Как переделать проверку pre-commit, чтобы она срабатывала только на настоящие повреждения

Проверка pre-commit стоит столько, сколько её послужной список: она должна падать на повреждениях и больше ни на чём. Эта страница — об одной проверке, которая плохо делала и то, и другое, и о том, как её переделали и проверили. Проверка, check-diff-artifacts.sh, охраняет сайт на PHP с английскими и русскими страницами, около 11 000 файлов в одном репозитории git. Она ищет в индексированном диффе повреждения, которые оставляют скриптовые правки. Как работать с текущей версией, описано в статье Проверка pre-commit на повреждения концов строк и кодировки; первая версия и её ошибка с git diff -w — в статье Проверка pre-commit, которая остановила верный коммит.

Что было

В версии 0.0.4 было четыре правила, каждое проверялось на каждом индексированном файле:

  1. дифф только из пробелов или концов строк: под git diff -b дифф пуст;
  2. потерян CRLF: в версии из HEAD есть CR, а в новой нет ни одного;
  3. добавлены символы замены U+FFFD;
  4. переписан весь файл: строк добавлено столько же, сколько удалено, в файле длиннее 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 были обычной работой:

14 ложных срабатываний версии 0.0.4
Вид измененияКоммитовПравило
длинная страница, переведённая построчно44
карта сайта, созданная заново с новыми датами, до 5228 строк34
путь или URL, изменённый в каждой строке страницы34
блоки кода переформатированы или перекрашены24
намеренная правка пробелов21 и 4

Те же правила сделали невозможной и ещё одну обычную работу: перевод репозитория на LF. Коммит, который только переводит файл с CRLF на LF, меняет каждую строку и ничего, кроме концов строк, поэтому срабатывают сразу правила 1 и 2, и в репозитории так и оставалось 309 файлов с CRLF рядом с более чем 10 000 файлов с LF. В разделе о решении такой коммит показан с обеими версиями.

Восемь сообщений коммитов в истории заканчиваются фразой о проверке. Проверка, которую пропускают каждые несколько дней, учит команду её пропускать, а проверку вручную, семь команд, с каждым разом делали всё небрежнее.

Проблема 2: повреждения, которые прошли

Тот же прогон нашёл повреждения, которые первая версия пропустила, а внимательное чтение скрипта — их причины:

Каждый случай воспроизводится во временном репозитории: перенос, который теряет 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
0.0.40.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

Каждый из них прочитан:

Ни одного из 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 во временной папке, коммитит базовый файл, индексирует новую версию и запускает настоящий скрипт:

Список с выводом запуска — в разделе Тесты.

Скорость

Проверка 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, чтобы доказать, что файл действительно прочитан.

Что мы поняли

Автор статьи: Клавдия Кондакова