Git Bisect: Najděte commit, který způsobil chybu
Funkce fungovala včera, ale dnes selhává. Naučte se, jak používat Git bisect k určení commitu, který způsobil regresi, automaticky testovat revize a bezpečně zkoumat výsledek.
Git Bisect: Najděte commit, který zavedl chybu
Minulý týden webová stránka fungovala. Dnes je výpočet pokladny špatný, komponenta JavaScript už nereaguje, nebo PHP endpoint vrací neočekávaná data.
Víte, že se chyba objevila někde v historii Gitu, ale repozitář obsahuje desítky nebo stovky commitů od poslední funkční verze. Otevírání každého commitu a čtení každého diffu bývá zřídka nejrychlejší řešení.
Git obsahuje nástroj navržený přesně pro tuto situaci: git bisect. Místo zkoumání každého commitu používá binární vyhledávání k identifikaci revize, která problém poprvé zavedla. Se spolehlivým testem můžete vyšetřování automatizovat.
V tomto tutoriálu vytvoříte malý PHP projekt, záměrně zavedete regresi, naleznete ji pomocí Git bisect a naučíte se, jak stejnou techniku aplikovat na reálné projekty.
1. Jak Git bisect funguje
Představte si, že vaše aplikace fungovala na commitu A, ale selhává na commitu H. Git bisect potřebuje dva referenční body: dobrý commit, kde funkce určitě fungovala, a špatný commit, kde určitě existuje chyba.
Vytáhne (checkout) mezilehlou revizi. Vyzkoušíte ji, nahlásíte, zda funguje, a Git zmenší zbývající rozsah hledání. Pro přibližně 128 kandidovaných commitů binární vyhledávání obvykle vyžaduje kolem sedmi testů místo zkoumání všech 128, za předpokladu, že chování lze konzistentně klasifikovat.
Oficiální dokumentace Gitu popisuje tento proces a jeho omezení.
2. Vytvoření reprodukovatelné PHP regrese
Vytvoříme malou funkci pro výpočet ceny. Není potřeba žádný framework, databáze, balíček Composer ani webový server. Potřebujete mít nainstalovaný Git a PHP CLI a Git musí mít pro commity nakonfigurované vaše jméno a e-mail.
Vytvořte adresář a inicializujte repozitář:
mkdir git-bisect-demo
cd git-bisect-demo
git init
Vytvořte price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
Očekávané chování je přímočaré: finalPrice(100, 20) vrací 80.
Odevzdejte (commit) tuto funkční verzi:
git add price.php
git commit -m "Add working price calculation"
Dále vytvořte nesouvisející změnu:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
Nakonec zaveďte chybu změnou výpočtu v price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
Odevzdejte rozbitou verzi:
git add price.php
git commit -m "Refactor price calculation"
Projekt má nyní tři commity, přičemž v tom posledním je záměrná regrese.
3. Nalezení regrese ručně
Začněte tím, že potvrdíte, že váš pracovní strom je čistý:
git status --short
Příkaz by neměl vyprodukovat žádný výstup. Pokud máte neodevzdanou práci, řádně ji před zahájením odevzdejte nebo ji odložte (stash).
Nyní spusťte Git bisect:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

Zde je HEAD rozbitá revize, zatímco HEAD~2 ukazuje na první, funkční commit. Git vytáhne mezilehlý commit.
Vyzkoušejte výpočet:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
Pokud je výstup 80, označte revizi jako dobrou:
git bisect good
Pokud je to 120, označte ji jako špatnou:
git bisect bad
Git pokračuje ve výběru commitů, dokud neidentifikuje první špatnou revizi. V této ukázce se třemi commity je potřeba otestovat pouze jednu mezilehlou revizi.
Až skončíte, obnovte svou původní větev:
git bisect reset
Během bisect Git obvykle vytáhne historické revize ve stavu odpojené hlavy (detached HEAD). git bisect reset vás vrátí na revizi, kterou jste používali před vyšetřováním.
4. Automatizace vyšetřování pomocí git bisect run
Ruční testování je užitečné, když chyba vyžaduje vizuální kontrolu. Pokud ale lze chování zkontrolovat příkazem, je automatizace efektivnější.
Git podporuje git bisect run <command>. Příkaz sděluje svůj výsledek pomocí návratového kódu:
| Návratový kód | Význam |
|---|---|
0 |
Dobrá revize |
1–124 nebo 126–127 |
Špatná revize |
125 |
Tuto revizi nelze otestovat |
| Jiné hodnoty | Ukončit vyšetřování |
Tato pravidla pocházejí z oficiální příručky Git bisect.
Vytvořte testovací skript mimo repozitář, například ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
Skript předpokládá, že složka projektu se jmenuje git-bisect-demo a nachází se vedle check-price.php. Spusťte tyto příkazy zevnitř složky projektu:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git spustí test na vybraných historických revizích, dokud není identifikován první špatný commit. Protože je testovací skript mimo repozitář, vytažení starší revize jej neodstraní.
Pro reálné projekty použijte stabilní testovací příkaz nebo externí testovací skript, který funguje s historickými revizemi, jež jsou předmětem vyšetřování.
5. Aplikace techniky na reálný webový projekt
Stejný pracovní postup funguje pro plugin WordPressu, rozšíření Joomla, aplikaci v JavaScriptu nebo PHP knihovnu.
Předpokládejme, že funkce pokladny (checkout) je v nejnovější verzi rozbitá, ale ve verzi v1.4.0 fungovala. Nejprve ověřte, že je vydání skutečně dobré, poté spusťte:
git bisect start HEAD v1.4.0
Pokud má projekt test PHPUnit, který funguje napříč vybranými revizemi, můžete jej spustit ručně:
vendor/bin/phpunit tests/CheckoutTest.php
Po každém testu nahlaste git bisect good nebo git bisect bad.
Když je test spolehlivě automatizovaný:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
Historické commity mohou vyžadovat různé verze PHP, závislosti, databázová schémata nebo nástroje pro sestavení. Test, který selže kvůli nekompatibilitě prostředí, nemusí nutně naznačovat regresi. Ujistěte se, že vaše testovací prostředí dokáže reprodukovat příslušné historické verze.

6. Co když nelze starý commit otestovat?
Někdy historická revize selže při sestavení z nesouvisejícího důvodu. Neoznačujte ji automaticky jako špatnou.
Použijte:
git bisect skip
Git vyzkouší dalšího kandidáta. U automatizovaných testů řekne Gitovi kód návratu 125, aby revizi přeskočil.
Přeskakování příliš mnoha commitů snižuje přesnost. Pokud je netestovatelný commit hned vedle regrese, Git může nahlásit více možných viníků místo jednoho přesného commitu.
Dobrou dlouhodobou praxí je udržovat reprodukovatelná vývojová prostředí, uzamykat verze závislostí a uchovávat kritické regresní testy nezávislé na nesouvisející infrastruktuře.
7. Prohlídka commitu, který zavedl chybu
Jakmile Git identifikuje první špatný commit, prozkoumejte jej:
git show <commit-hash>
Chcete-li zjistit, které soubory se změnily:
git show --stat <commit-hash>
Chcete-li prozkoumat konkrétní soubor:
git show <commit-hash> -- price.php
První špatný commit nemusí být nutně jedinou příčinou chyby. Commit mohl odhalit dosud skrytý problém, reagovat s jinou změnou, nebo záviset na externí službě, která se mezitím změnila.
Použijte identifikovaný commit k prozkoumání kořenové příčiny, nikoli jako automatický důkaz, že každý řádek v tomto commitu je nesprávný.
8. Běžné problémy a řešení
Chyba se objevuje nekonzistentně
Pokud test na stejné revizi někdy projde a někdy selže, výsledky bisectu se stávají nespolehlivými. Spusťte test vícekrát, odstraňte tam, kde je to možné, závislosti na časování, a kontrolujte externí vstupy. Opakované testování zvyšuje jistotu, ale zvyšuje čas vyšetřování.
Test selže na každé historické revizi
Potvrďte, že váš známý dobrý commit je opravdu dobrý. Vytažte (checkout) tuto revizi samostatně a spusťte test před zahájením nové relace bisectu. Pokud selže i tam, váš test nebo prostředí mohou být nesprávné.
Git odmítá přepnout revize
Neodevzdané změny mohou zabránit vytažení (checkout). Zkontrolujte git status a před restartem své změny zachovejte. Vyhněte se destruktivním příkazům, jako je git reset --hard, pokud přesně nerozumíte tomu, co zahodí.
Historie obsahuje mnoho merge commitů
Pro složité repozitáře Git podporuje:
git bisect start --first-parent HEAD v1.4.0
Toto sleduje historii prvního rodiče (first-parent) a může pomoci při vyšetřování regresí zavedených prostřednictvím sloučení (mergí). Mění, které commity se považují za relevantní, takže to není univerzální náhrada normálního bisectu.
Chyba závisí na produkčních datech
Nikdy nespouštějte historický kód aplikace proti živé produkční databázi. Použijte izolované testovací prostředí se sanitizovanými fixturemi a reprodukovatelným schématem. Starší revize mohou obsahovat migrace nebo předpoklady nekompatibilní s produkcí.
9. Praktický kontrolní seznam pro ladění
- Potvrďte, že chybu lze reprodukovat.
- Identifikujte jednu revizi, o které víte, že funguje, a jednu, o které víte, že selhává.
- Zachovejte neodevzdanou práci.
- Definujte spolehlivý test s jasným výsledkem projde/neprojde.
- Udržujte externí služby a testovací data konzistentní.
- Použijte
git bisect skippro skutečně netestovatelné revize. - Prohlédněte si identifikovaný commit a ověřte kořenovou příčinu.
- Dokončete pomocí
git bisect reset.
Závěr
Git bisect mění nejistý úkol ladění na strukturované vyšetřování. Místo hádání, která nedávná změna rozbila aplikaci, identifikujete funkční revizi, rozbitou revizi a necháte Git zúžit historii.
Tato technika je obzvlášť mocná, když se kombinuje s automatizovanými testy. Regresi skrytou mezi stovkami commitů lze často lokalizovat pouze s hrstkou kontrol.
Pro vývojáře, kteří udržují dlouholeté PHP projekty, pluginy WordPressu, rozšíření Joomla nebo aplikace v JavaScriptu, je git bisect jedním z nejužitečnějších příkazů Gitu nad rámec každodenního větvení a slučování.