Как переделать проверку pre-commit, чтобы она срабатывала только на настоящие повреждения
Проверка pre-commit стоит столько, сколько её послужной список: она должна падать на повреждениях и больше ни на чём. Эта страница — об одной проверке, которая плохо делала и то, и другое, и о том, как её переделали и проверили. Проверка, check-diff-artifacts.sh, охраняет сайт на PHP с английскими и русскими страницами, около 11 000 файлов в одном репозитории git. Она ищет в индексированном диффе повреждения, которые оставляют скриптовые правки. Как работать с текущей версией, описано в статье Проверка pre-commit на повреждения концов строк и кодировки; первая версия и её ошибка с git diff -w — в статье Проверка pre-commit, которая остановила верный коммит.
Что было
В версии 0.0.4 было четыре правила, каждое проверялось на каждом индексированном файле:
- дифф только из пробелов или концов строк: под git diff -b дифф пуст;
- потерян CRLF: в версии из HEAD есть CR, а в новой нет ни одного;
- добавлены символы замены U+FFFD;
- переписан весь файл: строк добавлено столько же, сколько удалено, в файле длиннее 100 строк.
Правила 2 и 3 описывают повреждение. Правила 1 и 4 описывают, как повреждение часто выглядит: смена CRLF меняет каждую строку и ничего, кроме пробелов, поэтому дифф с равными счётчиками или дифф, который исчезает под -b, может оказаться такой сменой. Когда правило срабатывало на нормальном изменении, рабочие заметки репозитория требовали проверки вручную: сравнить число CR в каждом индексированном файле с HEAD, поискать U+FFFD через grep, убедиться, что git diff -w пуст, и закоммитить с SKIP=check-diff-artifacts и фразой о проверке в тексте коммита.
Проблема 1: остановки на обычной работе
На сайте с двумя языками много замен 1:1. У страницы, переведённой построчно, столько же добавленных строк, сколько удалённых, так же как у карты сайта с новыми датами или у страницы, где папку картинок переименовали в каждой ссылке. Правило 4 срабатывало на всех. Здесь первая версия встречает переведённую страницу из 150 строк во временном репозитории. Хук там не установлен: старый скрипт, сохранённый как tools/old-check.sh, и новый запускаются вручную. Обе версии лежат рядом с репозиторием как old.sh и new.sh.
git init -q demo && cd demo && git config user.email you@example.com && git config user.name You
mkdir -p tools && cp ../old.sh tools/old-check.sh && cp ../new.sh tools/check-diff-artifacts.sh
for i in $(seq 1 150); do echo "<p>Строка $i: текст страницы</p>"; done > guide.html
printf 'function sum(a, b) {\r\n return a + b;\r\n}\r\n' > sum.js
git add . && git commit -qm "Adds the pages"
for i in $(seq 1 150); do echo "<p>Line $i: the text of the page</p>"; done > guide.html
git add guide.html
git diff --cached --numstat
150 150 guide.html
tools/old-check.sh --staged
ARTIFACT: guide.html [staged]: full-file rewrite (150 lines removed+added, possible EOL flip)
tools/check-diff-artifacts.sh --staged
check-diff-artifacts: clean
git commit -qm "Translates the guide"
Прогон по истории репозитория (см. ниже) показал, что первая версия остановила 16 коммитов. Два из них были настоящими повреждениями. Остальные 14 были обычной работой:
| Вид изменения | Коммитов | Правило |
|---|---|---|
| длинная страница, переведённая построчно | 4 | 4 |
| карта сайта, созданная заново с новыми датами, до 5228 строк | 3 | 4 |
| путь или URL, изменённый в каждой строке страницы | 3 | 4 |
| блоки кода переформатированы или перекрашены | 2 | 4 |
| намеренная правка пробелов | 2 | 1 и 4 |
Те же правила сделали невозможной и ещё одну обычную работу: перевод репозитория на LF. Коммит, который только переводит файл с CRLF на LF, меняет каждую строку и ничего, кроме концов строк, поэтому срабатывают сразу правила 1 и 2, и в репозитории так и оставалось 309 файлов с CRLF рядом с более чем 10 000 файлов с LF. В разделе о решении такой коммит показан с обеими версиями.
Восемь сообщений коммитов в истории заканчиваются фразой о проверке. Проверка, которую пропускают каждые несколько дней, учит команду её пропускать, а проверку вручную, семь команд, с каждым разом делали всё небрежнее.
Проблема 2: повреждения, которые прошли
Тот же прогон нашёл повреждения, которые первая версия пропустила, а внимательное чтение скрипта — их причины:
- Переименованные файлы пропускались. Список файлов брался из git diff --name-only --diff-filter=ACM, а у переименования статус R. Перенос шести файлов примеров, при котором их CRLF превратился в LF, прошёл незамеченным.
- Пути с кириллицей пропускались. Git берёт такое имя в кавычки в своём выводе, и git show HEAD:"\320\263..." не находит файла. В репозитории десять файлов с такими именами.
- Считалась только полная потеря CRLF. Правилу 2 нужно было, чтобы исчезли все CR; строка, дописанная с LF в файл с CRLF, проходила, как и файл с LF, переведённый на CRLF в ходе настоящей правки.
- Для повреждений кодировки, кроме U+FFFD, правила не было. Кракозябры (mojibake: байты одной кодировки, прочитанные как другая и сохранённые снова) или файл, сохранённый в cp1251, проявлялись только через правило 4, если файл был достаточно длинным и счётчики совпадали. BOM меняет одну строку, и правила для него не было.
- --all не видел неиндексированных изменений. Он сравнивал HEAD с индексом для каждого файла, так же как --staged.
Каждый случай воспроизводится во временном репозитории: перенос, который теряет CRLF и добавляет строку, файл с кириллическим именем, который теряет CRLF и получает строку, и неиндексированная потеря с правкой под --all. Старый скрипт считает чистыми все три:
mkdir -p examples && git mv sum.js examples/sum.js
sed -i 's/\r$//; 1i // Adds two numbers' examples/sum.js && git add examples/sum.js
git status --short
R sum.js -> examples/sum.js
tools/old-check.sh --staged
check-diff-artifacts: clean
tools/check-diff-artifacts.sh --staged
ARTIFACT: examples/sum.js (from sum.js) [staged]: CRLF line endings lost (base CRLF on all 3 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, а следом идёт список городов с кириллическим именем файла:
sed -i 's/$/\r/' examples/sum.js && git add examples/sum.js && git commit -qm "Moves sum.js to examples/"
printf 'Москва\r\nТампере\r\n' > города.txt && git add города.txt && git commit -qm "Adds the city list"
printf 'Москва\nТампере\nТурку\n' > города.txt && git add города.txt
git diff --cached --name-only
"\320\263\320\276\321\200\320\276\320\264\320\260.txt"
tools/old-check.sh --staged
check-diff-artifacts: clean
tools/check-diff-artifacts.sh --staged
ARTIFACT: города.txt [staged]: CRLF line endings lost (base CRLF on all 2 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 -qm "Adds Turku"
Последний случай — потеря CRLF с правкой, которая не проиндексирована:
sed -i 's/\r$//; s/two numbers/two numbers a and b/' examples/sum.js
tools/old-check.sh --all
check-diff-artifacts: clean
tools/check-diff-artifacts.sh --all
ARTIFACT: examples/sum.js [all]: 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
Решение: останавливать только то, что не делают намеренно
У обеих проблем одна причина: правила 1 и 4 измеряют форму диффа, а такая форма бывает и у повреждения, и у обычной работы. Новая версия измеряет само повреждение. Каждое правило сравнивает байты новой стороны с байтами базовой и останавливает только то, что в этом репозитории никто никогда не делает намеренно. То, что заслуживает внимания, но повреждением не является, становится заметкой NOTE, которая коммит не останавливает.
Лучше всего идею показывает правило о концах строк. Потеря CRLF — это повреждение, когда она прячет правку, потому что дифф, где изменилась каждая строка, невозможно проверить глазами. Перевод без чего-либо ещё ничего не прячет, и это можно доказать: новый файл должен быть ровно базой, из которой убран CR перед каждым переводом строки. Новая версия проверяет это одним сравнением и пропускает такой файл с заметкой, поэтому репозиторий может переходить на LF коммитами, которые только переводят. Во временном репозитории старая версия дважды останавливает чистый перевод, а новая его пропускает:
git checkout -- examples/sum.js
sed -i 's/\r$//' examples/sum.js && git add examples/sum.js
tools/old-check.sh --staged
ARTIFACT: examples/sum.js [staged]: whitespace/EOL-only diff (4+/ 4-, invisible under -b) ARTIFACT: examples/sum.js [staged]: CRLF line endings lost (HEAD blob has CR)
tools/check-diff-artifacts.sh --staged
NOTE: examples/sum.js [staged]: converted from CRLF to LF, nothing else changed (4 lines) check-diff-artifacts: clean (1 note(s), not blocking)
Перевод вместе с правкой, как во всех трёх случаях выше, по-прежнему останавливается, и сообщение говорит, что прошло бы. Исключение работает в одну сторону: LF на CRLF всегда останавливается, потому что цель — репозиторий, который в итоге весь в LF.
| 0.0.4 | 0.2.0 |
|---|---|
| дифф только из пробелов или концов строк: остановка | смену концов строк судит правило о концах строк; любой другой дифф только из пробелов — NOTE |
| потерян CRLF: исчезли все CR | стиль концов строк каждой стороны (lf, crlf, mixed): потерян CRLF вместе с другими изменениями, смешанные концы строк в файле с одним стилем, смена LF на CRLF; чистый перевод на LF — NOTE |
| добавлен U+FFFD | осталось для существующих файлов; новый файл с U+FFFD — NOTE |
| переписан весь файл: остановка | убрано; правила о кракозябрах, о правильности UTF-8 и о BOM проверяют повреждения, вместо которых оно стояло |
| переименования и пути с кириллицей пропускались | git diff --raw -z -M: переименования сравниваются с источником, пути без кавычек |
| --all = --staged | --all сравнивает HEAD с рабочим деревом; новый режим --commit REV |
Как устроено каждое правило, описано в разделе Как устроены проверки. Режим --commit добавили первым, потому что именно он делает возможной следующую проверку.
Проверка на всей истории
Модульные тесты проверяют случаи, о которых кто-то подумал. В истории репозитория лежат случаи, которые действительно произошли: каждый коммит — это индексированный дифф, который проверка видела или увидела бы. Проверка в том, чтобы запустить обе версии на каждом коммите и прочитать каждую находку. Новая версия делает это через --commit; маленькая обёртка добавляет к каждой находке идентификатор коммита:
vi replay.sh
#!/usr/bin/env bash # replay.sh REV: run the check on one commit, prefix each finding with REV out=$(container/tools/check-diff-artifacts.sh --commit "$1" 2>&1) grep -E '^(ARTIFACT|NOTE):' <<< "$out" | sed "s/^/$1 /"
chmod +x replay.sh
git rev-list --no-merges HEAD > commits.txt
wc -l < commits.txt
1174
xargs -P 8 обрабатывает восемь коммитов сразу, по одному коммиту на вызов (-n 1):
time (xargs -P 8 -n 1 ./replay.sh < commits.txt > hits.txt)
real 16m15,641s user 11m58,344s sys 21m46,361s
Версия 0.0.4 не умела проверять коммит, поэтому для старых правил вторая обёртка выполняла те же четыре проверки на паре REV^ и REV через git diff REV^ REV и git show REV:path.
Итоги прогона
Коммиты, которые останавливает новая версия:
awk '$2 == "ARTIFACT:" {print substr($1, 1, 9)}' hits.txt | sort | uniq -c | sort -rn
275 2af4d0554 6 45e2c4d58 4 8d889c516 1 b68ebc079 1 a402d2992
Каждый из них прочитан:
- 275 файлов: коммит, который исправил стиль кода сайта форматировщиком и перевёл на LF каждый затронутый файл с CRLF, одновременно его правя. Настоящее повреждение; старая версия тоже его поймала. Она насчитала 332, потому что остановила ещё 53 файла того же коммита, у которых изменились только концы строк, и 4 смешанных текстовых дампа, приведённых к LF: эти 57 теперь заметки.
- 6 файлов: перенос шести файлов примеров. Настоящее; старая версия его пропустила.
- 4 файла и 1 файл: собранный CSS, который стал смешанным, потому что сборка положила исходник с CRLF в набор с LF. Это были старые папки сборки; тот же случай в сегодняшней папке сборки — заметка, потому что набор берёт концы строк у своих исходников, а исходники проверяются сами.
- 1 файл: рефакторинг, который потерял CRLF в одном подключаемом файле. Настоящее; старая версия его поймала.
Ни одного из 14 ложных срабатываний среди них нет. Заметки тоже прочитаны:
awk '$2 == "NOTE:"' hits.txt | sed -E 's/^[0-9a-f]+ NOTE: [^[]*\[[^]]*\]: //; s/(^|[ (/])[0-9]+/\1N/g' | sort | uniq -c | sort -rn
53 converted from CRLF to LF, nothing else changed (N lines) 16 whitespace-only change (N+/N-: indentation, trailing spaces), not blocking 8 new file with mixed line endings (N of N lines CRLF) 7 new file with U+FFFD on N line(s) 4 converted from mixed endings to LF, nothing else changed (N of N lines had CRLF) 2 new file with a UTF-8 BOM
Два из этих видов в первом черновике новой версии были остановками, и прогон показал, что зря. Первый коммит репозитория, импорт 9155 файлов, содержит страницы, которые намеренно показывают U+FFFD (страница о chr(), вывод /dev/urandom), а сторонняя библиотека поставляет файлы README с BOM. У нового файла нет базы, относительно которой его можно испортить, поэтому для новых файлов это теперь заметки — кроме BOM в новом файле PHP, который ломает заголовки страницы.
Настройка правила о кракозябрах
Кракозябры — это UTF-8, прочитанный в однобайтовой кодировке и сохранённый снова. Правило считает шаблоны байтов такого текста: ведущий байт UTF-8, прочитанный как cp1252 или latin-1, и ведущие байты кириллицы, прочитанные как cp1251, которые превращают каждую русскую букву в Р или С с символом, которого в русском тексте на этом месте не бывает. Первую версию шаблона прогнали по всем отслеживаемым текстовым файлам репозитория, где кракозябр не ждали. Она нашла настоящий текст: математический словарь пишет «категория С°» и «С…» перед многоточием. Эти пары убрали из шаблона. С итоговым шаблоном скрипта в переменной MOJIBAKE поиск находит три файла:
LC_ALL=C git grep -c -I -P "$MOJIBAKE"
container/src/dev/python/collections/string/index.php:1 container/src/dev/python/strings.php:1 container/src/ru/code/python/objects/str/index.php:1
Все три — уроки по Python, которые цитируют одно слово кракозябрами, чтобы показать, как выглядит неверное декодирование. Такая цитата — 2–6 последовательностей, а одна испорченная строка русского текста — 20 и больше, поэтому правилу нужно десять новых последовательностей в файле. Цитаты проходят, испорченная страница — нет.
Проверка на собственном изменении
Первый запуск новой версии по рабочему дереву нашёл три артефакта, и все — в самом изменении:
ARTIFACT: container/tests/linters/test_check_diff_artifacts_sh.py [all]: U+FFFD replacement chars introduced (0 -> 1, a lossy decode?) ARTIFACT: container/tools/CHECK_DIFF_ARTIFACTS.md [all]: mojibake introduced (0 -> 6 sequences like é or Рё: UTF-8 read as cp1252, latin-1 or cp1251 and saved again) ARTIFACT: container/tools/check-diff-artifacts.sh [all]: mojibake introduced (0 -> 7 sequences like é or Рё: UTF-8 read as cp1252, latin-1 or cp1251 and saved again) check-diff-artifacts: 3 artifact(s). Fix them, or audit and skip this hook only: container/tools/CHECK_DIFF_ARTIFACTS.md
В файле тестов в одном случае был буквальный U+FFFD, а документация и скрипт цитировали кракозябры как примеры. Проверку, которая не может закоммитить саму себя, пропустили бы в первый же день. Исправление: скрипт только из ASCII, документация описывает примеры, а не цитирует их, тесты строят испорченные байты во время запуска ("\N{REPLACEMENT CHARACTER}", .encode().decode("cp1251").encode()), а порог в десять последовательностей покрывает короткую цитату. Эта страница показывает свои примеры кракозябр числовыми сущностями HTML, поэтому и её исходник проходит проверку.
Тесты во временных репозиториях
Самотест скрипта вырос с 5 случаев до 36. Каждый создаёт репозиторий git во временной папке, коммитит базовый файл, индексирует новую версию и запускает настоящий скрипт:
- 10 случаев повреждений, которые должны останавливаться: потерян CRLF при правке строки и при одном лишнем пробеле, строка с LF в файле с CRLF, LF на CRLF, строка с CRLF в файле с LF, U+FFFD, кракозябры из cp1251 и из latin-1, файл, сохранённый в cp1251, добавлен BOM;
- 13 обычных изменений, которые должны проходить: перевод на LF файла с CRLF, почти целиком CRLF смешанного файла и перенесённого файла (с заметкой), правки одних пробелов (с заметкой), пробел, удалённый внутри строки, замены 1:1 с LF и с CRLF, перевод, процитированное слово кракозябрами, правка старого файла в cp1251;
- 13 случаев для краёв: заметки об удалённом BOM и о новых файлах, BOM в новом файле PHP, два исключённых пути, двоичный файл, переименование, путь с кириллицей, --all и режим по умолчанию, --commit, неверная опция.
Список с выводом запуска — в разделе Тесты.
Скорость
Проверка pre-commit работает при каждом коммите, поэтому её время оплачивается каждый раз. Первый черновик новой версии запускал около двадцати процессов на файл: два вызова git diff --no-index, подсчёт строк, grep и iconv. Три изменения сократили это: один git diff --numstat и один git diff -b --numstat на все файлы вместо двух вызовов на файл, никакого подсчёта строк, когда ни на одной стороне нет CR, и никаких проверок кодировки, когда новая сторона — чистый ASCII. Замеры через --commit на одной машине при одной нагрузке:
| Коммит | Первый черновик | Итог |
|---|---|---|
| 48 файлов | 8,7 с | 1,7 с |
| 17 файлов | 3,7 с | 2,0 с |
| 382 файла | 63,5 с | 21,0 с |
Линтер, который ничего не проверил
Перед коммитом все хуки запустили на изменённых файлах через pre-commit run --files, и ShellCheck прошёл. Сам коммит упал:
shellcheck (maintained .sh)..............................................Failed - hook id: shellcheck - exit code: 1 linting 1 shell script(s) with shellcheck ... In container/tools/check-diff-artifacts.sh line 258: into["$path"]="$adds $dels" ^-----------^ SC2034 (warning): into appears unused. Verify use (or export if used externally).
Хук shellcheck в этом репозитории настроен с pass_filenames: false и сам проверяет индексированные скрипты. Во время --files ничего не было проиндексировано, поэтому он ничего не проверил и прошёл. Предупреждение — известная ложная тревога для nameref в bash (local -n into=...), и функцию переписали без него. Настоящей проверкой стал собственный линтер хука на этом файле вместе с тем же линтером на старой индексированной копии, которая должна была упасть с SC2034, чтобы доказать, что файл действительно прочитан.
Что мы поняли
- Проверяйте само повреждение, а не его форму. Правило, которое заменяет повреждение («равные счётчики — возможно, смена концов строк»), срабатывает на всём, что имеет ту же форму. У правила 4 было 14 ложных срабатываний, и оно не поймало ничего, чего не поймало бы правило 2.
- Прогоните историю, прежде чем доверять проверке. Один режим, который запускает проверку на готовом коммите, превращает всю историю в набор тестов. Каждое ложное срабатывание и каждый пропуск на этой странице найдены этим прогоном.
- Пропускайте безопасную форму остановленного изменения. Потеря CRLF останавливается, потому что может спрятать правку; перевод, который доказуемо ничего не прячет, проходит, и с ним репозиторий может перейти на LF.
- Заметки для того, что не является повреждением. Правка одних пробелов заслуживает взгляда, а не остановки.
- Проверка должна проходить на собственном изменении. Документация и тесты проверки цитируют ровно то, что она ищет.
- Убедитесь, что линтер прочитал файл. Прошедший хук, который ничего не проверил, выглядит так же, как прошедший хук, который проверил всё.
Автор статьи: Клавдия Кондакова