Webb & utveckling

Git Bisect: Hitta commit som introducerade ett fel

Git Bisect: Find the Commit That Introduced a Bug

En funktion fungerade igår men misslyckas idag. Lär dig hur du använder Git bisect för att exakt lokalisera den commit som introducerade en regression, testa revisioner automatiskt och undersöka resultatet säkert.

Git Bisect: Hitta committen som introducerade en bugg

En webbplats fungerade förra veckan. Idag är en kassaberäkning felaktig, en JavaScript-komponent svarar inte längre, eller en PHP-endpoint returnerar oväntade data.

Du vet att buggen dykte upp någonstans i Git-historiken, men repot innehåller dussintals eller hundratals commits sedan den senaste fungerande versionen. Att öppna varje commit och läsa varje diff är sällan den snabbaste lösningen.

Git innehåller ett verktyg utformat för just denna situation: git bisect. Istället för att undersöka varje commit använder det en binär sökning för att identifiera den revision som först introducerade problemet. Med ett tillförlitligt test kan du automatisera undersökningen.

I den här handledningen skapar du ett litet PHP-projekt, introducerar en regression medvetet, lokaliserar den med Git bisect och lär dig hur du tillämpar samma teknik på verkliga projekt.

1. Hur Git bisect fungerar

Föreställ dig att din applikation fungerade vid commit A men misslyckas vid commit H. Git bisect behöver två referenspunkter: en god commit, där funktionen definitivt fungerade, och en felaktig commit, där buggen definitivt existerar.

Den checkar ut en intermediär revision. Du testar den, rapporterar om den fungerar, och Git minskar det återstående sökintervallet. För cirka 128 kandidat-commits kräver binär sökning typiskt omkring sju tester istället för att inspektera alla 128, förutsatt att beteendet kan klassificeras konsekvent.

Den officiella Git-dokumentationen beskriver processen och dess begränsningar.

2. Skapa en reproducerbar PHP-regression

Vi bygger en liten prisberäkningsfunktion. Inget ramverk, databas, Composer-paket eller webbserver krävs. Du behöver Git och PHP CLI installerat, och Git måste ha ditt författarnamn och e-post konfigurerade för commits.

Skapa en katalog och initiera ett repo:

mkdir git-bisect-demo
cd git-bisect-demo
git init

Skapa price.php:

<?php

declare(strict_types=1);

function finalPrice(int $price, int $discount): int
{
    return $price - $discount;
}

Det förväntade beteendet är rakt på sak: finalPrice(100, 20) returnerar 80.

Commita den fungerande versionen:

git add price.php
git commit -m "Add working price calculation"

Skapa sedan en orelaterad ändring:

echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"

Slutligen, introducera en bugg genom att ändra beräkningen i price.php:

<?php

declare(strict_types=1);

function finalPrice(int $price, int $discount): int
{
    return $price + $discount;
}

Commita den trasiga versionen:

git add price.php
git commit -m "Refactor price calculation"

Projektet har nu tre commits, med en medveten regression i den sista.

3. Hitta regressionen manuellt

Börja med att bekräfta att ditt arbetsträd är rent:

git status --short

Kommandot bör inte ge någon utdata. Om du har okommitterat arbete, commita det på lämpligt sätt eller stasha det innan du börjar.

Starta nu Git bisect:

git bisect start
git bisect bad HEAD
git bisect good HEAD~2
Illustration of the article's main concept

Här är HEAD den trasiga revisionen, medan HEAD~2 pekar på den första, fungerande committen. Git checkar ut den intermediära committen.

Testa beräkningen:

php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'

Om utdata är 80, markera revisionen som god:

git bisect good

Om det är 120, markera den som felaktig:

git bisect bad

Git fortsätter att välja commits tills den identifierar den första felaktiga revisionen. I den här tre-commits-demonstration behöver bara en intermediär revision testas.

När du är färdig, återställ din ursprungliga branch:

git bisect reset

Under bisect checkar Git normalt ut historiska revisioner i ett detached HEAD-läge. git bisect reset returnerar dig till den revision du använde innan undersökningen.

4. Automatisera undersökningen med git bisect run

Manuell testning är användbar när en bugg kräver visuell inspektion. Men om beteendet kan kontrolleras med ett kommando, är automatisering mer effektiv.

Git stöder git bisect run <command>. Kommandot kommunicerar sitt resultat med en exit-kod:

Exit-kod Betydelse
0 God revision
1–124 eller 126–127 Felaktig revision
125 Kan inte testa denna revision
Andra värden Avbryt undersökningen

Dessa regler kommer från den officiella Git bisect-manualen.

Skapa ett testskript utanför repot, till exempel ../check-price.php:

<?php

declare(strict_types=1);

require __DIR__ . '/git-bisect-demo/price.php';

exit(finalPrice(100, 20) === 80 ? 0 : 1);

Skriptet antar att projektmappen heter git-bisect-demo och ligger bredvid check-price.php. Kör dessa kommandon från inuti projektmappen:

git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset

Git kör testet på utvalda historiska revisioner tills den första felaktiga committen identifierats. Eftersom testskriptet ligger utanför repot, tas det inte bort vid checkout av en äldre revision.

För verkliga projekt, använd ett stabilt testkommando eller ett externt testskript som fungerar med de historiska revisioner som undersöks.

5. Tillämpa tekniken på ett verkligt webbprojekt

Samma arbetsflöde fungerar för ett WordPress-tillägg, Joomla-tillägg, JavaScript-applikation eller PHP-bibliotek.

Anta att en kassa-funktion är trasig i den senaste versionen, men den fungerade i release v1.4.0. Verifiera först att releasen faktiskt är god, starta sedan:

git bisect start HEAD v1.4.0

Om projektet har ett PHPUnit-test som fungerar över de valda revisionerna, kan du köra det manuellt:

vendor/bin/phpunit tests/CheckoutTest.php

Efter varje test, rapportera git bisect good eller git bisect bad.

När testet är tillförlitligt automatiserat:

git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset

Historiska commits kan kräva olika PHP-versioner, beroenden, databasscheman eller byggverktyg. Ett test som misslyckas för att miljön är inkompatibel indikerar inte nödvändigtvis regressionen. Se till att din testmiljö kan reproducera de relevanta historiska versionerna.

Technical workflow illustration

6. Vad händer om en gammal commit inte kan testas?

Ibland misslyckas en historisk revision att byggas av en orelaterad anledning. Markera den inte automatiskt som felaktig.

Använd:

git bisect skip

Git provar en annan kandidat. För automatiserade tester, säger exit-kod 125 åt Git att hoppa över revisionen.

Att hoppa över för många commits minskar precisionen. Om en otestbar commit ligger intill regressionen, kan Git rapportera flera möjliga skyldiga snarare än en exakt commit.

En bra långsiktig praxis är att underhålla reproducerbara utvecklingsmiljöer, låsa beroendeversioner och hålla kritiska regressionstester oberoende av orelaterad infrastruktur.

7. Inspektera committen som introducerade buggen

När Git identifierat den första felaktiga committen, undersök den:

git show <commit-hash>

För att se vilka filer som ändrats:

git show --stat <commit-hash>

För att inspektera en specifik fil:

git show <commit-hash> -- price.php

Den första felaktiga committen är inte nödvändigtvis den enda orsaken till buggen. En commit kan avslöja ett tidigare dolt problem, interagera med en annan förändring, eller bero på en extern tjänst som sedan har ändrats.

Använd den identifierade committen för att undersöka grundorsaken, inte som automatiskt bevis för att varje rad i den committen är felaktig.

8. Vanliga problem och lösningar

Buggen uppstår inkonsekvent

Om ett test ibland passerar och ibland misslyckas på samma revision, blir bisect-resultaten opålitliga. Kör testet flera gånger, ta bort tidsberoenden där det är möjligt, och kontrollera externa indata. Upprepade tester ökar konfidensen men ökar undersökningstiden.

Testet misslyckas på alla historiska revisioner

Bekräfta att din kända goda commit verkligen är god. Checka ut den revisionen separat och kör testet innan du börjar en ny bisect-session. Om det misslyckas där också, kan ditt test eller din miljö vara felaktiga.

Git vägrar byta revisioner

Okommitterade ändringar kan förhindra checkout. Kolla git status och spara dina ändringar innan du startar om. Undvik destruktiva kommandon som git reset --hard om du inte förstår exakt vad de kastar.

Historiken innehåller många merge-commits

För komplexa repos stöder Git:

git bisect start --first-parent HEAD v1.4.0

Detta följer first-parent-historik och kan hjälpa till att undersöka regressioner introducerade genom merges. Det ändrar vilka commits som betraktas, så det är ingen universell ersättning för ett normalt bisect.

Buggen beror på produktionsdata

Kör aldrig historisk applikationskod mot en live-produktionsdatabas. Använd en isolerad testmiljö med sanerade fixtures och ett reproducerbart schema. Äldre revisioner kan innehålla migrationer eller antaganden inkompatibla med produktion.

9. En praktisk felsökningschecklista

  • Bekräfta att buggen är reproducerbar.
  • Identifiera en revision som är känd att fungera och en som är känd att misslyckas.
  • Spara okommitterat arbete.
  • Definiera ett tillförlitligt test med ett tydligt pass/fail-resultat.
  • Håll externa tjänster och testdata konsekventa.
  • Använd git bisect skip för äkta otestbara revisioner.
  • Inspektera den identifierade committen och verifiera grundorsaken.
  • Avsluta med git bisect reset.

Slutsats

Git bisect förvandlar en osäker felsökningsuppgift till en strukturerad undersökning. Istället för att gissa vilken nyliga förändring som bröt en applikation, identifierar du en fungerande revision, en trasig revision, och låter Git förgrensa historiken.

Tekniken blir särskilt kraftfull när den kombineras med automatiserade tester. En regression gömd bland hundratals commits kan ofta lokaliseras med bara en handfull kontroller.

För utvecklare som underhåller långlivade PHP-projekt, WordPress-tillägg, Joomla-tillägg eller JavaScript-applikationer, är git bisect ett av de mest användbara Git-kommandona utöver daglig branching och merging.