Web a vývoj

Git Bisect: Najděte commit, který způsobil chybu

Git Bisect: Find the Commit That Introduced a Bug

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
Illustration of the article's main concept

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.

Technical workflow illustration

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 skip pro 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í.