Git Bisect: Найдите коммит, который привёл баг
Функция работала вчера, но сегодня не работает. Узнайте, как использовать Git bisect, чтобы точно определить коммит, который привёл к регрессии, автоматически тестировать ревизии и безопасно исследовать результат.
Git Bisect: Найдите коммит, в который была внесена ошибка
Веб-сайт работал на прошлой неделе. Сегодня расчет в корзине неверен, компонент JavaScript перестал отвечать, или PHP-эндпоинт возвращает неожиданные данные.
Вы знаете, что ошибка появилась где-то в истории Git, но репозиторий содержит десятки или сотни коммитов с последней рабочей версии. Открытие каждого коммита и чтение каждого diff — редко самое быстрое решение.
Git включает инструмент, созданный именно для этой ситуации: git bisect. Вместо проверки каждого коммита он использует бинарный поиск для идентификации ревизии, в которой проблема впервые появилась. С надежным тестом вы можете автоматизировать расследование.
В этом руководстве вы создадите небольшой PHP-проект, намеренно внесете регрессию, найдете её с помощью Git bisect и научитесь применять эту технику к реальным проектам.
1. Как работает Git bisect
Представьте, что ваше приложение работало в коммите A, но падает в коммите H. Git bisect нужны две опорные точки: хороший коммит (good commit), где функция точно работала, и плохой коммит (bad commit), где ошибка точно существует.
Он проверяет промежуточную ревизию. Вы тестируете её, сообщаете, работает ли она, и Git сужает оставшийся диапазон поиска. Приблизительно для 128 кандидатов бинарный поиск обычно требует около семи тестов вместо проверки всех 128, если поведение можно классифицировать последовательно.
В официальной документации Git описан процесс и его ограничения.
2. Создайте воспроизводимую PHP-регрессию
Мы создадим крошечную функцию расчета цены. Не требуется фреймворк, база данных, пакет Composer или веб-сервер. Вам понадобятся Git и PHP CLI, и в Git должны быть настроены ваше имя автора и email для коммитов.
Создайте директорию и инициализируйте репозиторий:
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
Команда не должна выдавать никакого вывода. Если у вас есть незакоммиченная работа, закоммитьте её соответствующим образом или спрячьте (stash) перед началом.
Теперь запустите 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 обычно проверяет исторические ревизии в состоянии detached 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. Распространенные проблемы и решения
Ошибка проявляется нестабильно
Если тест иногда проходит, а иногда падает на одной и той же ревизии, результаты bisect становятся ненадежными. Запускайте тест несколько раз, устраняйте временные зависимости где возможно и контролируйте внешние входные данные. Повторное тестирование повышает уверенность, но увеличивает время расследования.
Тест падает на каждой исторической ревизии
Подтвердите, что ваш известный хороший коммит действительно хорош. Отдельно проверьте эту ревизию и запустите тест перед началом новой сессии bisect. Если он падает и там, ваш тест или окружение могут быть некорректны.
Git отказывается переключать ревизии
Незакоммиченные изменения могут препятствовать checkout. Проверьте git status и сохраните свои изменения перед перезапуском. Избегайте деструктивных команд вроде git reset --hard, если вы не понимаете точно, что они отбрасывают.
История содержит много merge-коммитов
Для сложных репозиториев Git поддерживает:
git bisect start --first-parent HEAD v1.4.0
Это следует по истории first-parent и может помочь расследовать регрессии, внесенные через слияния. Это меняет то, какие коммиты рассматриваются, поэтому это не универсальная замена обычному bisect.
Ошибка зависит от продакшн-данных
Никогда не запускайте исторический код приложения против живой продакшн-базы данных. Используйте изолированное тестовое окружение с санитизированными фикстурами и воспроизводимой схемой. Старые ревизии могут содержать миграции или предположения, несовместимые с продакшном.
9. Практический чек-лист отладки
- Подтвердите, что ошибка воспроизводима.
- Идентифицируйте одну ревизию, известную как рабочая, и одну — как падающая.
- Сохраните незакоммиченную работу.
- Определите надежный тест с понятным результатом pass/fail.
- Держите внешние сервисы и тестовые данные последовательными.
- Используйте
git bisect skipдля действительно непроверяемых ревизий. - Изучите идентифицированный коммит и проверьте корневую причину.
- Завершите с
git bisect reset.
Заключение
Git bisect превращает неопределенную задачу отладки в структурированное расследование. Вместо гаданий, какое недавнее изменение сломало приложение, вы идентифицируете рабочую ревизию, сломанную ревизию и позволяете Git сузить историю.
Техника становится особенно мощной в сочетании с автоматизированными тестами. Регрессия, скрытая среди сотен коммитов, часто может быть локализована всего несколькими проверками.
Для разработчиков, поддерживающих долгосрочные PHP-проекты, плагины WordPress, расширения Joomla или JavaScript-приложения, git bisect — одна из самых полезных команд Git за пределами повседневного ветвления и слияния.