Pre-commit: как настроить проверки до коммита

Один неверный YAML, случайный секрет или файл с пробелами в конце строки может попасть в коммит за секунду и обнаружиться уже после ревью. Pre-commit 4.x запускает такие проверки перед созданием коммита: настройка занимает около 10–20 минут, а результатом становится единый конфигурационный файл и предсказуемый набор проверок для всей команды.

Что именно решает pre-commit

Pre-commit — это менеджер Git-хуков: он устанавливает сценарий, который Git запускает перед созданием коммита. Сам pre-commit не форматирует код и не ищет уязвимости. Он подключает отдельные хуки из репозиториев и передаёт им изменённые файлы.

Хук — программа, привязанная к событию Git. В этой статье речь идёт о хуке pre-commit, который срабатывает до создания коммита и может остановить операцию, если проверка завершилась ошибкой.

Для первого набора достаточно проверок, не зависящих от языка проекта:

• удалить пробелы в конце строк;
• добавить перевод строки в конец файла;
• проверить синтаксис YAML и JSON;
• найти незакрытые маркеры конфликтов Git;
• не разрешить добавить слишком большой файл.

Локальный хук должен быть быстрым и исправлять очевидное. Всё, что требует базы, сети или длительного запуска тестов, лучше оставить CI.

Три способа проверять код

Pre-commit полезно сравнить не с одной альтернативой, а с местом, где выполняется проверка. Эти подходы не исключают друг друга: локальный хук ускоряет обратную связь, а CI остаётся независимой страховкой.

Практическое правило простое: форматирование и дешёвые проверки запускайте через pre-commit, полный набор тестов и проверку сборки — в CI. Если проверка занимает десятки секунд на каждом коммите, она быстро превращается в причину отключать хук.

Базовая настройка pre-commit 4.x

1. Установите инструмент

Pre-commit распространяется как Python-пакет, но запускать его можно в проекте на любом языке. Установите его одним из поддерживаемых менеджеров. Для изолированной установки подойдёт pipx:

pipx install pre-commit

Проверьте, что команда доступна:

pre-commit --version

В ответе должна быть версия из ветки 4.x. Если команда не найдена, проверьте PATH и установку pipx, а не меняйте конфигурацию проекта.

2. Создайте конфигурацию

В корне репозитория создайте файл .pre-commit-config.yaml. Ниже — рабочий минимальный вариант с официальным набором хуков pre-commit-hooks версии 5.0.0:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-merge-conflict
      - id: check-added-large-files

Здесь намеренно нет линтера конкретного языка. Сначала проверьте сам механизм, затем добавляйте Ruff, ESLint, PHP_CodeSniffer или другой инструмент с учётом версии проекта и официальной документации этого инструмента.

3. Установите Git-хук

Выполните установку из корня репозитория:

pre-commit install

После этого Git создаст локальный сценарий в каталоге хуков. Он не коммитится вместе с проектом, поэтому каждый новый разработчик должен выполнить эту команду сам или получить её через onboarding-скрипт.

4. Запустите проверки на всём репозитории

pre-commit run --all-files

Должны появиться названия хуков и статусы выполнения. Если trailing-whitespace или end-of-file-fixer изменили файлы, команда может завершиться ошибкой: это не поломка, а просьба проверить изменения и добавить их в индекс.

5. Закоммитьте исправления

git diff
git add .
git commit -m "Configure pre-commit checks"

Перед повторным коммитом убедитесь, что автоматические исправления не затронули лишние строки. Сообщение об успешном прохождении всех хуков означает, что локальные проверки завершились без ошибок.

Что происходит при обычном коммите

Pre-commit обычно получает от Git только файлы, подготовленные к коммиту через git add. Поэтому файл можно изменить после добавления в индекс: хук проверит индексированную версию, а не весь рабочий каталог. Это одна из самых частых причин расхождения между локальным результатом и тем, что потом видит ревьюер.

Если хук исправляет файл, Git не добавляет исправление в индекс автоматически. Последовательность должна быть такой:

1. Выполните git commit.
2. Дождитесь завершения хуков.
3. Посмотрите git diff и проверьте изменения.
4. Повторно выполните git add для исправленных файлов.
5. Запустите коммит ещё раз.

Если нужно проверить не весь репозиторий, а только обычный сценарий, достаточно снова сделать коммит. Полный запуск через --all-files нужен после добавления нового хука, смены его версии или массового изменения правил форматирования.

Что ломается чаще всего

Хук не запускается

Если коммит проходит без единого сообщения pre-commit, обычно команда pre-commit install не выполнялась в этом клоне репозитория либо Git использует другой каталог хуков. Проверьте установку команды и повторите установку хука из корня проекта.

Проверка падает на YAML

Сообщение вроде InvalidConfigError или ошибка синтаксиса YAML означает, что проблема может быть в самом .pre-commit-config.yaml. Отступы в YAML значимы: используйте пробелы, сохраните вложенность repos → hooks и проверьте, что идентификатор хука существует в указанной версии репозитория.

Файл исправился, но коммит всё ещё не проходит

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

Один разработчик получает другую ошибку

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

Pre-commit тормозит коммит

Уберите из локального этапа тяжёлые тесты, сетевые проверки и операции с полной базой данных. Для форматтера настройте проверку изменённых файлов, а полный прогон перенесите в CI. Отключать весь pre-commit из-за одного медленного хука — плохой компромисс: лучше разделить проверки по времени выполнения.

Как не превратить хук в формальность

Конфигурация живёт в репозитории, а установленный Git-хук — нет. Поэтому добавьте установку pre-commit в инструкцию для разработчиков и в проверку CI. CI не должен доверять тому, что локальный хук когда-то был установлен: он обязан запускать те же проверки отдельно.

Обновляйте версии осознанно. Команда pre-commit autoupdate может изменить зафиксированные ревизии хуков; после этого нужно запустить проверки на всём репозитории и просмотреть массовые изменения. Не обновляйте хуки прямо перед срочным релизом без отдельного коммита и ревью.

Секреты и уязвимости требуют специализированных сканеров. Базовый набор из этой статьи не обещает найти API-ключи, пароли или небезопасные зависимости. Для таких задач добавляйте проверенный инструмент, не храните реальные токены в конфигурации и дублируйте критичные проверки на сервере.

Что делать дальше

Сначала оставьте базовые шесть хуков и добейтесь, чтобы ими пользовалась вся команда. Затем добавьте один инструмент языка проекта и измерьте время обычного коммита. В CI сравнивайте результат с локальным запуском, а при обновлении зависимостей отдельно проверяйте изменения ревизий и массовые правки форматирования.