Git Bisect: Знайдіть коміт, що ввів помилку
Функція працювала вчора, але сьогодні не працює. Дізнайтеся, як використовувати Git bisect, щоб виявити коміт, який ввів регресію, автоматично перевіряти ревізії та безпечно досліджувати результат.
Git Bisect: знайдіть коміт, який запровадив помилку
Вебсайт працював минулого тижня. Сьогодні розрахунок під час оформлення замовлення неправильний, JavaScript-компонент більше не реагує або PHP-ендпоінт повертає неочікувані дані.
Ви знаєте, що помилка з’явилася десь в історії Git, але від останньої робочої версії в репозиторії є десятки чи сотні комітів. Відкривати кожен коміт і читати кожен diff рідко буває найшвидшим рішенням.
Git містить інструмент, створений саме для такої ситуації: git bisect. Замість перегляду кожного коміту він використовує бінарний пошук, щоб визначити ревізію, яка вперше запровадила проблему. Маючи надійний тест, ви можете автоматизувати дослідження.
У цьому посібнику ви створите невеликий PHP-проєкт, навмисно запровадите регресію, знайдете її за допомогою Git bisect і навчитеся застосовувати ту саму техніку до реальних проєктів.
1. Як працює Git bisect
Уявіть, що ваш застосунок працював на коміті A, але не працює на коміті H. Git bisect потребує двох опорних точок: хорошого коміту, де функція точно працювала, і поганого коміту, де помилка точно існує.
Він перемикається на проміжну ревізію. Ви тестуєте її, повідомляєте, чи вона працює, і Git зменшує залишковий діапазон пошуку. Для приблизно 128 кандидатних комітів бінарний пошук зазвичай потребує близько семи тестів замість перевірки всіх 128, якщо поведінку можна послідовно класифікувати.
Офіційна документація Git описує цей процес та його обмеження.
2. Створіть відтворювану PHP-регресію
Ми створимо крихітну функцію розрахунку ціни. Не потрібні фреймворк, база даних, пакет Composer чи вебсервер. Вам потрібні встановлені Git і PHP CLI, а в Git мають бути налаштовані ваше ім’я автора та електронна пошта для комітів.
Створіть каталог і ініціалізуйте репозиторій:
mkdir git-bisect-demo
cd git-bisect-demo
git init
Створіть price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
Очікувана поведінка проста: finalPrice(100, 20) повертає 80.
Закомітьте цю робочу версію:
git add price.php
git commit -m "Add working price calculation"
Далі створіть не пов’язану з цим зміну:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
Нарешті, запровадьте помилку, змінивши розрахунок у price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
Закомітьте зламану версію:
git add price.php
git commit -m "Refactor price calculation"
Тепер у проєкті є три коміти, з навмисною регресією в останньому.
3. Знайдіть регресію вручну
Почніть із підтвердження, що ваше робоче дерево чисте:
git status --short
Команда не повинна нічого виводити. Якщо у вас є незакомічені зміни, закомітьте їх належним чином або сховайте перед початком.
Тепер запустіть Git bisect:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

Тут HEAD — це зламана ревізія, а HEAD~2 вказує на перший, робочий коміт. Git перемикається на проміжний коміт.
Перевірте розрахунок:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
Якщо вивід — 80, позначте ревізію як хорошу:
git bisect good
Якщо це 120, позначте її як погану:
git bisect bad
Git продовжує вибирати коміти, доки не визначить першу погану ревізію. У цій демонстрації з трьома комітами потрібно перевірити лише одну проміжну ревізію.
Коли завершите, відновіть свою початкову гілку:
git bisect reset
Під час bisect Git зазвичай перемикається на історичні ревізії в стані відокремленого HEAD. git bisect reset повертає вас до ревізії, яку ви використовували перед дослідженням.
4. Автоматизуйте дослідження за допомогою git bisect run
Ручне тестування корисне, коли помилка потребує візуального огляду. Але якщо поведінку можна перевірити командою, автоматизація ефективніша.
Git підтримує git bisect run <command>. Команда повідомляє свій результат через код виходу:
| Код виходу | Значення |
|---|---|
0 |
Хороша ревізія |
1–124 або 126–127 |
Погана ревізія |
125 |
Неможливо перевірити цю ревізію |
| Інші значення | Перервати дослідження |
Ці правила походять з офіційного посібника Git bisect.
Створіть тестовий скрипт поза репозиторієм, наприклад ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
Скрипт припускає, що папка проєкту називається git-bisect-demo і розташована поруч із check-price.php. Виконуйте ці команди зсередини папки проєкту:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git запускає тест на вибраних історичних ревізіях, доки не буде визначено перший поганий коміт. Оскільки тестовий скрипт розташований поза репозиторієм, перемикання на старішу ревізію не видаляє його.
Для реальних проєктів використовуйте стабільну тестову команду або зовнішній тестовий скрипт, який працює з історичними ревізіями, що досліджуються.
5. Застосуйте техніку до реального вебпроєкту
Той самий робочий процес підходить для плагіна WordPress, розширення Joomla, JavaScript-застосунку або PHP-бібліотеки.
Припустімо, функція оформлення замовлення зламана в останній версії, але працювала в релізі v1.4.0. Спочатку переконайтеся, що реліз справді хороший, а потім почніть:
git bisect start HEAD v1.4.0
Якщо в проєкті є тест PHPUnit, який працює на вибраних ревізіях, його можна запустити вручну:
vendor/bin/phpunit tests/CheckoutTest.php
Після кожного тесту повідомте git bisect good або git bisect bad.
Коли тест надійно автоматизовано:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
Історичні коміти можуть потребувати різних версій PHP, залежностей, схем бази даних або інструментів збірки. Невдача тесту через несумісність середовища не обов’язково вказує на регресію. Переконайтеся, що ваше тестове середовище може відтворити відповідні історичні версії.

6. Що робити, якщо старий коміт неможливо перевірити?
Іноді історична ревізія не збирається з не пов’язаної з цим причини. Не позначайте її автоматично як погану.
Використайте:
git bisect skip
Git спробує іншого кандидата. Для автоматизованих тестів код виходу 125 повідомляє Git, що ревізію потрібно пропустити.
Пропуск занадто великої кількості комітів зменшує точність. Якщо коміт, який неможливо перевірити, розташований поруч із регресією, Git може повідомити про кілька можливих винних замість одного точного коміту.
Хорошою довгостроковою практикою є підтримка відтворюваних середовищ розробки, фіксація версій залежностей і незалежність критичних регресійних тестів від не пов’язаної з ними інфраструктури.
7. Огляньте коміт, який запровадив помилку
Коли Git визначить перший поганий коміт, огляньте його:
git show <commit-hash>
Щоб побачити, які файли змінилися:
git show --stat <commit-hash>
Щоб оглянути конкретний файл:
git show <commit-hash> -- price.php
Перший поганий коміт не обов’язково є єдиною причиною помилки. Коміт може виявити раніше приховану проблему, взаємодіяти з іншою зміною або залежати від зовнішнього сервісу, який відтоді змінився.
Використовуйте визначений коміт для дослідження першопричини, а не як автоматичний доказ того, що кожен рядок у цьому коміті неправильний.
8. Поширені проблеми та рішення
Помилка з’являється непостійно
Якщо тест іноді проходить, а іноді fails на тій самій ревізії, результати bisect стають ненадійними. Запускайте тест кілька разів, де можливо, приберіть залежності від часу та контролюйте зовнішні вхідні дані. Повторне тестування підвищує впевненість, але збільшує час дослідження.
Тест fails на кожній історичній ревізії
Переконайтеся, що ваш відомий хороший коміт справді хороший. Окремо перемкніться на цю ревізію та запустіть тест перед початком нового сеансу bisect. Якщо там він теж fails, ваш тест або середовище можуть бути неправильними.
Git відмовляється перемикати ревізії
Незакомічені зміни можуть перешкоджати checkout. Перевірте git status і збережіть свої зміни перед перезапуском. Уникайте руйнівних команд, як-от git reset --hard, якщо ви не розумієте точно, що вони відкидають.
Історія містить багато merge-комітів
Для складних репозиторіїв Git підтримує:
git bisect start --first-parent HEAD v1.4.0
Це йде історією першого батька й може допомогти дослідити регресії, запроваджені через merge. Це змінює набір комітів, які розглядаються, тому не є універсальною заміною звичайного bisect.
Помилка залежить від production-даних
Ніколи не запускайте історичний код застосунку проти живої production-бази даних. Використовуйте ізольоване тестове середовище з очищеними фікстурами та відтворюваною схемою. Старіші ревізії можуть містити міграції або припущення, несумісні з production.
9. Практичний чекліст для налагодження
- Підтвердьте, що помилка відтворюється.
- Визначте одну ревізію, яка точно працює, і одну, яка точно не працює.
- Збережіть незакомічені зміни.
- Визначте надійний тест із чітким результатом pass/fail.
- Підтримуйте узгодженість зовнішніх сервісів і тестових даних.
- Використовуйте
git bisect skipдля ревізій, які справді неможливо перевірити. - Огляньте визначений коміт і перевірте першопричину.
- Завершуйте за допомогою
git bisect reset.
Висновок
Git bisect перетворює невизначене завдання налагодження на структуроване дослідження. Замість здогадок про те, яка нещодавня зміна зламала застосунок, ви визначаєте робочу ревізію, зламану ревізію і дозволяєте Git звузити історію.
Ця техніка стає особливо потужною в поєднанні з автоматизованими тестами. Регресію, приховану серед сотень комітів, часто можна локалізувати лише кількома перевірками.
Для розробників, які підтримують довготривалі PHP-проєкти, плагіни WordPress, розширення Joomla або JavaScript-застосунки, git bisect є однією з найкорисніших команд Git поза щоденним гілкуванням і злиттям.