Три байта в начале файла — и header() в PHP уже не работает, а в JSON появляется мусор перед фигурной скобкой. Два байта в конце строки — и shell-скрипт падает с bad interpreter. Clean BOM Senior делает удаление BOM и CRLF предсказуемым: побайтовая проверка, dry-run, атомарная запись и правило, по которому BOM в некоторых файлах трогать нельзя. Ниже — как это устроено и что показал прогон в песочнице с приманкой.

TL;DR: три вещи и одна проверка
- Что делает. Убирает BOM (UTF-8, UTF-16, UTF-32) и нормализует CRLF в LF.
- Чего не делает. Не трогает файлы, где BOM или CRLF обязательны — по правилу, а не по расширению.
- Как проверяется.
--dry-runпечатает список целей и ничего не меняет. - Как пишет. Атомарно, с сохранением прав и меток времени.
- Замер. В песочнице: 2 файла просканировано, 1 обработан, BOM снят, CRLF исправлен, приманка цела.
Проблема, которую это решает
BOM невидим в редакторе и виден компилятору. В PHP он превращается в вывод перед заголовками: Cannot modify header information. В JSON парсер спотыкается о первый символ. В shell-скриптах — bad interpreter, потому что ядро ищет #!/bin/sh в первых байтах, а находит BOM.
CRLF — обратная история. Файл, приехавший с Windows, содержит \r\n, и bash на нём падает с сообщением вида set: pipefail\r: invalid option name. Знакомо каждому, кто правил скрипты в Windows-редакторе.
Обе проблемы решаются руками, и оба раза плохо: массовая правка через sed без предпросмотра портит файлы, где BOM нужен, — например, .reg и некоторые конфиги Windows требуют его наличия.
Что такое Clean BOM Senior
flowchart TB
SCAN["обход дерева"] --> TYPE["определение типа файла"]
TYPE --> CHECK["побайтовая проверка BOM и CRLF"]
CHECK --> POLICY{"BOM допустим в этом типе?"}
POLICY -- да --> KEEP["оставить BOM, править только CRLF"]
POLICY -- нет --> STRIP["вырезать BOM"]
KEEP --> WRITE["атомарная запись"]
STRIP --> WRITE| Свойство | Значение |
|---|---|
| Тип | bash-скрипт clean-bom-senior.sh |
| Размер | 83 766 байт |
| Версия в скрипте | 3.0.0 |
| Версия релиза в репозитории | тег v1.0.0 |
| Зависимости | стандартные утилиты Unix |
| Платформы | Linux, macOS, Windows через WSL или Git Bash |
| Лицензия | MIT |
| Язык | bash, без внешних пакетов |
Расхождение версий — не опечатка: тег первого стабильного релиза помечен как v1.0.0, а сам скрипт и значки в README говорят 3.0.0. Это стоит держать в голове при выборе версии: ориентироваться на теги в репозитории и на вывод --version, а не на обложку.
Возможности
| Возможность | Что даёт |
|---|---|
| Детект BOM | UTF-8, UTF-16 и UTF-32 — по байтам, не по эвристике |
| Нормализация CRLF | перевод строк к LF |
| Поддержка типов | более пятидесяти расширений, включая .php, .js, .json, .yml |
--dry-run |
список целей без изменений |
| Атомарная запись | файл заменяется целиком, без частично записанных состояний |
| Сохранение прав | режим и владелец не меняются |
| Сохранение меток времени | дата файла остаётся прежней |
| Отчёт | сводка: сколько BOM, сколько CRLF, что пропущено |
| CI-режим | код выхода различает «чисто» и «требует правки» |
| Порт на PowerShell | для Windows без bash |
| npm-пакет | установка через npm |
Как это работает
flowchart LR DRY["dry-run: список целей"] --> REAL["боевой прогон"] REAL --> STAT["сводка: BOM, CRLF, пропуски"] STAT --> GATE["CI-проверка: код выхода"]
Порядок подчинён принципу «сначала покажи, потом делай».
Сначала обход: скрипт собирает файлы и определяет тип. Потом побайтовая проверка начала файла: если первые три байта EF BB BF — это UTF-8 BOM, другие последовательности означают UTF-16 или UTF-32. Отдельно проверяются окончания строк.
Дальше вступает правило: для части типов BOM допустим и даже нужен, и там он сохраняется — правится только CRLF. Для исполняемых и текстовых исходников BOM вырезается.
Запись атомарная: содержимое формируется целиком и подменяет файл, поэтому обрыв на середине не оставит половину файла. Права и метки времени восстанавливаются.
Замеры и цифры
Проверено 15.11.2026, двумя проверками.
| Что | Значение |
|---|---|
| Версия скрипта | clean-bom-senior.sh version 3.0.0 |
| Размер скрипта | 83 766 байт |
| Песочница | 2 файла: with-bom.php (BOM + CRLF) и чистая приманка canary-clean.txt |
Исходный with-bom.php |
19 байт, первые байты 239,187,191 (UTF-8 BOM), CRLF присутствует |
--dry-run |
файлов просканировано 2, к обработке 1, пропущено как чистые 1, ошибок 0 |
| Состояние после dry-run | файл не изменён: 19 байт, BOM на месте |
| Боевой прогон | BOM снято 1, CRLF исправлено 1, распределение: .php — 1 |
with-bom.php после |
14 байт, BOM отсутствует, CRLF отсутствует |
Приманка canary-clean.txt |
6 байт, не изменена |
| Страница репозитория | 200 |
| Страница релиза v1.0.0 | 200 |
| Страница npm-пакета | 403 — защита от автоматических запросов |

Разница 19 → 14 байт — это ровно три байта BOM плюс два байта CR (по одному на каждую из двух строк). Ничего лишнего не тронуто: приманка осталась байт в байт, а dry-run подтвердил, что чистый файл в работу не попадает. Арифметика сходится до байта, и это лучший аргумент, что инструмент не «переписывает файл на всякий случай».
Что прогон не показывает: поведение на UTF-16 и UTF-32, работу с бинарными файлами и точность правила «BOM допустим» для конкретных типов. Эти части заявлены в документации и требуют отдельной проверки под свои задачи.
Сильные стороны продукта
- Побайтовая проверка вместо эвристики. BOM определяется по сигнатуре, а не по «похоже на текст».
- Правило, а не «всё под нож». Файлы, где BOM нужен, остаются с ним.
- Dry-run по умолчанию безопасен. Список целей печатается до любых изменений.
- Атомарная запись. Нет состояний «файл наполовину перезаписан».
- Сохранение прав и дат. Инструмент не ломает метаданные проекта.
- Ноль зависимостей. Bash и стандартные утилиты.
- CI-режим. Код выхода годится как ворота в конвейере.
- Две платформы запуска. Bash и порт на PowerShell.
Установка
# из репозитория
git clone https://github.com/paulmann/Clean_BOM_Senior.git
cd Clean_BOM_Senior
# проверка версии
bash clean-bom-senior.sh --version
# предпросмотр по каталогу
bash clean-bom-senior.sh --dry-run /path/to/project
| Требование | Значение |
|---|---|
| bash | 4 и новее |
| Утилиты | стандартный набор Unix |
| Права | чтение и запись на целевые файлы |
| Windows | через WSL или Git Bash |
Настройка
flowchart TD
BOM["BOM в исполняемых файлах"] --> R{"опасно?"}
CRLF["CRLF в .bat и .cmd"] --> R2{"нужен?"}
R -- да --> FIX["удалить"]
R2 -- да --> KEEP2["сохранить CRLF"]| Что настроить | Как |
|---|---|
| Каталог обработки | аргументом, а не «всё подряд» |
| Отбор типов | по расширениям, которые нужны в проекте |
| Исключения | каталоги зависимостей и сборки — вне обхода |
| Режим CI | код выхода как проверка в конвейере |
| Права после записи | проверять, если проект под системным пользователем |
| Запуск в Windows | баш из WSL или Git Bash, но не «порт, лишь бы был» |
Практическое замечание про исключения: каталоги зависимостей (vendor, node_modules) в обход включать не нужно. Правка сторонних файлов ничего не улучшает, зато ломает воспроизводимость сборки.
Почему BOM вообще появляется
Откуда берутся три байта в начале файла — вопрос не праздный, потому что от ответа зависит способ борьбы.
Первое: редакторы Windows. Блокнот долгое время сохранял UTF-8 именно с BOM, и это поведение оставило след в тысячах репозиториев. Файл, созданный таким редактором, выглядит нормальным, а первый байт ломает PHP.
Второе: конвертеры кодировок. Любая утилита, переводящая cp1251 в UTF-8, может добавить метку — иногда по умолчанию, иногда по флагу, о котором никто не помнит.
Третье: генераторы кода и шаблонизаторы. Шаблон, сохранённый с BOM, выдаёт BOM в каждом сгенерированном файле — и это расползается по всему проекту.
Четвёртое: копирование фрагментов. Строка, скопированная из веб-формы или письма, иногда приносит невидимые символы.
Практический вывод: разовая чистка не решает проблему, если источник остаётся. Поэтому у инструмента есть CI-режим — он превращает «кто-то снова сохранил с BOM» в падение конвейера, а не в загадочную ошибку через неделю.
Что происходит с git
Массовая правка окончаний строк — это диф на весь файл, и здесь есть три момента, о которых лучше знать заранее.
Первый: core.autocrlf. Если в Windows-конфигурации включён режим true, git при чекауте снова превратит LF в CRLF, и правка откатится сама. Для репозиториев с bash-скриптами обычная настройка — input или false, плюс .gitattributes.
Второй: .gitattributes. Строка вида *.sh text eol=lf фиксирует правило на уровне репозитория и снимает проблему для всех, кто его клонирует.
Третий: история. После массовой правки git blame показывает одного автора на весь файл. Это не трагедия, но в проектах, где историю читают, лучше делать такую правку отдельным коммитом с понятным сообщением — тогда её легко пропустить при разборе.
Проверка после правки простая: git ls-files --eol показывает, что реально лежит в индексе и в рабочем дереве. Если там i/lf w/lf — всё получилось.
Что было в заметках к релизу и что добавилось здесь
Заметки первого стабильного выпуска — 5 939 знаков: перечень возможностей, безопасность операций, поддержка платформ. Как описание продукта они полны, но в них нет ни одного измерения и ни слова о том, где инструмент может навредить.
| Было в заметках | Добавлено в статье |
|---|---|
| список возможностей | разбор, что именно снимается и что остаётся |
| «сохраняет права и метки времени» | проверка на живом прогоне с приманкой |
| «dry-run» | конкретные числа: 2 просканировано, 1 к обработке |
| нет упоминания рисков | .bat, .cmd и конфиги Windows вынесены в подводные камни |
Отдельно зафиксировано расхождение версий: тег релиза v1.0.0, а скрипт сообщает 3.0.0. В заметках этого нет, а для читателя это практический вопрос — какую версию он ставит.
Подводные камни
- Версии расходятся. Тег v1.0.0, а скрипт сообщает 3.0.0 — сверяйтесь с
--version, а не с названием релиза. - BOM нужен не всегда, но иногда обязателен. Файлы конфигураций Windows без него могут не читаться.
- CRLF обязателен для
.batи.cmd. Нормализация в LF ломает пакетные файлы. - Git может «вернуть» CRLF. Настройка
core.autocrlfперезапишет файлы при следующем чекауте. - Бинарные файлы не трогать. Проверяйте, что обход их пропускает, особенно в проектах с картинками и архивами.
- Подпись коммита меняется. Массовая правка CRLF даст диф на весь файл — предупредите коллег.
- Метки времени сохраняются — это не всегда плюс. Системы сборки, ориентирующиеся на mtime, не заметят изменений.
- npm-страница отвечает 403 автоматике. Это защита от ботов, пакет при этом существует.
- Права root. Запуск от root по всему дереву системы — плохая идея: сначала dry-run и список.
- Кодировки кроме UTF. Скрипт про UTF-сигнатуры; файлы в других кодировках лучше проверять отдельно.
- Порт на PowerShell — не побайтовый близнец. Поведение может отличаться; проверяйте на своих файлах.
Как выглядит минимальный безопасный прогон
Порядок, который стоит соблюдать даже в знакомом проекте.
Сначала коммит. Не «потом посмотрю диф» — именно коммит, чтобы было куда вернуться одной командой.
Потом dry-run по каталогу, а не по всему дереву. Вывод покажет две вещи: сколько файлов найдено и какие именно будут обработаны. Если в списке оказались файлы, которых вы не ожидали, — остановитесь и разберитесь с отбором.
Дальше — боевой прогон по тому же каталогу. Сводка должна совпасть с предпросмотром: то же число файлов, тот же состав.
И проверка: два-три файла побайтово. Открыть в редакторе бесполезно — BOM там невидим, поэтому проверяют в терминале или скриптом. В PowerShell достаточно прочитать первые три байта и сравнить с 239,187,191. Такую проверку легко вставить в тест проекта: она ничего не стоит и ловит проблему до того, как её увидит пользователь.
После — сборка и тесты. Если проект на PHP, отдельно посмотреть, что страницы не начали отдавать пустую строку в начале вывода: это признак того, что где-то BOM остался.
Где инструмент не нужен
Границы стоит назвать, чтобы не превращать утилиту в обязательный ритуал.
Не нужен, когда файлов один-два: быстрее поправить руками.
Не нужен для бинарных файлов: там нет ни BOM как метки текста, ни окончаний строк в привычном смысле.
Не нужен как замена .gitattributes. Если CRLF приезжает регулярно, проблема не в файлах, а в настройках репозитория — и правка файлов без правки настроек будет повторяться.
И не нужен там, где кодировка не UTF: скрипт ищет UTF-сигнатуры, а не «любые невидимые байты».
Зато нужен в трёх случаях: массовая миграция старого проекта, проверка перед релизом и CI-шаг, который не даёт проблеме вернуться. На практике это выглядит так: один раз прогон по всему дереву, потом шаг в конвейере, который ловит единичные случаи — файл, сохранённый в чужом редакторе, или сгенерированный шаблон с меткой.
Чек-лист
- [ ] Сделать коммит или бэкап до массовой правки.
- [ ] Запустить
--dry-runи прочитать список целей. - [ ] Проверить, что в списке нет
.bat,.cmdи конфигов Windows. - [ ] Убедиться, что каталоги зависимостей исключены.
- [ ] Прогнать боевой прогон на одном каталоге, а не на всём диске.
- [ ] Побайтово проверить пару файлов: BOM нет, CRLF нет.
- [ ] Проверить, что права и владельцы файлов не изменились.
- [ ] Собрать проект и прогнать тесты.
- [ ] Добавить проверку в CI, чтобы проблема не вернулась.
- [ ] Проверить настройки git, чтобы CRLF не приехал обратно.
Проверка без утилиты: три команды
Полезно уметь проверить результат, не доверяя отчёту инструмента.
Первая: наличие BOM. В bash — head -c 3 file | od -An -tx1; при BOM вывод начинается с ef bb bf. В PowerShell — прочитать три байта и сравнить.
Вторая: окончания строк. file file покажет «CRLF line terminators» там, где остались Windows-переводы; grep -c $'\r' посчитает строки с \r.
Третья: права и владелец. stat -c '%a %U %G %y' file до и после прогона — сравнение покажет, не изменилось ли что-то, чего не ждали.
Эти три проверки занимают минуту и закрывают вопрос «а точно ли всё чисто». Отчёт утилиты — это её собственный взгляд на результат; независимая проверка на двух-трёх файлах надёжнее любого лога.
Что делать, если BOM остался после прогона
Три причины, в порядке частоты.
Первая: файл не попал в обход. Расширение не входит в список поддерживаемых, или каталог исключён. Проверьте вывод dry-run: его там не было.
Вторая: тип файла отнесён к тем, где BOM сохраняется. Это не ошибка, а правило; если вам нужно иначе — вопрос к политике инструмента, а не к его работе.
Третья: файл создан заново после прогона. Генератор, шаблон или скрипт сборки кладут BOM обратно — и тогда лечить надо источник, а не результат.
Отсюда и практика: чистку ставят перед сборкой и после неё проверяют, а не «один раз навели порядок».
FAQ
Что такое BOM и почему он мешает?
Это три байта в начале файла, помечающие кодировку. PHP считает их выводом и запрещает менять заголовки, JSON-парсеры спотыкаются, ядро не распознаёт shebang.
Утилита удаляет BOM везде?
Нет. Для части типов BOM сохраняется — именно потому, что там он нужен.
Чем опасен CRLF?
В shell-скриптах он превращает имя опции в pipefail\r и ломает запуск. В конфигах и .bat CRLF, наоборот, требуется.
Что делает dry-run?
Печатает список файлов, которые были бы обработаны, и ничего не меняет. В прогоне: 2 просканировано, 1 к обработке, 1 пропущен как чистый.
Сохраняются ли права и даты файлов?
Да, инструмент их сохраняет — это заявлено и проверяется на практике.
Можно ли использовать в CI?
Да: код выхода различает «всё чисто» и «требует правки», поэтому проверка ставится шагом конвейера.
Почему версия в скрипте 3.0.0, а релиз v1.0.0?
Так помечено в репозитории: тег первого стабильного релиза — v1.0.0, а внутренняя версия скрипта — 3.0.0. Ориентируйтесь на --version.
Что показывает сводка прогона
Отчёт утилиты короткий, но в нём есть всё нужное, если читать по порядку.
Первая строка — время выполнения. На двух файлах это секунды; на большом дереве счёт идёт на минуты, и это нормальный ориентир для планирования CI-шага.
Дальше — три числа: просканировано, к обработке, пропущено как чистые. В нашем прогоне 2 / 1 / 1. Если пропущенных ноль, а файлов в проекте сотни — стоит задуматься, тот ли каталог обрабатывается.
Потом блок «Issues Fixed»: сколько BOM снято и сколько CRLF исправлено. У нас по одному — ровно то, что было в тестовом файле.
И распределение по типам: .php — 1. Это подсказка для проверки: если в списке есть .bat или .cmd, значит правило для них не сработало так, как вы ожидали.
Завершает отчёт отметка времени. Она полезна в журнале CI: видно, когда шаг последний раз реально что-то правил. И если прогон ничего не изменил, это тоже результат — значит, проверка работает как сторож, а не как уборщик по расписанию.
Итог
Clean BOM Senior решает две невидимые проблемы, которые всплывают в самый неподходящий момент: BOM ломает заголовки и shebang, CRLF — shell-скрипты. Утилита делает это предсказуемо: побайтовая проверка, dry-run, атомарная запись и правило, по которому BOM в нужных файлах остаётся. Прогон в песочнице подтверждает: 2 файла просканировано, 1 обработан, BOM и CRLF сняты, файл уменьшился с 19 до 14 байт, приманка не тронута. Границы названы: .bat и .cmd требуют CRLF, конфиги Windows — иногда BOM, а версии в теге и в скрипте расходятся.
Цитата: Три невидимых байта дешевле убрать утилитой, чем искать причину «headers already sent» полдня.
Связанные материалы
- MD.Scribe 3.6.3: буквы в именах файлов и конфиг — ещё один разбор про невидимые причины сбоев.
- sr-search-replace: замена по дереву с журналом — массовая правка файлов с предпросмотром и откатом.
- ctf-collect-to-file: весь код в один документ — обход дерева и отбор файлов.
- Windows-LogOff 1.0.0: принудительный выход пользователя — утилита с
-WhatIfи структурным результатом. - Релиз v1.0.0 — заметки к первому стабильному выпуску.
LLM Summary
- Тема: Clean BOM Senior — bash-утилита для удаления UTF-8 BOM и нормализации CRLF в исходниках.
- Что делает: побайтовый детект BOM (UTF-8/16/32), перевод CRLF в LF, поддержка более 50 типов файлов, атомарная запись с сохранением прав и меток времени, dry-run, CI-режим, порт на PowerShell и npm-пакет.
- Ключевое правило: BOM сохраняется в типах, где он обязателен; удаляется в исполняемых и текстовых исходниках.
- Проверено 15.11.2026: скрипт
clean-bom-senior.sh— 83 766 байт,--versionсообщает 3.0.0 (тег релиза в репозитории — v1.0.0, расхождение зафиксировано). - Прогон в песочнице: 2 файла —
with-bom.php(19 байт, байтыEF BB BF, CRLF) и чистая приманка;--dry-run— просканировано 2, к обработке 1, пропущено 1, ошибок 0, файл не изменён; боевой прогон — BOM снято 1, CRLF исправлено 1,with-bom.phpстал 14 байт без BOM и CRLF, приманка осталась 6 байт без изменений. - Живая проверка: страница репозитория — 200, страница релиза — 200, страница npm-пакета — 403 (защита от автоматических запросов).
- Ограничения:
.bat/.cmdтребуют CRLF; конфиги Windows могут требовать BOM;core.autocrlfвернёт CRLF после чекаута; бинарные файлы обрабатывать нельзя. - Не проверялось: поведение на UTF-16 и UTF-32, точность правила BOM для конкретных типов, паритет PowerShell-порта.
- Ссылки: https://github.com/paulmann/Clean_BOM_Senior, https://github.com/paulmann/Clean_BOM_Senior/releases/tag/v1.0.0
Промт для агента (установка и настройка)
Готовый промт: скопируйте блок целиком. Источник шагов — README.md репозитория и собственный прогон в песочнице; файла AGENTS.md в проекте нет (проверено 15.11.2026).
Задача: убрать BOM и CRLF из исходников проекта, не задев файлы, где они обязательны.
Материалы:
- репозиторий: https://github.com/paulmann/Clean_BOM_Senior
- README: https://github.com/paulmann/Clean_BOM_Senior/blob/main/README.md
- релиз: https://github.com/paulmann/Clean_BOM_Senior/releases/tag/v1.0.0
Шаг 1. Сделать коммит или бэкап дерева.
Шаг 2. Проверить версию: bash clean-bom-senior.sh --version (в скрипте 3.0.0, тег релиза v1.0.0).
Шаг 3. Запустить dry-run по нужному каталогу: bash clean-bom-senior.sh --dry-run /path/to/project
Шаг 4. Прочитать список целей: в нём не должно быть .bat, .cmd и конфигов Windows.
Шаг 5. Убедиться, что каталоги зависимостей и сборки не в обходе.
Шаг 6. Выполнить боевой прогон по тому же каталогу.
Шаг 7. Побайтово проверить два-три файла: BOM отсутствует (первые байты не EF BB BF), CRLF отсутствует.
Шаг 8. Проверить права и владельца изменённых файлов.
Шаг 9. Собрать проект и прогнать тесты.
Шаг 10. Добавить проверку в CI, чтобы BOM и CRLF не вернулись.
Шаг 11. Проверить git config core.autocrlf, чтобы CRLF не приехал обратно при чекауте.
Запрещено:
- запускать без dry-run на незнакомом дереве;
- обрабатывать .bat и .cmd: им нужен CRLF;
- удалять BOM из файлов конфигураций Windows, где он обязателен;
- включать в обход vendor, node_modules и каталоги сборки;
- работать от root по системным каталогам без списка целей;
- считать, что порт на PowerShell ведёт себя так же, как bash-версия, без проверки.
Что считать успехом: dry-run показал ожидаемый список, боевой прогон дал ту же сводку, BOM и CRLF отсутствуют, приманки не тронуты, права сохранены, тесты зелёные, проверка в CI работает.