Web & Udvikling

Git Bisect: Find den commit, der introducerede en fejl

Git Bisect: Find the Commit That Introduced a Bug

En funktion virkede i går, men fejler i dag. Lær, hvordan du bruger Git bisect til at identificere den commit, der introducerede en regression, teste revisioner automatisk og undersøge resultatet sikkert.

Git Bisect: Find det commit, der indførte en fejl

Et websted fungerede i sidste uge. I dag er en betalingsberegning forkert, en JavaScript-komponent reagerer ikke længere, eller et PHP-endepunkt returnerer uventede data.

Du ved, at fejlen opstod et eller andet sted i Git-historikken, men arkivet indeholder dusinvis eller hundreder af commits siden den sidste fungerende version. At åbne hvert commit og læse hver diff er sjældent den hurtigste løsning.

Git indeholder et værktøj, der er designet til præcis denne situation: git bisect. I stedet for at undersøge hvert commit bruger det en binær søgning til at identificere den revision, der først indførte problemet. Med en pålidelig test kan du automatisere undersøgelsen.

I denne vejledning opretter du et lille PHP-projekt, indfører bevidst en regression, lokaliserer den med Git bisect og lærer, hvordan du anvender den samme teknik på rigtige projekter.

1. Sådan fungerer Git bisect

Forestil dig, at din applikation fungerede ved commit A, men fejler ved commit H. Git bisect har brug for to referencepunkter: et good commit, hvor funktionen helt sikkert fungerede, og et bad commit, hvor fejlen helt sikkert findes.

Det tjekker en mellemliggende revision ud. Du tester den, rapporterer, om den fungerer, og Git reducerer det resterende søgeområde. For cirka 128 kandidatcommits kræver binær søgning typisk omkring syv tests i stedet for at inspicere alle 128, forudsat at adfærden kan klassificeres konsistent.

Den officielle Git-dokumentation beskriver processen og dens begrænsninger.

2. Opret en reproducerbar PHP-regression

Vi bygger en lille funktion til prisberegning. Intet framework, ingen database, ingen Composer-pakke og ingen webserver er påkrævet. Du skal have Git og PHP CLI installeret, og Git skal have dit forfatternavn og din e-mail konfigureret til commits.

Opret en mappe og initialiser et arkiv:

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

Opret price.php:

<?php

declare(strict_types=1);

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

Den forventede adfærd er ligetil: finalPrice(100, 20) returnerer 80.

Commit denne fungerende version:

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

Opret derefter en urelateret ændring:

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

Indfør endelig en fejl ved at ændre beregningen i price.php:

<?php

declare(strict_types=1);

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

Commit den defekte version:

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

Projektet har nu tre commits med en bevidst regression i den sidste.

3. Find regressionen manuelt

Begynd med at bekræfte, at dit arbejdstræ er rent:

git status --short

Kommandoen bør ikke give noget output. Hvis du har ucommittet arbejde, så commit det passende, eller stash det, før du begynder.

Start nu Git bisect:

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

Her er HEAD den defekte revision, mens HEAD~2 peger på det første, fungerende commit. Git tjekker det mellemliggende commit ud.

Test beregningen:

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

Hvis outputtet er 80, så markér revisionen som god:

git bisect good

Hvis det er 120, så markér den som dårlig:

git bisect bad

Git fortsætter med at vælge commits, indtil den identificerer den første dårlige revision. I denne demonstration med tre commits er der kun én mellemliggende revision, der skal testes.

Når du er færdig, så gendan din oprindelige gren:

git bisect reset

Under bisect tjekker Git normalt historiske revisioner ud i en detached HEAD-tilstand. git bisect reset fører dig tilbage til den revision, du brugte før undersøgelsen.

4. Automatiser undersøgelsen med git bisect run

Manuel test er nyttig, når en fejl kræver visuel inspektion. Men hvis adfærden kan kontrolleres med en kommando, er automatisering mere effektiv.

Git understøtter git bisect run <command>. Kommandoen kommunikerer sit resultat via en exit code:

Exit code Betydning
0 God revision
1–124 eller 126–127 Dårlig revision
125 Kan ikke teste denne revision
Andre værdier Afbryd undersøgelsen

Disse regler stammer fra den officielle Git bisect-manual.

Opret et testscript uden for arkivet, såsom ../check-price.php:

<?php

declare(strict_types=1);

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

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

Scriptet antager, at projektmappen hedder git-bisect-demo og ligger ved siden af check-price.php. Kør disse kommandoer inde i projektmappen:

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

Git kører testen på udvalgte historiske revisioner, indtil det første dårlige commit er identificeret. Fordi testscriptet ligger uden for arkivet, fjerner udtjekning af en ældre revision det ikke.

Til rigtige projekter skal du bruge en stabil testkommando eller et eksternt testscript, der fungerer med de historiske revisioner, der undersøges.

5. Anvend teknikken på et rigtigt webprojekt

Den samme arbejdsgang virker for et WordPress-plugin, en Joomla-udvidelse, en JavaScript-applikation eller et PHP-bibliotek.

Forestil dig, at en checkout-funktion er defekt i den nyeste version, men at den fungerede i release v1.4.0. Verificér først, at releasen faktisk er god, og start derefter:

git bisect start HEAD v1.4.0

Hvis projektet har en PHPUnit-test, der fungerer på tværs af de udvalgte revisioner, kan du køre den manuelt:

vendor/bin/phpunit tests/CheckoutTest.php

Efter hver test skal du rapportere git bisect good eller git bisect bad.

Når testen er pålideligt automatiseret:

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

Historiske commits kan kræve forskellige PHP-versioner, afhængigheder, databaseskemaer eller buildværktøjer. En test, der fejler, fordi miljøet er inkompatibelt, indikerer ikke nødvendigvis regressionen. Sørg for, at dit testmiljø kan genskabe de relevante historiske versioner.

Technical workflow illustration

6. Hvad hvis et gammelt commit ikke kan testes?

Nogle gange mislykkes en historisk revision med at bygge af en urelateret årsag. Markér den ikke automatisk som dårlig.

Brug:

git bisect skip

Git prøver en anden kandidat. Til automatiserede tests fortæller exit code 125 Git, at den skal springe revisionen over.

At springe for mange commits over reducerer præcisionen. Hvis et utestbart commit ligger ved siden af regressionen, kan Git rapportere flere mulige syndere i stedet for ét præcist commit.

En god langsigtet praksis er at vedligeholde reproducerbare udviklingsmiljøer, låse afhængighedsversioner og holde kritiske regressionstests uafhængige af urelateret infrastruktur.

7. Inspicér det commit, der indførte fejlen

Når Git har identificeret det første dårlige commit, så undersøg det:

git show <commit-hash>

For at se, hvilke filer der blev ændret:

git show --stat <commit-hash>

For at inspicere en bestemt fil:

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

Det første dårlige commit er ikke nødvendigvis den eneste årsag til fejlen. Et commit kan blotlægge et tidligere skjult problem, interagere med en anden ændring eller afhænge af en ekstern tjeneste, der siden har ændret sig.

Brug det identificerede commit til at undersøge rodårsagen, ikke som automatisk bevis på, at hver linje i det commit er forkert.

8. Almindelige problemer og løsninger

Fejlen opstår inkonsekvent

Hvis en test nogle gange består og nogle gange fejler på den samme revision, bliver bisect-resultaterne upålidelige. Kør testen flere gange, fjern tidsafhængigheder, hvor det er muligt, og kontrollér eksterne input. Gentagen test forbedrer tilliden, men øger undersøgelsestiden.

Testen fejler på hver historisk revision

Bekræft, at dit kendte gode commit virkelig er godt. Tjek den revision ud separat og kør testen, før du begynder en ny bisect-session. Hvis den også fejler der, kan din test eller dit miljø være forkert.

Git nægter at skifte revisioner

Ucommittede ændringer kan forhindre checkout. Kontrollér git status og gem dine ændringer, før du genstarter. Undgå destruktive kommandoer såsom git reset --hard, medmindre du forstår præcis, hvad de kasserer.

Historikken indeholder mange merge commits

Til komplekse arkiver understøtter Git:

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

Dette følger first-parent-historikken og kan hjælpe med at undersøge regressioner, der blev indført via merges. Det ændrer, hvilke commits der overvejes, så det er ikke en universel erstatning for en normal bisect.

Fejlen afhænger af produktionsdata

Kør aldrig historisk applikationskode mod en live produktionsdatabase. Brug et isoleret testmiljø med saniterede fixtures og et reproducerbart skema. Ældre revisioner kan indeholde migrationer eller antagelser, der er inkompatible med produktionen.

9. En praktisk fejlfindingstjekliste

  • Bekræft, at fejlen er reproducerbar.
  • Identificér én revision, der er kendt for at fungere, og én, der er kendt for at fejle.
  • Gem ucommittet arbejde.
  • Definér en pålidelig test med et klart bestå/fejl-resultat.
  • Hold eksterne tjenester og testdata konsistente.
  • Brug git bisect skip til revisioner, der er reelt utestbare.
  • Inspicér det identificerede commit og verificér rodårsagen.
  • Afslut med git bisect reset.

Konklusion

Git bisect forvandler en usikker fejlfindingstaske til en struktureret undersøgelse. I stedet for at gætte, hvilken nylig ændring der ødelagde en applikation, identificerer du en fungerende revision, en defekt revision og lader Git indsnævre historikken.

Teknikken bliver især kraftfuld, når den kombineres med automatiserede tests. En regression skjult blandt hundredvis af commits kan ofte lokaliseres med kun en håndfuld kontroller.

For udviklere, der vedligeholder langlivede PHP-projekter, WordPress-plugins, Joomla-udvidelser eller JavaScript-applikationer, er git bisect en af de mest nyttige Git-kommandoer ud over den daglige branching og merging.