Проверка pre-commit, которая остановила верный коммит: git diff -w и git diff -b
Эта страница о первой версии проверки, 0.0.4, и вывод на ней получен с этой версией. Позже проверку переделали: теперь она останавливает только повреждения концов строк и кодировки, а правки одних пробелов, построчные замены 1:1 и чистый перевод на LF пропускает. Текущая версия описана в статье Проверка pre-commit на повреждения концов строк и кодировки, а почему и как она изменилась — в статье Как переделать проверку pre-commit, чтобы она срабатывала только на настоящие повреждения. Разница между git diff -w и git diff -b, разобранная здесь, по-прежнему верна: текущая версия использует -b для своей заметки о пробелах.
Хук pre-commit, который блокирует хорошие коммиты, хуже, чем отсутствие хука: люди учатся его обходить. Эта страница — история одного такого хука, проверки случайных диффов только из пробелов, который отказал в коммите, где изменилось лишь написание слова. Она показывает, что это была за проверка, почему она сработала, исправление в одну опцию и тест, который не даёт ошибке вернуться. Все команды выполнены в чистом репозитории с git 2.43.0 и bash 5.2; вывод вставлен так, как он был напечатан.
Проверка и от чего она защищает
В репозитории сайта есть скрипт check-diff-artifacts.sh, который запускается из фреймворка pre-commit как локальный хук при каждом коммите. Он смотрит на дифф из индекса и отказывает при четырёх видах повреждений, которые оставляют скриптовые массовые правки:
- дифф, который меняет только пробелы или концы строк, например каждую строку файла, переведённую из CRLF в LF;
- потерянные концы строк CRLF в файле, где они были в HEAD;
- символы замены U+FFFD — признак перекодирования туда и обратно;
- переписывание файла целиком: добавлено столько же строк, сколько удалено, в файле длиннее 100 строк.
Ошибка оказалась в первой проверке. Её идея проста: если дифф есть, но исчезает, когда пробелы игнорируются, настоящих изменений в нём нет. В bash она сравнивает количество строк в двух вызовах git diff:
adds, dels = lines added and deleted by: git diff --cached --numstat wsum = lines changed when whitespace is ignored: git diff --cached -w --numstat if wsum is empty, the diff was whitespace only: report it
Коммит, который она остановила
Одна задача исправляла написание JavaScript по всему сайту: на страницах в заголовках, ключевых словах и описаниях стояло «Java Script». В индекс попали шесть файлов, и коммит не прошёл. Показаны три из шести строк отчёта:
check-diff-artifacts (staged)...........................................Failed - hook id: check-diff-artifacts - exit code: 1 ARTIFACT: container/src/dev/js/array_sort.php [staged]: whitespace/EOL-only diff (2+/ 2-, invisible under -w) ARTIFACT: container/src/dev/js/tictactoe2.php [staged]: whitespace/EOL-only diff (2+/ 2-, invisible under -w) ARTIFACT: container/src/ru/code/js/ibs_to_kg.php [staged]: whitespace/EOL-only diff (3+/ 3-, invisible under -w)
Диффы были настоящими. Строка title: 'Java Script Promise' превратилась в title: 'JavaScript Promise'. С коммитом всё было в порядке, виноват был хук, поэтому коммит остался несделанным, пока хук не исправили. --no-verify пропустил бы хук для этого одного коммита, но хук, который приходится пропускать для верной работы, — это хук с ошибкой, и ошибка достанется следующему человеку.
Причина: git diff -w
-w — сокращение от --ignore-all-space: git сравнивает строки так, будто из них удалили все пробелы и табы. Для смены CRLF или смены отступов это именно та модель, что нужна. Для замены написания она не подходит: без пробела Java Script и JavaScript — один и тот же текст. Эффект воспроизводится во временном репозитории с файлом из трёх строк:
git init -q && git config user.email a@b && git config user.name n
printf "<?php\n\$page_keywords = 'Java Script, Java Script basics';\n title: 'Java Script Promise',\n" > page.php
git add page.php && git commit -qm init
sed -i "s/Java Script/JavaScript/g" page.php && git add page.php
git diff --cached --numstat
2 2 page.php
git diff --cached -w --numstat
Вторая команда ничего не печатает: с -w git не видит никакой разницы. Скрипт принял пустой ответ за «только пробелы»:
git show HEAD:container/tools/check-diff-artifacts.sh > /tmp/old-check-diff-artifacts.sh && chmod +x /tmp/old-check-diff-artifacts.sh
/tmp/old-check-diff-artifacts.sh --staged
ARTIFACT: page.php [staged]: whitespace/EOL-only diff (2+/ 2-, invisible under -w)
Проверка не умела отличить пробел, который сдвинулся или пропал на краю строки, от пробела, добавленного или убранного между двумя буквами. Второй случай меняет слова, то есть это противоположность артефакта.
Исправление: git diff -b
-b, или --ignore-space-change, — более мягкая опция. Она игнорирует пробелы в конце строки и считает любую серию пробелов и табов одним равным разделителем, но сам разделитель не удаляет: «Java Script» и «JavaScript» по-прежнему различаются. Изменение в скрипте — один флаг и комментарий:
- wsum=$(git diff "${diff_args[@]}" -w --numstat -- "$f" | awk '{print $1+$2}') + # -b, not -w: -w also hides a space added or removed inside a line + # ("Java Script" -> "JavaScript"), which is a real text change. + wsum=$(git diff "${diff_args[@]}" -b --numstat -- "$f" | awk '{print $1+$2}')
Сообщение теперь говорит invisible under -b, а версия в заголовке скрипта выросла на единицу. На том же исправлении написания -b по-прежнему видит две изменённые строки, и хук проходит:
git diff --cached -b --numstat
2 2 page.php
container/tools/check-diff-artifacts.sh --staged
check-diff-artifacts: clean
То, ради чего проверка существует, она обязана ловить по-прежнему. После коммита исправления файл переводят в концы строк CRLF и добавляют в индекс:
git commit -qm fix && sed -i "s/\$/\r/" page.php && git add page.php
git diff --cached --numstat
3 3 page.php
git diff --cached -b --numstat
container/tools/check-diff-artifacts.sh --staged
ARTIFACT: page.php [staged]: whitespace/EOL-only diff (3+/ 3-, invisible under -b)
С -b символы возврата каретки в конце строк игнорируются, дифф получается пустым, и хук сообщает об этом с ненулевым кодом возврата. Так два флага ведут себя в случаях, которые важны проверке:
| Изменение | -w | -b |
|---|---|---|
| смена CRLF на LF | только пробелы | только пробелы |
| пробелы добавлены в конец строки | только пробелы | только пробелы |
| табы в отступе заменены пробелами | только пробелы | только пробелы |
| один пробел заменён тремя | только пробелы | только пробелы |
| Java Script на JavaScript | только пробелы (неверно) | настоящее изменение |
| отступ добавлен в строку, где его не было | только пробелы | настоящее изменение |
Тест для хука
Ошибка была в скрипте, который никто не тестировал, поэтому исправление идёт с тестом. Он следует тому же шаблону, что и тесты других проверок pre-commit: временный git-репозиторий на каждый тест, настоящий скрипт запускается в нём, проверяются код возврата и текст отчёта. В репозитории один закоммиченный файл; каждый случай добавляет в индекс изменённую версию и запускает --staged:
ORIGINAL = b"a Java Script b\n x = 1\nfoo\n" @pytest.mark.parametrize( "content", [ b"a Java Script b\r\n x = 1\r\nfoo\r\n", b"a Java Script b \n x = 1\nfoo\n", b"a Java Script b\n\tx = 1\nfoo\n", b"a Java Script b\n x = 1\nfoo\n", ], ids=["crlf", "trailing", "tab-indent", "space-run"], ) def test_whitespace_only_diff_is_flagged(repo, content): result = check(repo, content) assert result.returncode == 1 assert "whitespace/EOL-only diff" in result.stdout + result.stderr def test_space_removed_inside_a_line_passes(repo): result = check(repo, b"a JavaScript b\n x = 1\nfoo\n") assert "whitespace/EOL-only diff" not in result.stdout + result.stderr assert result.returncode == 0
python -m pytest tests/linters/test_check_diff_artifacts_sh.py -v
tests/linters/test_check_diff_artifacts_sh.py::test_whitespace_only_diff_is_flagged[crlf] PASSED [ 20%] tests/linters/test_check_diff_artifacts_sh.py::test_whitespace_only_diff_is_flagged[trailing] PASSED [ 40%] tests/linters/test_check_diff_artifacts_sh.py::test_whitespace_only_diff_is_flagged[tab-indent] PASSED [ 60%] tests/linters/test_check_diff_artifacts_sh.py::test_whitespace_only_diff_is_flagged[space-run] PASSED [ 80%] tests/linters/test_check_diff_artifacts_sh.py::test_space_removed_inside_a_line_passes PASSED [100%] ============================== 5 passed in 0.42s ===============================
Четыре случая сохраняют первоначальную цель хука, один не даёт ошибке вернуться. Со старым -w падает пятый тест.
Ограничения и чего не делать
- Добавленный отступ больше не отмечается. Строка, в которой не было ведущих пробелов и появились четыре, при -b считается изменением. Такой дифф редок в скриптовых правках и является настоящим изменением файла, поэтому проверка его пропускает. Если его нужно ловить, добавьте второе сравнение с --ignore-space-at-eol --ignore-cr-at-eol, которое игнорирует только конец строки.
- Не переписывайте текст, чтобы пройти хук. Если изменить соседнее слово, чтобы дифф был не только из пробелов, в коммит попадёт изменение, которого никто не хотел.
- Не используйте --no-verify как исправление. Он пропускает хук для одного коммита и оставляет ошибку на месте. Исправьте хук, закоммитьте исправление первым, потом коммит с работой, которую он остановил.
- Проверяйте проверку на том случае, который не прошёл. Ложное срабатывание пришло с настоящего коммита; первый тест исправления — тот же самый коммит.
Подробнее о хуках, которые смотрят только на то, что в индексе, — в разделе проверка того, что в индексе, а о порядке хуков, которые пишут файлы, — в статье pre-commit и post-commit вместе.
Автор статьи: Клавдия Кондакова