Git Bisect: Vind de Commit die een bug heeft geïntroduceerd
Een functie werkte gisteren maar faalt vandaag. Leer hoe je Git bisect kunt gebruiken om de commit te identificeren die een regressie heeft geïntroduceerd, revisies automatisch te testen en het resultaat veilig te onderzoeken.
Een website werkte vorige week. Vandaag is een checkout-berekening fout, reageert een JavaScript-component niet meer, of geeft een PHP-eindpunt onverwachte gegevens terug.
Je weet dat de bug ergens in de Git-geschiedenis is opgetreden, maar de repository bevat tientallen of honderden commits sinds de laatste werkende versie. Elke commit openen en elk diff lezen is zelden de snelste oplossing.
Git bevat een hulpmiddel dat speciaal voor deze situatie is ontworpen: git bisect. In plaats van elke commit te onderzoeken, gebruikt het een binaire zoekmethode om de revisie te identificeren die het probleem als eerste heeft geïntroduceerd. Met een betrouwbare test kun je het onderzoek automatiseren.
In deze zelfstudie maak je een klein PHP-project, introduceer je opzettelijk een regressie, lokaliseer je het met Git bisect en leer je hoe je dezelfde techniek op echte projecten kunt toepassen.
1. Hoe Git bisect werkt
Stel dat je applicatie werkte bij commit A, maar faalt bij commit H. Git bisect heeft twee referentiepunten nodig: een goede commit, waar de functie zeker werkte, en een foute commit, waar de bug zeker bestaat.
Het checkt een tussenliggende revisie uit. Je test het, rapporteert of het werkt, en Git verkleint het resterende zoekbereik. Bij ongeveer 128 candidate commits vereist binaire zoekopdracht doorgaans zo'n zeven tests in plaats van alle 128 te inspecteren, mits het gedrag consistent kan worden geclassificeerd.
De officiële Git-documentatie beschrijft het proces en de beperkingen ervan.
2. Een reproduceerbare PHP-regressie maken
We bouwen een kleine prijsberekeningsfunctie. Geen framework, database, Composer-pakket of webserver vereist. Je hebt Git en PHP CLI nodig, en Git moet je auteurnaam en e-mailadres hebben geconfigureerd voor commits.
Maak een map en initialiseer een repository:
mkdir git-bisect-demo
cd git-bisect-demo
git init
Maak price.php aan:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
Het verwachte gedrag is eenvoudig: finalPrice(100, 20) retourneert 80.
Commit deze werkende versie:
git add price.php
git commit -m "Add working price calculation"
Maak vervolgens een niet-gerelateerde wijziging:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
Introduceer ten slotte een bug door de berekening in price.php te wijzigen:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
Commit de kapotte versie:
git add price.php
git commit -m "Refactor price calculation"
Het project heeft nu drie commits, met een opzettelijke regressie in de laatste.
3. De regressie handmatig vinden
Begin met het bevestigen dat je working tree schoon is:
git status --short
De opdracht zou geen output moeten produceren. Als je ongecommitteerd werk hebt, commit dit dan op de juiste manier of stash het voordat je begint.
Start nu Git bisect:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

Hier is HEAD de kapotte revisie, terwijl HEAD~2 wijst naar de eerste, werkende commit. Git checkt de tussenliggende commit uit.
Test de berekening:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
Als de output 80 is, markeer de revisie dan als goed:
git bisect good
Als het 120 is, markeer het dan als fout:
git bisect bad
Git blijft commits selecteren tot het de eerste foute revisie heeft geïdentificeerd. Bij deze demonstratie van drie commits hoeft er slechts één tussenliggende revisie te worden getest.
Als je klaar is, herstel dan je oorspronkelijke branch:
git bisect reset
Tijdens bisect checkt Git normaal gesproken historische revisies uit in een losgekoppelde HEAD-status. git bisect reset brengt je terug naar de revisie die je voor het onderzoek gebruikte.
4. Het onderzoek automatiseren met git bisect run
Handmatig testen is handig wanneer een bug visuele inspectie vereist. Maar als het gedrag door een opdracht kan worden gecontroleerd, is automatisering efficiënter.
Git ondersteunt git bisect run <command>. De opdracht communiceert het resultaat via een afsluitcode:
| Afsluitcode | Betekenis |
|---|---|
0 |
Goede revisie |
1–124 of 126–127 |
Foute revisie |
125 |
Kan deze revisie niet testen |
| Andere waarden | Onderzoek afbreken |
Deze regels komen uit de officiële Git bisect-handleiding.
Maak een testscript buiten de repository, zoals ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
Het script ervan uitgaat dat de projectmap git-bisect-demo heet en naast check-price.php ligt. Voer deze opdrachten uit vanuit de projectmap:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git voert de test uit op geselecteerde historische revisies tot de eerste foute commit is geïdentificeerd. Omdat het testscript buiten de repository staat, verwijdert het uitchecken van een oudere revisie dit niet.
Gebruik voor echte projecten een stabiele testopdracht of een extern testscript dat werkt met de onderzochte historische revisies.
5. Pas de techniek toe op een echt webproject
Hetzelfde werkproces werkt voor een WordPress-plug-in, Joomla-extensie, JavaScript-applicatie of PHP-bibliotheek.
Stel dat een checkout-functie kapot is in de nieuwste versie, maar dat het werkte in release v1.4.0. Verifieer eerst of de release werkelijk goed is, start dan:
git bisect start HEAD v1.4.0
Als het project een PHPUnit-test heeft die werkt over de geselecteerde revisies, kun je deze handmatig uitvoeren:
vendor/bin/phpunit tests/CheckoutTest.php
Rapporteer na elke test git bisect good of git bisect bad.
Wanneer de test betrouwbaar is geautomatiseerd:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
Historische commits kunnen verschillende PHP-versies, afhankelijkheden, databaseschema's of buildtools vereisen. Een test die faalt vanwege een incompatibele omgeving hoeft niet noodzakelijkerwijs de regressie aan te duiden. Zorg ervoor dat je testomgeving de relevante historische versies kan reproduceren.

6. Wat als een oude commit niet kan worden getest?
Soms mislukt het bouwen van een historische revisie om een niet-gerelateerde reden. Markeer het niet automatisch als fout.
Gebruik:
git bisect skip
Git probeert een andere kandidaat. Voor geautomatiseerde tests geeft afsluitcode 125 aan dat Git de revisie moet overslaan.
Te veel commits overslaan vermindert de nauwkeurigheid. Als een niet-testbare commit grenst aan de regressie, kan Git meerdere mogelijke schuldigen melden in plaats van één exacte commit.
Een goede lange-termijnpraktijk is om reproduceerbare ontwikkelomgevingen te onderhouden, afhankelijkheidsversies te vergrendelen en kritieke regressietests onafhankelijk te houden van niet-gerelateerde infrastructuur.
7. De commit inspecteren die de bug heeft geïntroduceerd
Zodra Git de eerste foute commit heeft geïdentificeerd, onderzoekt u deze:
git show <commit-hash>
Om te zien welke bestanden zijn gewijzigd:
git show --stat <commit-hash>
Om een specifiek bestand te inspecteren:
git show <commit-hash> -- price.php
De eerste foute commit is niet noodzakelijkerwijs de enige oorzaak van de bug. Een commit kan een eerder verborgen probleem blootleggen, interageren met een andere wijziging, of afhankelijk zijn van een externe dienst die intussen is veranderd.
Gebruik de geïdentificeerde commit om de hoofdoorzaak te onderzoeken, niet als automatisch bewijs dat elke regel in die commit onjuist is.
8. Veelvoorkomende problemen en oplossingen
De bug doet zich onregelmatig voor
Als een test soms slaagt en soms faalt bij dezelfde revisie, worden bisect-resultaten onbetrouwbaar. Voer de test meerdere keren uit, elimineer afhankelijkheden van timing waar mogelijk, en beheer externe invoer. Herhaald testen vergroot het vertrouwen, maar verlengt de onderzoektijd.
De test faalt bij elke historische revisie
Bevestig dat je bekende goede commit echt goed is. Check die revisie apart uit en voer de test uit voordat je een nieuwe bisect-sessie begint. Als het daar ook faalt, kan je test of omgeving onjuist zijn.
Git weigert overschakelen van revisies
Ongecommitteerde wijzigingen kunnen uitchecken voorkomen. Controleer git status en bewaar je wijzigingen voordat je opnieuw start. Vermijd destructieve opdrachten zoals git reset --hard tenzij je precies begrijpt wat ze weggooien.
De geschiedenis bevat veel merge-commits
Voor complexe repositories ondersteunt Git:
git bisect start --first-parent HEAD v1.4.0
Dit volgt first-parent-geschiedenis en kan helpen bij het onderzoeken van regressies die via merges zijn geïntroduceerd. Het verandert welke commits worden overwogen, dus het is geen universele vervanging voor een normale bisect.
De bug is afhankelijk van productiegegevens
Run nooit historische applicatiecode uit tegen een live productiedatabase. Gebruik een geïsoleerde testomgeving met gesanitiseerde fixtures en een reproduceerbaar schema. Oudere revisies kunnen migraties of aannames bevatten die incompatibel zijn met productie.
9. Een praktische debugchecklist
- Bevestig dat de bug reproduceerbaar is.
- Identificeer één revisie die je weet werkt en één die je weet faalt.
- Bewaar ongecommitteerd werk.
- Definieer een betrouwbare test met een duidelijk geslaagd/gefaald resultaat.
- Houd externe diensten en testgegevens consistent.
- Gebruik
git bisect skipvoor echt niet-testbare revisies. - Onderzoek de geïdentificeerde commit en verifieer de hoofdoorzaak.
- Sluit af met
git bisect reset.
Conclusie
Git bisect verandert een onzekere debugtaak in een gestructureerd onderzoek. In plaats van te raden welke recente wijziging een applicatie heeft stukgemaakt, identificeer je een werkende revisie, een kapotte revisie, en laat je Git de geschiedenis beperken.
De techniek wordt bijzonder krachtig wanneer deze wordt gecombineerd met geautomatiseerde tests. Een regressie die verborgen zit tussen honderden commits, kan vaak worden gelokaliseerd met slechts een handvol controles.
Voor ontwikkelaars die langdurige PHP-projecten, WordPress-plug-ins, Joomla-extensies of JavaScript-applicaties onderhouden, is git bisect een van de meest nuttige Git-opdrachten naast alledaags branching en mergen.