Статья также доступна на украинском (перейти к просмотру).

Содержание:

• Что такое Git hooks и зачем нужны в PHP-проекте
• Где выполняются Git-хуки
• Практическое использование Git хуков
• Изменение стандартного сообщения к коммиту
• Запуск статического анализатора перед отправкой коммита
• Быстрый Fixer
• Использование Psalm/Stan
• Заключение
• Практическое решение от FREEhost

Необходимым условием организации эффективного пайплайна в среде CI/CD является увеличение частоты выполнения операций слияния кода с главной ветвью разработки при сохранении высокого уровня чистоты поступающего кода. Достичь этого поможет использование Git-хуков – устроенного в Git механизма запуска сценариев, привязанных к определенным состояниям CI/CD процесса. Рассмотрим основные понятия и принципы использования git hooks в разных ситуациях. 

Что такое Git hooks и зачем нужны в PHP-проекте

Работа над веб-проектом на рабочем месте разработчика, например на VPS-сервере, при использовании Git предполагает существование нескольких этапов выполнения работ, соответствующих определенным состояниям или стадиям CI/CD процесса:

• Подготовка и внесение изменений (snapshots) в коде к Git-индекса с помощью команды git add (стадия Stage Changes);

• Инициирование передачи в локальный репозиторий содержимого Git-индекса с помощью команды git commit (стадия Commit Changes);

• Введение сообщения коммита с описанием внесенных изменений (стадия Enter Commit Message);

• Фиксация внесенных изменений в локальном репозитории (стадия All Done).

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

На Рисунку 1 приведена схема взаимодействия git hooks с CI процессом. 

Системой Gitlab предусмотрено наличие набора базовых сценариев для обработки каждого изменения состояния системы. Сценарии хранятся в каталоге .git/hooks.

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

$ cd .git/hooks
$ ls -l
-rwxr-xr-x 1 root root  478 Mar  2 20:12    applypatch-msg.sample
-rwxr-xr-x 1 root root  896 Mar  2 20:12    commit-msg.sample
-rwxr-xr-x 1 root root 4726 Mar  2 20:12   fsmonitor-watchman.sample
-rwxr-xr-x 1 root root  189 Mar  2 20:12    post-update.sample
-rwxr-xr-x 1 root root  424 Mar  2 20:12    pre-applypatch.sample
-rwxr-xr-x 1 root root 1643 Mar  2 20:12   pre-commit.sample
-rwxr-xr-x 1 root root  416 Mar  2 20:12    pre-merge-commit.sample
-rwxr-xr-x 1 root root 1492 Mar  2 20:12   prepare-commit-msg.sample
-rwxr-xr-x 1 root root 1374 Mar  2 20:12   pre-push.sample
-rwxr-xr-x 1 root root 4898 Mar  2 20:12   pre-rebase.sample
-rwxr-xr-x 1 root root  544 Mar  2 20:12    pre-receive.sample
-rwxr-xr-x 1 root root 2783 Mar  2 20:12   push-to-checkout.sample
-rwxr-xr-x 1 root root 3650 Mar  2 20:12   update.sample

Сценарии, названия которых начинаются с префикса pre всегда выполняются перед изменением состояний системы – отправкой коммита (pre-commit), введением комментария (prepare-commit-msg) и т.д. Их главное предназначение – разрешить или отменить ближайшее по времени действие, изменяющее состояние кодовой базы. Решение может быть принято, например, по результатам запуска подготовленного теста для определения качества кода перед отправкой (пушуванием) изменений в главную ветвь разработки.  

Работа сценариев организована по аналогии с фильтром: изменения проверяются на соответствие определенным критериям или принятым стандартам с возвратом соответствующего значения.  Если результатом выполнения сценария будет "0" - изменения "проходят", а если "1" - блокируются.          

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

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

• Автоматизация многих операций – запуск тестов, поиск ошибок, проверка форматов сообщений коммитов;

• Перенос процесса исправления ошибок в коде на ранние этапы разработки при настройке соответствующих сценариев-фильтров;

• Улучшение качества кода за счет его предварительного тестирования;

• Повышение безопасности благодаря фильтрации некорректных или подозрительных изменений в коде;

• Поддержка стандартов и согласованности работы команды;

• Расширение функциональности CI процесса, в частности, посредством использования хуков после оформления заказа(выбор конфигурации среды в зависимости от ветви разработки) и после начала (автоматизированный запуск сторонних сервисов после слияния кода).

Где выполняются Git-хуки

Git-хуки могут выполняться как на стороне клиента (на рабочем месте разработчика), так и сервера в зависимости от типа сценария. Первые оказывают влияние только на локальный репозиторий определенного разработчика, вторые – на центральный репозиторий проекта. 

Среди локальных можно выделить следующие сценарии:  

• pre-commit;

• prepare-commit-msg;

• commit-msg;

• post-commit;

• post-checkout.

Среди серверных:

• pre-receive;

• update;

• post-receive.

Назначение каждого из приведенных сценариев можно понять по их названиям. Этому также способствует то, что их позиции в списке соответствуют порядку их запуска. Например, prepare-commit-msg всегда вызывается после pre-commitя перед введением комментария в соответствующий коммит.

Место запуска сценария определяет его область воздействия, показатели работы и возможности обслуживания. В Таблице 1 приведены некоторые из этих показателей в зависимости от места запуска.    

Таблица 1. Характеристики работы Git-хуков в зависимости от места запуска.

Практическое использование Git хуков

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

1. Перейти к директории .git/hooks локального репозитория;

2. Выбрать нужный сценарий под названием;

3. Переименовать файл сценария, убрав слово sample и точку перед ним;

4. После этого выбранный хук будет включен.

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

1. Создать сценарий средствами одного из командных процессоров (bash, sh, dash и т.д.) или языковых процессоров (Python, Perl);

2. Скопировать сценарий в выбранный файл из .git/hooks, предварительно удалив его содержимое или создать собственное;

3. Сохранить внесенные изменения и переименовать файл в соответствии с его назначением;

4. Хук включен и готов к работе. 

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

$ chmod +x <Script file>

Здесь Script file – имя выбранного файла сценария.

Рассмотрим некоторые из вариантов применения git хуков. 

Изменение стандартного сообщения к коммиту

Сразу после выполнения коммита система выводит стандартное сообщение в качестве комментария к коммиту. Сменить его можно, установив хук с именем prepare-commit-msg.Код сценария при этом может быть следующим:

#!/bin/sh
echo "# Please don't forget to add a longer commit message!" > “$1”

Первая строка сценария указывает на программу-обработчик. В данном случае, это командный интерпретатор Bourne shell. Вторая строка содержит позиционный параметр $1, предоставляющий доступ к первому аргументу сценария. 

Теперь после каждого коммита вместо стандартного сообщения будет выводиться указанный в нашем сценарии текст с упоминанием о внесении расширенного комментария. 

Мы могли бы создать тот же сценарий, но на языке Python. Он может выглядеть следующим образом:

#!/usr/bin/env python3

import sys commit_msg_filepath = sys.argv[1] with open(commit_msg_filepath, 'w') as f:     f.write("# Please don't forget to add a longer commit message!")

Изменения произошли в первой строчке – теперь там находится ссылка на интерпретатор Python для обработки сценария. В теле сценария вместо параметра $1 использованный параметр sys.argv[1].

Запуск статического анализатора перед отправкой коммита

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

Размещен в файле pre-commit сценарий может быть следующим:

Быстрый Fixer

#!/usr/bin/env bash
set -euo pipefail
ROOT_DIR="$(git rev-parse --show-toplevel)"
cd "$ROOT_DIR"
# Собираем список staged PHP-файлов
mapfile -t PHP_FILES < <(git diff --cached --name-only --diff-filter=ACM | grep -E '\.php$' || true)
if [ ${#PHP_FILES[@]} -eq 0 ]; then
  exit 0
fi
echo "[pre-commit] PHP files staged: ${#PHP_FILES[@]}"
 
# 1) Быстрый Lint php -l (lint)
for f in "${PHP_FILES[@]}"; do
  php -l "$f" >/dev/null
done
echo "[pre-commit] php -l OK"
 
# 2) php-cs-fixer (только по staged файлам)
# Требования : vendor/bin/php-cs-fixer, конфиг .php-cs-fixer.php (или .php_cs.dist)
if [ -x "vendor/bin/php-cs-fixer" ]; then
  echo "[pre-commit] Running php-cs-fixer..."
  vendor/bin/php-cs-fixer fix --quiet --using-cache=yes -- "${PHP_FILES[@]}"
 
  # Важно: если fixer изменил файлы — нужно их снова добавить в индекс
  git add -- "${PHP_FILES[@]}"
  echo "[pre-commit] php-cs-fixer applied and re-staged"
else
  echo "[pre-commit] vendor/bin/php-cs-fixer not found, skipping"
fi
 
exit 0

Использование Psalm/Stan

Это универсальный вариант, но лучше оставить что-то одно
#!/usr/bin/env bash
set -euo pipefail
 
ROOT_DIR="$(git rev-parse --show-toplevel)"
cd "$ROOT_DIR"
 
echo "[pre-push] Running static analysis..."
 
# Psalm
if [ -x "vendor/bin/psalm" ]; then
  echo "[pre-push] psalm..."
  vendor/bin/psalm --no-cache
else
  echo "[pre-push] psalm not found, skipping"
fi
 
# PHPStan
if [ -x "vendor/bin/phpstan" ]; then
  echo "[pre-push] phpstan..."
  vendor/bin/phpstan analyse --no-progress
else
  echo "[pre-push] phpstan not found, skipping"
fi
 
# Тесты (опционально)
if [ -x "vendor/bin/phpunit" ]; then
  echo "[pre-push] phpunit..."
  vendor/bin/phpunit
fi
 
echo "[pre-push] OK"
exit 0

Заключение

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

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

При правильной настройке Git hooks становится важной частью современного процесса разработки наряду с CI/CD-системами. Они не заменяют полноценные конвейеры автоматизации, но значительно повышают дисциплину работы с кодом и позволяют обнаруживать ошибки до того, как изменения попадут в общую кодовую базу.

Подписывайтесь на наш Telegram-канал https://t.me/freehostua, чтобы быть в курсе новых полезных материалов

Смотрите наш канал YouTube на https://www.youtube.com/freehostua.

Мы в чем ошиблись, или что-то пропустили?

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

Дата: 11.03.2026 Автор: Александр Ровник #composer#git#linux#php

Голосование 1 2 3 4 5