Автоматизируйте рабочий процесс: Практическое руководство по клиентским хукам Git

Хуки Git — это мощные, но часто недооцененные инструменты в экосистеме Git. Они позволяют разработчикам автоматически запускать пользовательские сценарии в определенные моменты рабочего процесса разработки — до или после таких событий, как фиксация, отправка (push) или слияние (merge).

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

В этом руководстве мы рассмотрим механику клиентских хуков Git с акцентом на наиболее распространенные и полезные типы: pre-commit (перед фиксацией) и post-merge (после слияния). Освоив эти хуки, вы сможете автоматизировать повторяющиеся задачи, выявлять ошибки на ранних этапах и значительно повысить согласованность и надежность вашего ежедневного процесса разработки.

Понимание хуков Git

Хуки Git — это исполняемые сценарии, которые Git автоматически запускает до или после выполнения определенных основных операций. Они находятся в каталоге .git/hooks каждого репозитория Git. Git поставляется с примерами хуков (обычно оканчивающимися на .sample), но они становятся активными только после того, как вы переименуете их, удалив расширение .sample.

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

Крайне важно различать два основных типа:

• Клиентские хуки: Запускаются на локальной машине разработчика (например, pre-commit, commit-msg). Они отлично подходят для локальной валидации и улучшения пользовательского опыта.
• Хуки на стороне сервера: Запускаются на центральном сервере при получении команды push (например, pre-receive, post-receive). Они обычно используются для применения политик принудительного исполнения в рамках всего проекта.

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

Поиск и активация клиентских хуков

Все клиентские хуки находятся в каталоге .git/hooks внутри вашего репозитория.

При инициализации нового репозитория Git предоставляет шаблоны:

git init
# Это создает каталог .git/hooks, заполненный образцами файлов, такими как pre-commit.sample

Чтобы активировать хук, просто переименуйте файл-образец. Например, чтобы активировать хук pre-commit:

cd .git/hooks
cp pre-commit.sample pre-commit
chmod +x pre-commit

Сценарии, помещенные сюда, должны быть исполняемыми (отсюда и chmod +x). Как правило, они запускаются как сценарии оболочки (shell scripts), но могут быть написаны на любом языке при условии наличия строки shebang (#!/bin/bash, #!/usr/bin/env python и т. д.) и доступности интерпретатора.

Практический пример 1: Хук pre-commit

Хук pre-commit запускается непосредственно перед тем, как Git запросит сообщение коммита. Это идеальное место для запуска проверок кода, который фиксируется.

Общие сценарии использования pre-commit:

1. Линтирование/Проверка стиля: Обеспечение соответствия кода установленным руководствам по стилю (например, ESLint, Black).
2. Запуск модульных тестов: Выполнение быстрых, критически важных тестов.
3. Проверка синтаксиса: Проверка базовой синтаксической корректности.
4. Предотвращение случайных коммитов: Обеспечение того, чтобы не остались секретные ключи или отладочные операторы.

Создание простого хука pre-commit (Пример на Shell)

Этот пример сценария проверяет, содержит ли какой-либо файл, подготовленный к коммиту, слово TODO:, и прерывает фиксацию, если оно найдено, заставляя разработчика устранить эти маркеры.

Создайте файл .git/hooks/pre-commit и добавьте следующее содержимое:

#!/bin/bash

# 1. Проверка подготовленных файлов на наличие 'TODO:'
STAGED_FILES=$(git diff --cached --name-only)

if grep -q "TODO:" <<< "$STAGED_FILES"; then
    echo "\n[СБОЙ ХУКА] В подготовленных файлах найдены маркеры 'TODO:'. Пожалуйста, устраните их перед коммитом."
    # Вывод конкретных файлов, содержащих маркеры (необязательно)
    git diff --cached | grep "TODO:"
    exit 1 # Выход с ненулевым кодом для прерывания фиксации
fi

# 2. Выполнение базовой проверки синтаксиса для файлов Python (требуется 'python -m py_compile')
for FILE in $(git diff --cached --name-only --diff-filter=ACM | grep '\.py$'); do
    echo "Проверка синтаксиса для $FILE..."
    python -m py_compile "$FILE" > /dev/null 2>&1
    if [ $? -ne 0 ]; then
        echo "[СБОЙ ХУКА] Найден синтаксическая ошибка в $FILE."
        exit 1
    fi
done

# Если все проверки пройдены
echo "Проверки pre-commit успешно пройдены."
exit 0 # Выход с нулевым кодом для разрешения коммита

Если сценарий завершается с ненулевым статусом (например, exit 1), Git немедленно прерывает процесс фиксации и выводит сообщение об ошибке.

Рекомендация: Для сложного линтирования и форматирования рассмотрите возможность использования внешних инструментов управления хуками, таких как Husky (для экосистем JavaScript) или Pre-commit (фреймворк-независимый инструмент), которые автоматически управляют установкой хуков, их совместным использованием и управлением зависимостями.

Практический пример 2: Хук post-merge

Хук post-merge запускается сразу после успешного завершения операции git merge. Этот хук полезен для выполнения очистки или обновления локальных зависимостей на основе недавно объединенного кода.

Общие сценарии использования post-merge:

1. Обновление субмодулей: Автоматическое обновление зависимых репозиториев.
2. Пересборка зависимостей: Запуск npm install или эквивалента, если были изменены файлы зависимостей (package.json, requirements.txt).
3. Уведомление пользователей: Отображение соответствующей информации о ветке.

Создание простого хука post-merge (Обновление зависимостей)

Если ваш проект использует Node.js, вам может потребоваться убедиться, что node_modules обновлен после слияния ветки, которая изменила package.json или package-lock.json.

Создайте файл .git/hooks/post-merge:

#!/bin/bash

echo "Запущен хук post-merge."

# Проверка, были ли изменены файлы зависимостей в результате слияния (HEAD@{1} ссылается на состояние до слияния)
if git diff --name-only HEAD@{1} HEAD | grep -Eq "(package\.json|package-lock\.json)"; then
    echo "Файлы зависимостей изменены. Запускается npm install..."
    npm install
    if [ $? -eq 0 ]; then
        echo "Зависимости успешно обновлены."
    else
        echo "ПРЕДУПРЕЖДЕНИЕ: npm install не удался после слияния. Пожалуйста, запустите 'npm install' вручную."
    fi
else
    echo "Файлы зависимостей не изменились. Пропуск npm install."
fi

exit 0

Этот хук использует возможности журнала ссылок Git (HEAD@{1} ссылается на состояние перед слиянием) для сравнения файлов, делая действие обусловленным и избегая ненужных запусков.

Другие полезные клиентские хуки

Хотя pre-commit и post-merge используются очень широко, существует несколько других клиентских хуков, которые могут оптимизировать ваш рабочий процесс:

• commit-msg: Запускается после того, как пользователь ввел сообщение коммита, но до того, как коммит будет завершен. Полезен для обеспечения соблюдения стандартов сообщений коммитов (например, формата Conventional Commits).
• pre-rebase: Запускается перед началом операции rebase. Может проверить, следует ли защитить определенные ветки от перебазирования.
• post-checkout: Запускается после успешного выполнения git checkout. Полезен для переключения переменных среды или конфигураций инструментов в зависимости от извлеченной ветки.

Имя хука	Точка запуска	Основной сценарий использования
pre-commit	Перед созданием коммита	Линтирование кода, локальные тесты, форматирование
commit-msg	После ввода сообщения	Обеспечение формата сообщения (например, тикеты JIRA)
post-merge	После успешного слияния	Обновление субмодулей, обновление зависимостей
post-checkout	После успешного извлечения	Переключение конфигураций среды

Резюме и следующие шаги

Клиентские хуки Git предоставляют способ автоматизации повторяющихся задач и обеспечения локальных стандартов качества непосредственно в вашей среде разработки с нулевыми накладными расходами. Они служат важным первым рубежом обороны от неаккуратных коммитов и проблем интеграции.

Чтобы эффективно их использовать:

1. Определите повторяющиеся задачи: Определите проверки, которые вы выполняете вручную перед фиксацией или слиянием.
2. Найдите .git/hooks: Перейдите в этот каталог в своем проекте.
3. Активируйте и напишите сценарий: Скопируйте файл .sample, переименуйте его, убедитесь, что он исполняемый (chmod +x), и напишите свою логику автоматизации.
4. Рассмотрите инструменты управления: Для команд изучите такие инструменты, как pre-commit, для синхронизации установок хуков между разработчиками.