Проверка 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 как локальный хук при каждом коммите. Он смотрит на дифф из индекса и отказывает при четырёх видах повреждений, которые оставляют скриптовые массовые правки:

Ошибка оказалась в первой проверке. Её идея проста: если дифф есть, но исчезает, когда пробелы игнорируются, настоящих изменений в нём нет. В 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 падает пятый тест.

Ограничения и чего не делать

Подробнее о хуках, которые смотрят только на то, что в индексе, — в разделе проверка того, что в индексе, а о порядке хуков, которые пишут файлы, — в статье pre-commit и post-commit вместе.

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