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

clean bom senior cover

TL;DR: три вещи и одна проверка

  1. Что делает. Убирает BOM (UTF-8, UTF-16, UTF-32) и нормализует CRLF в LF.
  2. Чего не делает. Не трогает файлы, где BOM или CRLF обязательны — по правилу, а не по расширению.
  3. Как проверяется. --dry-run печатает список целей и ничего не меняет.
  4. Как пишет. Атомарно, с сохранением прав и меток времени.
  5. Замер. В песочнице: 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 — защита от автоматических запросов
Clean BOM Senior: прогон в песочнице и результаты

Разница 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» полдня.

Связанные материалы

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 работает.