Проверка pre-commit на повреждения концов строк и кодировки: check-diff-artifacts
check-diff-artifacts.sh — это хук pre-commit, который читает индексированный дифф и отказывает в одном виде изменений: в повреждениях на уровне байтов, которые оставляют скриптовые правки. Скрипт на Python, переписавший страницу в текстовом режиме, теряет её концы строк CRLF, редактор добавляет BOM, файл, прочитанный не в той кодировке, возвращается кракозябрами (по-английски mojibake): байты одной кодировки показаны символами другой, и Привет превращается в Привет. Ничего из этого никогда не делают намеренно, поэтому хук может останавливать такие изменения без исключений. Всё остальное проходит, в том числе правки одних пробелов и переписывания, меняющие каждую строку, например перевод или заново созданная карта сайта. Файл, единственное изменение которого — перевод с CRLF на LF, тоже проходит, поэтому репозиторий может перевести на LF все свои файлы.
Здесь хук подключается во временном репозитории, и каждое правило запускается с настоящим выводом. Инструменты: git 2.43.0, bash 5.2, GNU grep 3.11, iconv из glibc 2.39, фреймворк pre-commit 4.6.2 и Python 3.12 для правок, которые наносят повреждения. Как эта версия заменила первую и как её проверили на всей истории репозитория, рассказано в статье Как переделать проверку pre-commit, чтобы она срабатывала только на настоящие повреждения. Первая версия и её ошибка с git diff -w описаны в статье Проверка pre-commit, которая остановила верный коммит.
Что она останавливает и что пропускает
Каждое правило сравнивает новую сторону файла с базовой: с версией в HEAD для индексированного изменения, с родителем для коммита. Повреждение, которое уже есть в базе, никогда не роняет следующий коммит. Находка, которая останавливает коммит, печатается как ARTIFACT, и скрипт завершается с кодом 1.
| Правило | Типичная причина |
|---|---|
| потерян CRLF в файле с CRLF вместе с другими изменениями | переписывание через Python или sed в текстовом режиме, которое заодно правит файл |
| в файле с одним стилем концов строк они стали смешанными | строка, дописанная через echo в файл с CRLF, фрагмент с CRLF, вставленный в файл с LF |
| файл с LF переведён на CRLF | редактор, настроенный на концы строк Windows |
| в существующий файл добавлены символы замены U+FFFD | декодирование с errors='replace' |
| кракозябры: 10 и больше новых последовательностей двойного кодирования | UTF-8 прочитан как cp1252, latin-1 или cp1251 и сохранён снова |
| правильный файл UTF-8 перестал быть правильным UTF-8 | страница сохранена в cp1251 или latin-1 |
| BOM UTF-8 добавлен в существующий файл, или новый файл PHP с BOM | редактор, настроенный на «UTF-8 с BOM»; PHP выводит BOM раньше любого заголовка |
Находка, которая не останавливает коммит, печатается как NOTE, и код завершения остаётся 0:
| Изменение | Отчёт |
|---|---|
| перевод с CRLF на LF и ничего больше, в том числе при переносе | NOTE |
| только пробелы: отступы, пробелы в конце строк, серия пробелов | NOTE |
| замена 1:1 многих строк: перевод, путь, изменённый в каждой строке, заново созданный файл | ничего |
| BOM удалён | NOTE |
| одиночные CR удалены из файла, где почти везде LF | NOTE |
| новый файл со смешанными концами строк, U+FFFD или (не PHP) BOM: портить нечего, базы нет | NOTE |
| неотслеживаемые, удалённые и двоичные файлы, символьные ссылки и подмодули | пропускаются |
Подключение
Пример работает в новом репозитории. Сам скрипт приведён в конце страницы; сохраните его как tools/check-diff-artifacts.sh:
git init -q demo && cd demo
git config user.email you@example.com && git config user.name You
mkdir -p tools
vi tools/check-diff-artifacts.sh
chmod +x tools/check-diff-artifacts.sh
Хук — локальная запись фреймворка pre-commit. Весь индексированный дифф он читает сам, поэтому работает при каждом коммите и не принимает имён файлов:
vi .pre-commit-config.yaml
repos: - repo: local hooks: - id: check-diff-artifacts name: check-diff-artifacts (staged) entry: tools/check-diff-artifacts.sh --staged language: system always_run: true pass_filenames: false
pre-commit install
pre-commit installed at .git/hooks/pre-commit
Четыре страницы для примера: одна с концами строк CRLF, какие бывают у файла, впервые сохранённого в Windows, одна из 120 строк, одна на русском и короткий список:
printf '<?php\r\n// A page first saved on Windows\r\n$title = "Old title";\r\necho $title;\r\n' > legacy.php
for i in $(seq 1 120); do echo "<p>Draft note $i</p>"; done > notes.html
mkdir -p ru && printf '<h1>О проекте</h1>\n<p>Привет! Это страница о проекте, она написана по-русски.</p>\n' > ru/about.html
printf '<ul>\n <li>one</li>\n <li>two</li>\n</ul>\n' > list.html
git add . && git commit -qm "Adds the pages"
check-diff-artifacts (staged)............................................Passed
git ls-files --eol показывает стиль концов строк, который git видит в индексе (i/) и в рабочем дереве (w/):
git ls-files --eol
i/lf w/lf attr/ .pre-commit-config.yaml i/crlf w/crlf attr/ legacy.php i/lf w/lf attr/ list.html i/lf w/lf attr/ notes.html i/lf w/lf attr/ ru/about.html i/lf w/lf attr/ tools/check-diff-artifacts.sh
Концы строк
Самое частое повреждение: скрипт меняет одну строку страницы с CRLF и записывает весь файл обратно с LF. Python делает так по умолчанию: файл, открытый в текстовом режиме, при чтении превращает каждый \r\n в \n, а в Linux записывает обратно \n:
python3 -c "p = 'legacy.php'; t = open(p).read(); open(p, 'w').write(t.replace('Old title', 'New title'))"
git add legacy.php
git commit -qm "Renames the page title"
check-diff-artifacts (staged)............................................Failed - hook id: check-diff-artifacts - exit code: 1 ARTIFACT: legacy.php [staged]: CRLF line endings lost (base CRLF on all 4 lines, now LF) together with other changes; a conversion alone passes check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
Последняя строка указывает на документацию репозитория, из которого взят скрипт; поменяйте этот путь в скрипте на свой. Коммит не состоялся. Отчёт заодно говорит, что прошло бы: тот же файл, переведённый на LF без смены заголовка, — так файл и переходит на LF. Здесь смысл правки в заголовке, поэтому исправление возвращает возвраты каретки. С newline='' Python читает и пишет концы строк как есть, и именно так правку и надо было делать с самого начала:
python3 -c "p = 'legacy.php'; t = open(p, newline='').read(); open(p, 'w', newline='').write(t.replace('\n', '\r\n'))"
git add legacy.php
git diff --cached --numstat
1 1 legacy.php
Изменилась одна строка вместо четырёх: только заголовок. Коммит проходит:
git commit -qm "Renames the page title"
check-diff-artifacts (staged)............................................Passed
Потеря лишь части концов строк тоже ловится. Строка, дописанная через echo, заканчивается на LF, и файл с CRLF становится смешанным:
echo '<p>Added later</p>' >> legacy.php
git add legacy.php
tools/check-diff-artifacts.sh --staged
ARTIFACT: legacy.php [staged]: mixed line endings, 1 of 5 lines now end in LF in a CRLF file check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
sed даёт каждой строке ровно один CR. \r* не даёт удвоить CR в строках, где он уже есть:
sed -i 's/\r*$/\r/' legacy.php
git add legacy.php
tools/check-diff-artifacts.sh --staged
check-diff-artifacts: clean
git commit -qm "Adds a line to the old page"
check-diff-artifacts (staged)............................................Passed
Перенос, который меняет концы строк
Лучше всего повреждение прячется при переносе: старый путь исчезает, и файл выглядит новым. Скрипт следует за распознаванием переименований в git и сравнивает перенесённый файл с его источником. Здесь страница переезжает в pages/, одна её строка правится, и по дороге она теряет CRLF:
mkdir -p pages && git mv legacy.php pages/legacy.php
sed -i 's/\r$//; s/Added later/Added later, moved/' pages/legacy.php && git add pages/legacy.php
git status --short
R legacy.php -> pages/legacy.php
tools/check-diff-artifacts.sh --staged
ARTIFACT: pages/legacy.php (from legacy.php) [staged]: CRLF line endings lost (base CRLF on all 5 lines, now LF) together with other changes; a conversion alone passes check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
sed -i 's/\r*$/\r/' pages/legacy.php && git add pages/legacy.php
tools/check-diff-artifacts.sh --staged
check-diff-artifacts: clean
git commit -qm "Moves the old page to pages/"
check-diff-artifacts (staged)............................................Passed
Перенос, который только переводит файл на LF, без правки, проходит с заметкой, как любой другой перевод. Git считает удалённый и добавленный файлы переименованием, когда они похожи хотя бы на 50%. Перенос, который заодно переписывает большую часть файла, выглядит как новый файл, а новому файлу не с чем сравниваться: см. Ограничения.
Повреждение кодировки
Кракозябры. Скрипт, открывший файл UTF-8 как cp1251, читает каждую русскую букву как два символа Windows и сохраняет их в UTF-8. Страница остаётся правильным UTF-8, но текста больше нет:
python3 -c "p = 'ru/about.html'; t = open(p, encoding='cp1251').read(); open(p, 'w', encoding='utf-8').write(t.replace('<h1>', '<h1 id=\"top\">'))"
head -n 2 ru/about.html
<h1 id="top">Рћ проекте</h1> <p>Привет! Рто страница Рѕ проекте, РѕРЅР° написана РїРѕ-СЂСѓСЃСЃРєРё.</p>
git add ru/about.html
tools/check-diff-artifacts.sh --staged
ARTIFACT: ru/about.html [staged]: mojibake introduced (0 -> 42 double-encoded sequences: UTF-8 read as cp1252, latin-1 or cp1251 and saved again) check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
Надёжнее всего повреждение кодировки исправляет закоммиченная версия: верните её и повторите правку с правильной кодировкой. git restore --staged --worktree сбрасывает и индекс, и файл:
git restore --staged --worktree ru/about.html
Файл, сохранённый в другой кодировке. iconv переводит страницу в cp1251, как сделал бы старый редактор:
iconv -f utf-8 -t cp1251 ru/about.html > ru/about.tmp && mv ru/about.tmp ru/about.html
git add ru/about.html
tools/check-diff-artifacts.sh --staged
ARTIFACT: ru/about.html [staged]: no longer valid UTF-8 (illegal input sequence at position 4), saved in another encoding? check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
git restore --staged --worktree ru/about.html
BOM. Три байта EF BB BF в начале файла PHP уходят в браузер раньше любого заголовка, который ставит страница:
printf '\xef\xbb\xbf' | cat - pages/legacy.php > legacy.tmp && mv legacy.tmp pages/legacy.php
git add pages/legacy.php
tools/check-diff-artifacts.sh --staged
ARTIFACT: pages/legacy.php [staged]: UTF-8 BOM added (PHP prints it before any header) check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
git restore --staged --worktree pages/legacy.php
Что проходит
Правка одних пробелов попадает в отчёт, чтобы её не пропустили, но это изменение, которое кто-то сделал намеренно, и коммит проходит. Здесь у списка отступ становится в два пробела:
sed -i 's/^ / /' list.html
git add list.html
tools/check-diff-artifacts.sh --staged
NOTE: list.html [staged]: whitespace-only change (2+/2-: indentation, trailing spaces), not blocking check-diff-artifacts: clean (1 note(s), not blocking)
git commit -qm "Indents the list with two spaces"
check-diff-artifacts (staged)............................................Passed
Фреймворк показывает вывод хука только при ошибке, поэтому заметка видна, когда скрипт запускают вручную. Переписывание, которое меняет каждую строку файла, столько же добавленных строк, сколько удалённых, — такое же обычное дело. Построчный перевод или карта сайта с новыми датами выглядят так же:
sed -i 's/Draft/Final/' notes.html
git add notes.html
git diff --cached --numstat
120 120 notes.html
tools/check-diff-artifacts.sh --staged
check-diff-artifacts: clean
git commit -qm "Marks the notes final"
check-diff-artifacts (staged)............................................Passed
Проверка без коммита
Скрипт принимает одну опцию, которая задаёт, какие две стороны он сравнивает:
| Команда | База | Новая сторона |
|---|---|---|
| check-diff-artifacts.sh | индекс | рабочее дерево: неиндексированные изменения |
| check-diff-artifacts.sh --staged | HEAD | индекс: то, что запишет следующий коммит |
| check-diff-artifacts.sh --all | HEAD | рабочее дерево: индексированные и неиндексированные изменения вместе |
| check-diff-artifacts.sh --commit REV | первый родитель REV | REV, уже сделанный коммит |
Без опции скрипт проверяет правку ещё до индексации:
python3 -c "p = 'pages/legacy.php'; t = open(p).read(); open(p, 'w').write(t.replace('New title', 'Newer title'))"
tools/check-diff-artifacts.sh
ARTIFACT: pages/legacy.php [worktree]: CRLF line endings lost (base CRLF on all 5 lines, now LF) together with other changes; a conversion alone passes check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
git commit --no-verify пропускает все хуки, и повреждение попадает в историю. --commit находит его там:
git commit --no-verify -qam "Renames the page title again"
tools/check-diff-artifacts.sh --commit HEAD
ARTIFACT: pages/legacy.php [commit b3b09761b]: CRLF line endings lost (base CRLF on all 5 lines, now LF) together with other changes; a conversion alone passes check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
Новый коммит, который вернёт CRLF, сам будет переводом с LF на CRLF, и хук его остановит. Пока коммит не отправлен на сервер, лучше его разобрать. git reset --soft HEAD~1 убирает коммит и оставляет его изменения в индексе. Базой снова становится хорошая версия:
git reset --soft HEAD~1
sed -i 's/\r*$/\r/' pages/legacy.php && git add pages/legacy.php
tools/check-diff-artifacts.sh --staged
check-diff-artifacts: clean
git commit -qm "Renames the page title again"
check-diff-artifacts (staged)............................................Passed
Если повреждённый коммит уже отправлен, правка осталась в истории, а файл теперь в LF. LF — это нормально: следующий раздел переводит файлы на LF намеренно. Исправление нужно только файлу, которому обязательно нужен CRLF, и такое исправление — намеренное срабатывание.
Перевод файлов на LF
Файл, единственное изменение которого — перевод с CRLF на LF, не повреждён: прятать в нём нечего. Хук проверяет, что новый файл — это ровно база, из которой убран возврат каретки перед каждым переводом строки, и пропускает его с заметкой. git ls-files --eol перечисляет файлы, которые в индексе хранятся с CRLF:
git ls-files --eol | awk '$1 == "i/crlf" {print $NF}'
pages/legacy.php
sed -i 's/\r$//' pages/legacy.php && git add pages/legacy.php
git diff --cached --numstat
5 5 pages/legacy.php
tools/check-diff-artifacts.sh --staged
NOTE: pages/legacy.php [staged]: converted from CRLF to LF, nothing else changed (5 lines) check-diff-artifacts: clean (1 note(s), not blocking)
git commit -qm "Converts pages/legacy.php to LF"
check-diff-artifacts (staged)............................................Passed
git ls-files --eol pages/legacy.php
i/lf w/lf attr/ pages/legacy.php
Изменилась каждая строка, и это нормально, потому что больше не изменилось ничего. Переводите файлы в коммитах, которые только переводят, в большом репозитории — по папкам, а правьте файлы в других коммитах: перевод и правка одного файла в одном коммите — это то, что остановил первый пример.
Когда всё переведено на LF, файл .gitattributes сохраняет это состояние. text=auto оставляет git решать, какие файлы текстовые, а eol=lf хранит их с LF, что бы ни записал редактор:
printf '* text=auto eol=lf\n' > .gitattributes && git add .gitattributes && git commit -qm "Keeps text files LF"
check-diff-artifacts (staged)............................................Passed
printf 'one\r\ntwo\r\n' > win.txt && git add win.txt
warning: in the working copy of 'win.txt', CRLF will be replaced by LF the next time Git touches it
git ls-files --eol win.txt
i/lf w/crlf attr/text=auto eol=lf win.txt
В индексе лежит LF (i/lf), хотя на диске у файла CRLF (w/crlf), поэтому правилам хука о концах строк в индексе больше нечего искать; правила о кодировке продолжают работать. Файл, которому на диске обязательно нужен CRLF, например пакетный файл Windows, получает свою строку. Git по-прежнему хранит его с LF и пишет CRLF, когда извлекает файл:
printf '*.bat text eol=crlf\n' >> .gitattributes && git add .gitattributes && git commit -qm "Keeps batch files CRLF in the working tree"
check-diff-artifacts (staged)............................................Passed
printf '@echo off\r\necho Building\r\n' > run.bat && git add run.bat
git ls-files --eol run.bat
i/lf w/crlf attr/text eol=crlf run.bat
git commit -qm "Adds run.bat"
check-diff-artifacts (staged)............................................Passed
Намеренное срабатывание
Переводу на LF пропуск не нужен. Нужных срабатываний осталось немного: возврат CRLF после отправленного повреждения или страница, которая намеренно показывает кракозябры. Здесь русская страница получает пример неверного декодирования, построенный во время запуска из нормального текста, и хук, как обычно, останавливает коммит:
python3 -c "p = 'ru/about.html'; s = 'Привет! Это страница о проекте.'.encode().decode('cp1251'); open(p, 'a', encoding='utf-8').write('<p>A wrong decode looks like this: ' + s + '</p>\n')"
git add ru/about.html
git commit -qm "Shows a wrong decode on the about page"
check-diff-artifacts (staged)............................................Failed - hook id: check-diff-artifacts - exit code: 1 ARTIFACT: ru/about.html [staged]: mojibake introduced (0 -> 21 double-encoded sequences: UTF-8 read as cp1252, latin-1 or cp1251 and saved again) check-diff-artifacts: 1 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
Переменная SKIP фреймворка пропускает только этот хук и запускает все остальные. Второй -m объясняет в коммите, почему хук пропущен:
SKIP=check-diff-artifacts git commit -qm "Shows a wrong decode on the about page" -m "Committed with SKIP=check-diff-artifacts: the mojibake sample is intended."
check-diff-artifacts (staged)...........................................Skipped
git commit --no-verify тоже сработал бы, но пропустил бы вместе с ним и все остальные проверки. Оставьте его для сломанного хука.
Как устроены проверки
Какие файлы и какие стороны. Один вызов git diff --raw перечисляет изменённые файлы с идентификаторами блобов обеих сторон. -z оставляет пути без кавычек, поэтому имя с кириллицей или пробелами доходит до проверок как есть. -M собирает пары переименований, а --no-abbrev печатает полные идентификаторы. Идентификатор из одних нулей означает «файл в рабочем дереве»:
while IFS= read -r -d '' meta; do IFS= read -r -d '' path || break src="" read -r smode dmode ssha dsha status <<< "${meta#:}" case "$status" in R*|C*) src="$path"; IFS= read -r -d '' path || break ;; esac ... check_file "$path" "$src" "$ssha" "$dsha" done < <("${GIT_DIFF[@]}" --raw --no-abbrev "${RANGE[@]}")
На месте ... стоит пропуск символьных ссылок, подмодулей и чистых переименований. Каждая сторона записывается во временный файл через git cat-file blob <id>. Файл, который --numstat в git показывает как двоичный, с - вместо числа строк, пропускается.
Концы строк. Для каждой стороны скрипт считает строки (wc -l) и строки, которые заканчиваются на CR (grep -c $'\r$'), и называет стиль: lf, когда CR нет ни в одной строке, crlf, когда он есть в каждой, mixed в остальных случаях. Вердикт выносится по паре стилей:
| База | Новая сторона | Отчёт |
|---|---|---|
| crlf | lf | NOTE, если убраны только CR, иначе ARTIFACT: потерян CRLF |
| crlf | mixed | ARTIFACT: смешанные концы строк |
| lf | crlf | ARTIFACT: смена LF на CRLF |
| lf | mixed | ARTIFACT: смешанные концы строк |
| mixed, половина или больше с CRLF | lf | NOTE, если убраны только CR, иначе ARTIFACT: потерян CRLF |
| mixed, почти везде LF | lf | NOTE: одиночные CR удалены |
| нет (новый файл) | mixed | NOTE |
| одинаковый стиль с обеих сторон | ничего |
«Убраны только CR» — это одно точное сравнение: база, из которой sed убрал CR перед каждым переводом строки, должна байт в байт совпасть с новым файлом. Один изменённый пробел где угодно — и сравнение не проходит:
only_cr_removed() { LC_ALL=C sed 's/\r$//' "$1" | cmp -s - "$2"; }
Проверка работает в одну сторону. Перевод с LF на CRLF всегда останавливается, потому что цель — репозиторий, который в итоге весь в LF. Если ни на одной стороне нет ни одного CR, число строк вообще не нужно, и в репозиториях с LF проверка остаётся быстрой.
Кодировка. Новая сторона только из ASCII не может нести повреждение кодировки и пропускает следующие проверки. В остальных случаях:
- U+FFFD — это последовательность байтов EF BF BD; скрипт сравнивает число строк, где она есть, на обеих сторонах.
- Кракозябры считаются по шаблонам байтов, которых не бывает в настоящем тексте: ведущий байт UTF-8, прочитанный как cp1252 или latin-1 (Ã, за которым идёт ©, вместо é), ведущий байт кириллицы, прочитанный как cp1251 (Р или С, за которыми идёт символ, которого русский текст на этом месте не ставит), и то же для тире и кавычек. Пары, которые в настоящем русском тексте встречаются, например С° или С…, из шаблона исключены. Нужно десять новых последовательностей: статья, которая цитирует одно слово кракозябрами, это 2–6 последовательностей, проходит, а в одной испорченной строке русского текста их двадцать и больше.
- Правильность UTF-8 проверяет iconv -f UTF-8 -t UTF-8: он падает на первом неверном байте и сообщает, где. Считается только база, которая была правильной, поэтому старые файлы в другой кодировке можно по-прежнему править.
- BOM — это три байта в начале файла.
Пробелы. Файл, дифф которого исчезает под git diff -b, получает заметку о пробелах. Именно -b, а не -w, потому что -w прячет и пробел, удалённый между двумя словами: история этой ошибки — в статье Проверка pre-commit, которая остановила верный коммит.
В скрипте есть два исключения для репозитория, для которого он написан: файл ленты, который хук post-commit переписывает целиком, и собранные наборы CSS, которые наследуют концы строк своих исходников. Оба заданы шаблоном пути в case; поменяйте или удалите их для своего репозитория.
Тесты
Тесты устроены так же, как у других проверок: на каждый тест — временный репозиторий git, в нём запускается настоящий скрипт с --staged, проверяются код завершения и отчёт. Случаи повреждений собраны в одну таблицу из базового содержимого, нового содержимого и ожидаемого сообщения; здесь она сокращена до основных случаев. Повреждённое содержимое строится во время запуска, поэтому в самом файле тестов нет ни кракозябр, ни U+FFFD, которые нашёл бы хук:
@pytest.mark.parametrize( ("base", "new", "message"), [ (crlf(LONG), EDITED, "CRLF line endings lost (base CRLF on all 150 lines, now LF) together with other changes"), (crlf(LONG), crlf(LONG) + b"added with LF\n", "mixed line endings, 1 of 151 lines now end in LF"), (LONG, crlf(LONG), "line endings flipped from LF to CRLF"), (LONG, LONG + b"pasted\r\n", "mixed line endings, 1 of 151 lines now end in CRLF"), (ORIGINAL, ORIGINAL + "bad \N{REPLACEMENT CHARACTER} byte\n".encode(), "U+FFFD replacement chars introduced"), ( RUSSIAN.encode(), RUSSIAN.encode().decode("cp1251").encode(), "mojibake introduced", ), (RUSSIAN.encode(), RUSSIAN.encode("cp1251"), "no longer valid UTF-8"), (ORIGINAL, b"\xef\xbb\xbf" + ORIGINAL, "UTF-8 BOM added"), ], ) def test_damage_is_blocked(repo, base, new, message): result = gate(repo, base, new, "damaged.txt") assert result.returncode == 1, out(result) assert message in out(result)
Тот же файл проверяет, что обычные изменения проходят: перевод на LF с заметкой, в том числе смешанного и перенесённого файла, замена 1:1 150 строк с LF и с CRLF, правка файла с CRLF, где концы строк сохранены, перевод 120 строк, одно процитированное слово кракозябрами, правка старого файла в cp1251. Перевод с одним лишним пробелом по-прежнему останавливается. Остальные тесты проверяют переименования, путь с кириллицей, четыре режима и неверную опцию:
python -m pytest tests/linters/test_check_diff_artifacts_sh.py -v
tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[crlf-lost-with-edit] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[crlf-lost-with-space-edit] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[crlf-file-gets-lf-line] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[lf-to-crlf] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[lf-file-gets-crlf-line] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[fffd] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[mojibake-cp1251] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[mojibake-latin1] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[saved-as-cp1251] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_damage_is_blocked[bom-added] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_whitespace_only_diff_is_a_note[trailing] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_whitespace_only_diff_is_a_note[tab-indent] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_whitespace_only_diff_is_a_note[space-run] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_space_removed_inside_a_line_passes PASSED tests/linters/test_check_diff_artifacts_sh.py::test_ordinary_changes_pass[1to1-rewrite-lf] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_ordinary_changes_pass[1to1-rewrite-crlf] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_ordinary_changes_pass[crlf-kept] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_ordinary_changes_pass[translation] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_ordinary_changes_pass[one-mojibake-sample] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_ordinary_changes_pass[legacy-cp1251-edit] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_bom_removed_is_a_note PASSED tests/linters/test_check_diff_artifacts_sh.py::test_new_file_findings_are_notes[mixed-endings] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_new_file_findings_are_notes[fffd] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_new_file_findings_are_notes[bom] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_new_php_file_with_bom_is_blocked PASSED tests/linters/test_check_diff_artifacts_sh.py::test_conversion_to_lf_is_a_note[crlf] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_conversion_to_lf_is_a_note[mostly-crlf-mixed] PASSED tests/linters/test_check_diff_artifacts_sh.py::test_renamed_and_converted_file_is_a_note PASSED tests/linters/test_check_diff_artifacts_sh.py::test_feed_json_line_endings_are_exempt PASSED tests/linters/test_check_diff_artifacts_sh.py::test_generated_css_line_endings_are_a_note PASSED tests/linters/test_check_diff_artifacts_sh.py::test_binary_file_is_skipped PASSED tests/linters/test_check_diff_artifacts_sh.py::test_renamed_file_is_compared_with_its_source PASSED tests/linters/test_check_diff_artifacts_sh.py::test_non_ascii_path_is_checked PASSED tests/linters/test_check_diff_artifacts_sh.py::test_all_mode_sees_unstaged_changes PASSED tests/linters/test_check_diff_artifacts_sh.py::test_commit_mode_audits_a_commit PASSED tests/linters/test_check_diff_artifacts_sh.py::test_unknown_argument_is_a_usage_error PASSED ============================= 36 passed in 22.90s ==============================
Ограничения
- Мелкие кракозябры проходят. Меньше десяти новых последовательностей, например один испорченный короткий заголовок, — ниже порога. Страница, которая намеренно цитирует целое предложение кракозябрами, выше порога, и ей нужен пропуск.
- Перенос с большой переделкой — новый файл. При сходстве ниже 50% git не связывает два пути, и новый файл получает только проверки для новых файлов.
- Новые файлы не судятся. Смешанные концы строк, U+FFFD или BOM в новом файле — заметки, кроме BOM в новом файле PHP.
- Смешанные файлы остаются смешанными. Файл, который уже был смешанным, падает только тогда, когда почти весь был в CRLF и стал целиком в LF.
- Перевод и правка одного файла — два коммита. В одном коммите перевод прячет правку, и хук его останавливает.
- Закоммиченное повреждение исправляется сменой концов строк. Неотправленный коммит отмените через git reset --soft HEAD~1; после отправки закоммитьте исправление с пропуском.
- Требования. GNU grep с -P для правила о кракозябрах и iconv для правила о UTF-8. Без одного из них это правило пропускается с сообщением в стандартный поток ошибок.
Скрипт
Скрипт целиком, версия 0.2.0. Сохраните его как tools/check-diff-artifacts.sh и сделайте исполняемым, как в разделе Подключение:
#!/usr/bin/env bash # version 0.2.0 # Block the byte-level damage that scripted rewrites (sed, Python # read/write round trips, editors) leave in a diff, and nothing else. # # Blocking (ARTIFACT, exit 1), each judged against the base side: # 1. line endings: CRLF lost in a CRLF file together with other changes, # an LF file flipped to CRLF, or a file with one ending style left with # mixed endings. A file whose only change is CRLF -> LF passes with a # NOTE, so a repository can move to LF in conversion-only commits. # 2. U+FFFD replacement chars introduced into an existing file (a lossy # decode) # 3. mojibake introduced: UTF-8 decoded as cp1252/latin-1 or cp1251 and # written back, 10 or more new sequences (an e-acute turned into # A-tilde + copyright sign, Russian turned into runs of R/S pairs) # 4. a valid UTF-8 file no longer valid UTF-8 (saved as cp1251/latin-1) # 5. a UTF-8 BOM added to an existing file or to a new PHP file (PHP # prints it before any header) # Not blocking (NOTE, exit stays 0): whitespace-only diffs, a BOM removed, # stray CRs dropped from a mostly-LF file, and a new file with mixed endings, # U+FFFD or (not PHP) a BOM: a new file has no base to be damaged against. # A 1:1 rewrite of many lines (translation, path rename, regenerated # sitemap) is an ordinary change and is not reported: the EOL and encoding # checks above catch the damage the old "full-file rewrite" rule stood for. # The rolling feed JSON files skip the line-ending and whitespace checks: # the feed writer serializes them whole. Generated CSS concatenations # (css_pipeline/build/) take their line endings from their sources, which # are checked themselves, so a line-ending hit there is only a NOTE. # # Usage: # check-diff-artifacts.sh [--staged | --all | --commit REV] # (default) unstaged changes: index -> working tree # --staged what the next commit records: HEAD -> index (pre-commit) # --all HEAD -> working tree, staged and unstaged together # --commit REV an existing commit: its first parent -> REV # Exit 0 when clean (notes allowed), 1 when artifacts are found, 2 on a # usage error. Untracked, deleted, binary, symlink and submodule entries # are skipped. A renamed or copied file is compared with its source. set -u usage() { sed -n '/^# Usage:/,/^# are skipped/{s/^# \{0,1\}//;p}' "$0"; } MODE="worktree" REV="" while [ $# -gt 0 ]; do case "$1" in --staged) MODE="staged" ;; --all) MODE="all" ;; --commit) if [ $# -lt 2 ]; then usage >&2; exit 2; fi MODE="commit"; REV="$2"; shift ;; --commit=*) MODE="commit"; REV="${1#--commit=}" ;; -h|--help) usage; exit 0 ;; *) echo "check-diff-artifacts: unknown argument: $1" >&2; usage >&2; exit 2 ;; esac shift done cd "$(git rev-parse --show-toplevel)" || exit 2 EMPTY_TREE=$(git hash-object -t tree /dev/null) head_or_empty() { if git rev-parse -q --verify HEAD >/dev/null; then echo HEAD; else echo "$EMPTY_TREE"; fi } # The same pairs for --raw (blob ids), --numstat and -b --numstat. case "$MODE" in worktree) LABEL="worktree"; RANGE=(--diff-filter=ACM) ;; staged) LABEL="staged"; RANGE=(--cached -M --diff-filter=ACMR "$(head_or_empty)") ;; all) LABEL="all"; RANGE=(-M --diff-filter=ACMR "$(head_or_empty)") ;; commit) if ! COMMIT=$(git rev-parse -q --verify "$REV^{commit}"); then echo "check-diff-artifacts: not a commit: $REV" >&2; exit 2 fi PARENT=$(git rev-parse -q --verify "$COMMIT^1") || PARENT="$EMPTY_TREE" LABEL="commit ${COMMIT:0:9}" RANGE=(-M --diff-filter=ACMR "$PARENT" "$COMMIT") ;; esac GIT_DIFF=(git diff -z --no-ext-diff --no-color) TMP=$(mktemp -d) || exit 2 trap 'rm -rf "$TMP"' EXIT HAVE_PCRE=1 printf 'x\n' | LC_ALL=C grep -qP 'x' 2>/dev/null || HAVE_PCRE=0 HAVE_ICONV=1 command -v iconv >/dev/null 2>&1 || HAVE_ICONV=0 # Double-encoded UTF-8, as bytes (this file stays ASCII so it never matches # itself). Latin: a lead byte C2-DF read as cp1252 or latin-1 (U+00C2-U+00DF) # followed by what its continuation byte turns into; E2 80 xx punctuation # (dashes, quotes) read as cp1252 or latin-1. Cyrillic: a lead D0/D1 read as # cp1251 (U+0420/U+0421) followed by what the second byte turns into, minus # the pairs real Russian text has (before NBSP, guillemets, degree, ellipsis, # dashes, quotes, yo); E2 80 xx punctuation read as cp1251. MOJIBAKE='\xC3[\x82-\x9F](?:\xC2[\x80-\xBF]|\xE2\x80[\x93-\xBA]|\xE2\x82\xAC|\xE2\x84\xA2|\xC5[\x92\x93\xA0\xA1\xB8\xBD\xBE]|\xC6\x92|\xCB[\x86\x9C])|\xC3\xA2(?:\xE2\x82\xAC|\xC2[\x80-\x9F])|\xD0[\xA0\xA1](?:\xD0[\x82-\x8F]|\xD1[\x92-\x9F]|\xD2[\x90\x91]|\xC2[\xA4-\xAA\xAC-\xAF\xB1-\xBA\xBC-\xBF]|\xE2\x80[\x9A\x9E\xA0\xA1\xA2\xB0\xB9\xBA]|\xE2\x82\xAC|\xE2\x84[\x96\xA2])|\xD0\xB2\xD0\x82' # New sequences needed: an article may quote a short sample (one mojibake # word is 2-6 sequences); one damaged line of Russian is 20 or more. MOJIBAKE_MIN=10 FOUND=0 NOTES=0 report() { echo "ARTIFACT: $1"; FOUND=$((FOUND + 1)); } note() { echo "NOTE: $1"; NOTES=$((NOTES + 1)); } is_zero() { case "$1" in *[!0]*) return 1 ;; *) return 0 ;; esac; } lines() { local n; n=$(wc -l < "$1"); echo $((n)); } cr_lines() { LC_ALL=C grep -ac $'\r$' "$1" || true; } non_ascii() { LC_ALL=C grep -aq $'[\x80-\xff]' "$1"; } fffd() { LC_ALL=C grep -ac $'\xef\xbf\xbd' "$1" || true; } mojibake() { local n; n=$(LC_ALL=C grep -aoP "$MOJIBAKE" "$1" 2>/dev/null | wc -l); echo $((n)); } has_bom() { local head="" IFS= read -r -n 3 head < "$1" || true # 3 bytes, or 1-3 chars in a UTF-8 locale [[ $head == $'\xef\xbb\xbf'* ]] } utf8_error() { # prints iconv's complaint and fails when $1 is not UTF-8 local err err=$(iconv -f UTF-8 -t UTF-8 "$1" 2>&1 >/dev/null) && return 0 printf '%s' "${err##*: }" return 1 } # True when $2 is exactly $1 with the CR before each line break removed: # a conversion to LF and nothing else. only_cr_removed() { LC_ALL=C sed 's/\r$//' "$1" | cmp -s - "$2"; } # Ending style of a file: none (no line break), lf, crlf or mixed. eol_style() { local n="$1" c="$2" if [ "$n" -eq 0 ]; then echo none elif [ "$c" -eq 0 ]; then echo lf elif [ "$c" -ge "$n" ]; then echo crlf else echo mixed fi } # $1 path, $2 display name, $3 base file or "", $4 new file. check_eol() { local path="$1" f="$2" base="$3" new="$4" bn=0 bc=0 bs="absent" nn nc ns hit=report case "$path" in container/css_pipeline/build/*) hit=note ;; esac nc=$(cr_lines "$new") [ -z "$base" ] || bc=$(cr_lines "$base") [ "$nc" -gt 0 ] || [ "$bc" -gt 0 ] || return 0 # LF on both sides if [ -n "$base" ]; then bn=$(lines "$base"); bs=$(eol_style "$bn" "$bc") fi nn=$(lines "$new"); ns=$(eol_style "$nn" "$nc") case "$bs:$ns" in crlf:lf) if only_cr_removed "$base" "$new"; then note "$f [$LABEL]: converted from CRLF to LF, nothing else changed ($nn lines)" else "$hit" "$f [$LABEL]: CRLF line endings lost (base CRLF on all $bn lines, now LF) together with other changes; a conversion alone passes" fi ;; crlf:mixed) "$hit" "$f [$LABEL]: mixed line endings, $((nn - nc)) of $nn lines now end in LF in a CRLF file" ;; lf:crlf) "$hit" "$f [$LABEL]: line endings flipped from LF to CRLF ($nn lines)" ;; lf:mixed) "$hit" "$f [$LABEL]: mixed line endings, $nc of $nn lines now end in CRLF in an LF file" ;; mixed:lf) if only_cr_removed "$base" "$new"; then note "$f [$LABEL]: converted from mixed endings to LF, nothing else changed ($bc of $bn lines had CRLF)" elif [ $((bc * 2)) -ge "$bn" ]; then "$hit" "$f [$LABEL]: CRLF line endings lost ($bc of $bn base lines had CRLF, now none) together with other changes; a conversion alone passes" else note "$f [$LABEL]: stray CRs removed ($bc of $bn base lines), the file is LF now" fi ;; absent:mixed) note "$f [$LABEL]: new file with mixed line endings ($nc of $nn lines CRLF)" ;; esac } # $1 path, $2 display name, $3 base file or "", $4 new file. check_encoding() { local path="$1" f="$2" base="$3" new="$4" b n err if ! non_ascii "$new"; then # plain ASCII: valid UTF-8, nothing to damage if [ -n "$base" ] && has_bom "$base"; then note "$f [$LABEL]: UTF-8 BOM removed"; fi return 0 fi n=$(fffd "$new") if [ "$n" -gt 0 ] && [ -z "$base" ]; then # A new page may show the character on purpose (unichr, /dev/urandom). note "$f [$LABEL]: new file with U+FFFD on $n line(s)" elif [ "$n" -gt 0 ]; then b=$(fffd "$base") if [ "$n" -gt "$b" ]; then report "$f [$LABEL]: U+FFFD replacement chars introduced on $((n - b)) more line(s) ($b -> $n, a lossy decode?)" fi fi if [ "$HAVE_PCRE" -eq 1 ]; then n=$(mojibake "$new") if [ "$n" -ge "$MOJIBAKE_MIN" ]; then b=0; [ -z "$base" ] || b=$(mojibake "$base") if [ $((n - b)) -ge "$MOJIBAKE_MIN" ]; then report "$f [$LABEL]: mojibake introduced ($b -> $n double-encoded sequences: UTF-8 read as cp1252, latin-1 or cp1251 and saved again)" fi fi fi if [ "$HAVE_ICONV" -eq 1 ] && [ -n "$base" ] && ! err=$(utf8_error "$new"); then if utf8_error "$base" >/dev/null; then report "$f [$LABEL]: no longer valid UTF-8 (${err:-invalid byte}), saved in another encoding?" fi fi if has_bom "$new"; then if [ -n "$base" ] && ! has_bom "$base"; then report "$f [$LABEL]: UTF-8 BOM added (PHP prints it before any header)" elif [ -z "$base" ]; then case "$path" in *.php) report "$f [$LABEL]: new PHP file with a UTF-8 BOM (printed before any header)" ;; *) note "$f [$LABEL]: new file with a UTF-8 BOM" ;; esac fi elif [ -n "$base" ] && has_bom "$base"; then note "$f [$LABEL]: UTF-8 BOM removed" fi } # $1 path, $2 source path (rename/copy) or "", $3 base sha (zeros: none), # $4 new sha (zeros: read the working tree file). check_file() { local f="$1" src="$2" ssha="$3" dsha="$4" name base="" new stat adds dels before notes_before eol_notes name="$f" [ -z "$src" ] || [ "$src" = "$f" ] || name="$f (from $src)" if ! is_zero "$ssha"; then base="$TMP/base" git cat-file blob "$ssha" > "$base" 2>/dev/null || return 0 fi if is_zero "$dsha"; then [ -f "$f" ] && [ ! -L "$f" ] || return 0 new="$f" else new="$TMP/new" git cat-file blob "$dsha" > "$new" 2>/dev/null || return 0 fi # git's own text/binary call (NUL in the first 8000 bytes, attributes): # binary files show "-" counts and none of the line or text checks apply. stat="${NUMSTAT[$f]:-}" [ -n "$stat" ] || return 0 read -r adds dels <<< "$stat" [ "$adds" != "-" ] && [ "$dels" != "-" ] || return 0 before=$FOUND notes_before=$NOTES case "$f" in container/src/feed/feed.json|container/src/feed/arch.json) ;; *) check_eol "$f" "$name" "$base" "$new" ;; esac eol_notes=$((NOTES - notes_before)) check_encoding "$f" "$name" "$base" "$new" # A line-ending note already explains a whitespace-only diff. if [ "$FOUND" -eq "$before" ] && [ "$eol_notes" -eq 0 ] && [ -n "$base" ]; then case "$f" in container/src/feed/feed.json|container/src/feed/arch.json) ;; *) # -b, not -w: -w also hides a space added or removed inside # a line ("Java Script" -> "JavaScript"), a real text change. if [ -z "${NONWS[$f]:-}" ]; then note "$name [$LABEL]: whitespace-only change ($adds+/${dels}-: indentation, trailing spaces), not blocking" fi ;; esac fi } # numstat -z: "adds<TAB>dels<TAB>path" or, for a rename or copy, # "adds<TAB>dels<TAB>" then the source and the destination as two fields. declare -A NUMSTAT=() NONWS=() read_numstat() { # $1: NUMSTAT or NONWS, the array to fill; the rest: diff options local which="$1" rec adds dels path shift while IFS= read -r -d '' rec; do IFS=$'\t' read -r adds dels path <<< "$rec" if [ -z "$path" ]; then IFS= read -r -d '' _ || break # rename/copy source IFS= read -r -d '' path || break fi if [ "$which" = NONWS ]; then NONWS["$path"]="$adds $dels" else NUMSTAT["$path"]="$adds $dels" fi done < <("${GIT_DIFF[@]}" --numstat "$@" "${RANGE[@]}") } read_numstat NUMSTAT read_numstat NONWS -b # -b keeps a whitespace-only change listed with 0 0: drop those. for k in "${!NONWS[@]}"; do [ "${NONWS[$k]}" != "0 0" ] || unset 'NONWS[$k]' done while IFS= read -r -d '' meta; do IFS= read -r -d '' path || break src="" read -r smode dmode ssha dsha status <<< "${meta#:}" case "$status" in R*|C*) src="$path"; IFS= read -r -d '' path || break ;; esac case "$smode:$dmode" in 120000:*|*:120000|160000:*|*:160000) continue ;; esac [ "$ssha" != "$dsha" ] || continue # pure rename or mode change check_file "$path" "$src" "$ssha" "$dsha" done < <("${GIT_DIFF[@]}" --raw --no-abbrev "${RANGE[@]}") if [ "$HAVE_PCRE" -eq 0 ]; then echo "check-diff-artifacts: grep -P is not available, the mojibake check was skipped" >&2 fi if [ "$HAVE_ICONV" -eq 0 ]; then echo "check-diff-artifacts: iconv is not available, the UTF-8 validity check was skipped" >&2 fi if [ "$FOUND" -gt 0 ]; then echo "check-diff-artifacts: $FOUND artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md" exit 1 fi if [ "$NOTES" -gt 0 ]; then echo "check-diff-artifacts: clean ($NOTES note(s), not blocking)" else echo "check-diff-artifacts: clean" fi exit 0
Подробнее о хуках, которые смотрят только на индексированное, — в разделе проверка индексированного, а о порядке хуков, которые пишут файлы, — в статье pre-commit и post-commit вместе.
Автор статьи: Клавдия Кондакова