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

Зміст:

• Що таке 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 процесом.

Малюнок 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 процесу, зокрема, за допомогою використання хуків post-checkout (вибір конфігурації середовища в залежності від гілки розробки) та post-merge (автоматизований запуск сторонніх сервісів після злиття коду).

Де виконуються 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