Husky Git hooks: где ломается проверка перед коммитом
Хуки закоммичены, локально линтер проходит — а у части команды коммит уходит без единой проверки. Типовые причины: каталог хуков не выставлен через настройку путей, файл потерял право на исполнение при переносе между файловыми системами, установка зависимостей в сборке идёт с отключёнными сборочными скриптами. Husky делает git-хуки в проекте частью репозитория, а не личной настройкой разработчика — но только при воспроизводимой установке.
Цена сбоев на коммите проявляется не сразу. Стиль расходится между ветками, и ревью превращается в спор о форматировании: реальные правки теряются среди переформатированных строк. Ошибки типов и синтаксиса всплывают уже на слиянии, когда автор переключился на другую задачу, сборка красная, а релиз сдвигается.
Вторая половина отказов — конфигурация самого хука. Предкоммитная проверка запускается по всему дереву вместо застейдженных файлов: на среднем проекте это десятки секунд, и обход через --no-verify становится привычкой. При частичном индексе (git add -p) линтер читает рабочую копию, а в коммит уходит версия из индекса — непроверенная. В репозитории с несколькими пакетами общий хук линтует всё целиком.
По отраслевым оценкам процесса разработки, дефект, пойманный до сборки, обходится в разы дешевле по трудозатратам, чем тот же дефект на интеграции. Разбираем, как это закрывается: воспроизводимая установка хуков, проверка ровно тех строк, что попадают в коммит, и отклик в пределах пары секунд.
Что даёт автоматическая проверка кода перед отправкой
Обратная связь за секунды вместо ожидания ревью
Линтер перед коммитом и проверка типов запускаются локально за секунды — разработчик узнаёт об ошибке до того, как код уйдёт в общую ветку. Раньше та же ошибка всплывала на сборке или на ревью через несколько часов, и время уходило на переключение контекста. Быстрая обратная связь сокращает цикл правки с часов до минут.
Единый стиль и меньше правок при слиянии веток
Автоматическая проверка кода фиксирует форматирование, порядок импортов и правила именования до слияния, поэтому спорные правки в ревью уходят в прошлое. Доля замечаний, касающихся стиля, падает почти до нуля — обсуждение смещается к логике и архитектуре. Единый стиль кода снимает и часть конфликтов при слиянии: расхождения форматирования перестают давать ложные различия в файлах.
Сборка перестаёт падать по мелочам
Проверки отсекают то, что раньше ломало сборку: незакрытые типы, забытые отладочные выводы, неиспользуемые зависимости. Доля отказов сборки снижается кратно, а освободившееся время уходит на задачи, а не на разбор чужих опечаток. Объём повторных исправлений в одном и том же файле тоже падает — правило срабатывает один раз и работает для всей команды.
Хуки, которые запускает Husky, настраиваются под конкретный репозиторий: тяжёлые каталоги исключаются из проверки, а для срочной правки остаётся явный обход. Правила живут в самом проекте, поэтому одинаково работают у всех — и у нового разработчика с первого дня.
Способы подключения проверок: локально, в сборке, в репозитории
Проверки можно включить на трёх уровнях: на машине разработчика, в сборочной линии и в общем репозитории. Уровни не заменяют друг друга — они ловят разные классы нарушений: от опечатки в коммите до попадания секрета в общую ветку. Ниже — что даёт каждый вариант и когда его достаточно.
| Вариант | Когда подходит | Ограничения |
|---|---|---|
| Локальные хуки на рабочей машине | Команда из 2-10 человек, единый стек, зависимости ставятся из манифеста при клонировании | Обход через --no-verify, свежий клон без установки зависимостей, разное окружение у участников |
| Проверка на стороне сборки | Несколько команд, длинные ветки, обязательные проверки перед слиянием | Обратная связь приходит позже — не секунды, а минуты; при росте числа веток копится очередь задач |
| Контроль в общем репозитории | Единые правила для всех, защита релизных веток и тегов | Нужны права на настройку, часть проверок дублирует локальные, правила сложнее менять точечно |
Когда локального контроля достаточно
Пока правила касаются формата, линтера и сообщений коммитов, хватит локальных хуков — они дают обратную связь за секунды, до того как код ушёл в общую ветку. Достаточно, чтобы зависимости ставились на шаге установки пакетов, а не отдельной командой, которую новичок забудет выполнить.
Когда нужен контроль на стороне сборки
Как только в репозитории несколько команд или релизные ветки, локальный контроль перестаёт быть гарантией: флаг обхода никто не отменял. Тогда те же проверки дублируются на сборке и становятся обязательным условием слияния — нарушение не проходит дальше, даже если его обошли на машине. Локальные хуки при этом остаются: они экономят время, а сборочные — защищают общую ветку.
Внедрение Git-хуков: этапы инженерной работы над проектом
Внедрение git-хуков начинается не с установки Husky, а с аудита репозитория: смотрим, какие проверки уже живут на сборочном сервере, сколько ветвей живёт долго, где заявленные правила расходятся с фактическим кодом. По результатам собираем план работ, в котором каждый хук привязан к конкретному классу ошибок, а не к абстрактному «надо проверять всё». Ниже — этапы настройки от аудита до передачи команде.
Что делаем на каждом шаге
- Аудит репозитория: инвентаризация линтеров, форматтеров и тестов, поиск дублей с непрерывной интеграцией, замер времени прогонов.
- Схема хуков: commit-msg отвечает за формат сообщения, pre-commit — за файлы в индексе, pre-push — за типы и быстрые тесты.
- Настройка окружения команды: зависимости и prepare-скрипт в манифесте — хуки встают при установке, без ручных шагов на каждой машине.
- Подключение проверок стиля и типов: общие конфиги, чтобы редактор, хуки и сборочный сервер читали один источник правил.
- Отладка на реальных ветках: длинная ветка, массовое переименование, слияние — смотрим время проверки и трение при частых коммитах.
- Проверка поведения при обходе: что происходит с
--no-verify, что при этом попадает в историю и как это подхватывает сборочный сервер. Обход не запрещаем, но делаем заметным. - Передача и инструктаж: инструкция по ручному запуску, обновлению конфигов и разбору срабатываний, короткая сессия с командой.
Точки согласования с командой
Согласуем состав хуков и порог строгости: что блокирует коммит, а что даёт предупреждение. Отдельно фиксируем, кто владеет конфигами и как вносить правки — иначе правила расходятся между машинами и сборочным сервером за пару недель.
Комплект на выходе: конфигурации, схемы, регламенты, документация
Комплект собираем так, чтобы новый инженер включился в работу без устных пояснений, а правила жили в репозитории, а не в переписке. Ниже — что именно передаём заказчику вместе с настроенными Git-хуками.
Техническая документация
- Файлы конфигурации проверок: настройки хуков и связанных анализаторов кода в репозитории, с комментариями по каждому правилу и разметкой, что проверяется на коммите, а что — перед отправкой в общую ветку.
- Схема прохождения коммита по этапам: от правки в рабочей копии до слияния — какие проверки запускаются, что происходит при ошибке и как выглядит корректный проход без обхода.
- Карта документации по проекту: где лежат правила стиля, конфигурация проверок и как они связаны с локальными настройками инженера.
Регламенты и инструкции для команды
- Регламент разработки: правила именования веток и сообщений, формат заголовка и тела, требования к разбиению изменений на атомарные коммиты.
- Политика обхода проверок: когда аварийный пропуск допустим, кто его подтверждает, что остаётся в истории и как инцидент разбирается после.
- Инструкция для новых разработчиков: пошаговая установка окружения, первый коммит, типовые ошибки и способы их исправления.
- Регламент обновления правил: кто вносит изменения в конфигурацию проверок, как проходит согласование и как убедиться, что новые правила не блокируют работу команды.
Кейс: предкоммитная проверка вместо сбоев в основной ветке
Было и стало в цифрах
До внедрения проверок на стороне разработчика основная ветка собиралась как повезёт. По логам сервера сборки: 34% запусков падали на этапе линтера и тестов — почти каждый третий; первая обратная связь приходила в среднем через 11 минут, а на правках форматирования ожидание растягивалось до получаса. Возвратов задачи в работу после ревью было столько же — правки прилетали уже после прогона на сервере.
После переноса базовых проверок в локальный цикл через Husky доля отказов сборки в основной ветке упала до 6%, первая обратная связь приходит за 30-40 секунд на том же наборе проверок, а возвраты в работу сократились до одной задачи из двенадцати. Проверки запускаются по изменённым файлам, а не по всему репозиторию, поэтому ожидание остаётся коротким даже на крупной кодовой базе.
Что сделали и что поменялось
Настроили предкоммитный хук на форматирование и линтер с автоисправлением, в предпушный вынесли модульные тесты по затронутым модулям и проверку типов. Тяжёлые сценарии оставили на сервере сборки, чтобы локальный цикл не превращался в ожидание. Конфигурация хуков лежит в репозитории и раскатывается вместе с установкой зависимостей — новый инженер получает те же правила в первый день, без устных договорённостей.
Обходной путь тоже закрыт: общие хуки на стороне сервера игнорируют локальные послабления, а любое изменение конфигурации проходит ревью как обычный код. При необходимости хук снимается одной командой, история правок сохраняется — откат к прежнему режиму не требует пересборки проекта.
Что делать, если проверки уже частично настроены в проекте?
Частично настроенные хуки — норма, а не исключение: обычно в проекте уже стоит Husky с линтером на предкоммитном этапе, плюс пара локальных скриптов и дублирующая проверка на серверном конвейере. Начинаем с инвентаризации: выписываем каждое правило, этап его запуска, время работы и затрагиваемые файлы. Без такой карты любая правка конфигурации превращается в угадывание, почему у одного инженера коммит проходит, а у другого падает.
Дальше раскладываем правила по группам. Быстрые — форматирование, линтер, проверка типов по изменённым файлам — остаются на этапе коммита. Тяжёлые — сборка, тесты, проверка зависимостей — уезжают на предпушный этап или на сервер. Дубли убираем в пользу одного источника правды: правило, живущее в трёх местах, расходится по версиям при первой же правке.
Переход без остановки работ строится на режиме предупреждения: новое правило сначала печатает замечание, но не блокирует коммит, и становится блокирующим после периода наблюдения, когда срабатываний становится мало. Так команда не уходит в обход через пропуск проверок и не теряет привычный ритм.
Миграция проверок требует преемственности: локальные скрипты удаляем только после того, как их поведение воспроизведено в общем конфиге, а изменения оформляем одним коммитом, который можно откатить целиком. Исключения для отдельных путей держим в файлах-исключениях, а не в теле хука. Команды запускаем через общую обёртку — тогда поведение одинаково на всех платформах и предсказуемо по времени.
Технические сомнения перед внедрением проверок в проекте
Перед включением хуков в общий процесс у команд всплывают одни и те же сомнения: обойдут ли проверку, не начнёт ли коммит занимать минуты, как это уживается с общим репозиторием. Ниже — короткие ответы на то, что спрашивают чаще всего.
Можно ли обойти проверку и как это отследить?
Ключ --no-verify отключает хуки для одного коммита, и запретить его на стороне разработчика нельзя. Поэтому критичные правила дублируются проверкой на сборочном сервере: локально они дают быструю обратную связь, а на интеграции работают как обязательный шлагбаум. Коммиты, прошедшие без проверки, видны в истории — это обсуждаемо, а не анонимно.
Не замедлит ли это работу на крупном проекте?
Замедляет не хук, а наивный прогон всех правил по всему дереву. Проверки идут только по изменённым файлам с кэшем результатов, поэтому на проекте в десятки тысяч файлов коммит остаётся в пределах секунд. Тяжёлые прогоны переносим на pre-push или на сервер.
У нас общий репозиторий, у всех свои настройки
Конфигурацию держим в репозитории, а не в локальных настройках: после клонирования её подхватывает prepare-скрипт, и у нового участника правила появляются сразу. Личные эксперименты уводим отдельным путём через core.hooksPath, чтобы они не расходились с общим набором.
Кто поддерживает правила, когда код развивается?
Правила лежат рядом с кодом и обновляются той же правкой, что и код: меняется архитектура — меняются и проверки. Раз в квартал делаем ревизию и убираем правила, которые перестали ловить ошибки, иначе хуки только замедляют коммиты.
Обсудим задачу и вернёмся с оценкой и планом работ
Чтобы оценка была точной, а не «плюс-минус», разговор стоит начать с вводных о проекте. Настройка Husky и хуков на pre-commit и pre-push — задача, где результат зависит от деталей: сколько разработчиков в команде, какие проверки уже существуют и сколько занимает полная сборка на машине разработчика.
Что полезно прислать заранее:
- структура репозитория: монорепозиторий или набор связанных пакетов;
- текущие проверки — линтер, типы, тесты, форматирование — и что из этого запускается вручную;
- состав команды и режим работы: сколько человек и как часто идут коммиты;
- боли в процессе: медленные проверки, конфликты при слиянии, обход правил через флаг пропуска;
- требования безопасности: закрытый контур, запрет на отправку кода во внешние сервисы;
- желаемые сроки и точки, к которым нужно прийти;
- порядок доступа к репозиторию и передачи проекта, если работаем на вашей стороне.
По этим вводным мы возвращаемся с оценкой и планом работ: что делаем в первую очередь, что можно отложить, как проверяем результат на каждом шаге. Опишите задачу в удобном формате — вернёмся с оценкой, планом и порядком передачи проекта вашей команде.
- Хуки настроены на одной машине и не закреплены в репозитории: у остальных участников проверки просто не запускаются, а правки в обход уходят в основную ветку
- Проверка запускается на всей истории правок и на всех файлах подряд — ожидание затягивается, и команда отключает её целиком, чтобы работать
- Правила живут в переписке и в голове одного человека: новый участник не знает, что сработает при сохранении, и регулярно ломает общий контур
- Локальная проверка написана иначе, чем серверная: один и тот же код проходит у разработчика и падает при сборке, спорят о причине, а не о правиле
- Набор правил не пересматривают после обновления инструментов и библиотек: проверка срывается на ровном месте, доверие к ней падает
- Нет разумного способа срочно пропустить проверку и нет записи о таком пропуске — непонятно, кто и когда обошёл правила
- Хуком пытаются закрыть всё сразу: тяжёлые проверки, сборку и выкладку; время ожидания растёт, дисциплина падает, правила обходят
- Настройку сделали один раз и забыли: через несколько месяцев она расходится с реальным кодом, а чинить её уже некому
