Git Bisect: Finde den Commit, der einen Bug eingeführt hat
Eine Funktion hat gestern funktioniert, heute jedoch nicht mehr. Lerne, wie du Git bisect nutzt, um den Commit zu identifizieren, der die Regression verursacht hat, Revisionen automatisch testest und das Ergebnis sicher untersuchst.
Git Bisect: Den Commit finden, der einen Fehler eingeführt hat
Eine Website funktionierte letzte Woche noch. Heute ist eine Checkout-Berechnung falsch, eine JavaScript-Komponente reagiert nicht mehr oder ein PHP-Endpunkt liefert unerwartete Daten.
Du weißt, dass der Fehler irgendwo in der Git-Historie aufgetreten ist, aber das Repository enthält seit der letzten funktionierenden Version Dutzende oder Hunderte von Commits. Jeden Commit zu öffnen und jeden Diff zu lesen ist selten die schnellste Lösung.
Git enthält ein Werkzeug, das genau für diese Situation entwickelt wurde: git bisect. Anstatt jeden Commit zu untersuchen, verwendet es eine binäre Suche, um die Revision zu identifizieren, die das Problem erstmals eingeführt hat. Mit einem zuverlässigen Test kannst du die Untersuchung automatisieren.
In diesem Tutorial erstellst du ein kleines PHP-Projekt, fügst absichtlich eine Regression ein, findest sie mit Git bisect und lernst, wie du dieselbe Technik auf echte Projekte anwendest.
1. Wie Git bisect funktioniert
Stell dir vor, deine Anwendung funktionierte bei Commit A, schlägt aber bei Commit H fehl. Git bisect benötigt zwei Referenzpunkte: einen guten Commit, bei dem die Funktion definitiv funktioniert hat, und einen schlechten Commit, bei dem der Fehler definitiv vorhanden ist.
Es checkt eine zwischenliegende Revision aus. Du testest sie, meldest, ob sie funktioniert, und Git reduziert den verbleibenden Suchbereich. Bei etwa 128 Kandidaten-Commits erfordert die binäre Suche typischerweise rund sieben Tests anstatt alle 128 zu untersuchen, sofern sich das Verhalten konsistent klassifizieren lässt.
Die offizielle Git-Dokumentation beschreibt den Prozess und seine Einschränkungen.
2. Eine reproduzierbare PHP-Regression erstellen
Wir erstellen eine winzige Preisberechnungsfunktion. Kein Framework, keine Datenbank, kein Composer-Paket und kein Webserver sind erforderlich. Du benötigst installiertes Git und PHP CLI, und Git muss für Commits deinen Autorennamen und deine E-Mail-Adresse konfiguriert haben.
Erstelle ein Verzeichnis und initialisiere ein Repository:
mkdir git-bisect-demo
cd git-bisect-demo
git init
Erstelle price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
Das erwartete Verhalten ist einfach: finalPrice(100, 20) gibt 80 zurück.
Committe diese funktionierende Version:
git add price.php
git commit -m "Add working price calculation"
Erstelle als Nächstes eine unabhängige Änderung:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
Füge schließlich einen Fehler ein, indem du die Berechnung in price.php änderst:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
Committe die fehlerhafte Version:
git add price.php
git commit -m "Refactor price calculation"
Das Projekt hat nun drei Commits, mit einer absichtlichen Regression im letzten.
3. Die Regression manuell finden
Beginne damit, zu bestätigen, dass dein Arbeitsbaum sauber ist:
git status --short
Der Befehl sollte keine Ausgabe erzeugen. Wenn du nicht committete Änderungen hast, committe sie angemessen oder stash sie, bevor du beginnst.
Starte jetzt Git bisect:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

Hier ist HEAD die fehlerhafte Revision, während HEAD~2 auf den ersten, funktionierenden Commit zeigt. Git checkt den zwischenliegenden Commit aus.
Teste die Berechnung:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
Wenn die Ausgabe 80 ist, markiere die Revision als gut:
git bisect good
Wenn sie 120 ist, markiere sie als schlecht:
git bisect bad
Git wählt weiterhin Commits aus, bis es die erste fehlerhafte Revision identifiziert. In dieser Demonstration mit drei Commits muss nur eine zwischenliegende Revision getestet werden.
Wenn du fertig bist, stelle deinen ursprünglichen Branch wieder her:
git bisect reset
Während des Bisects checkt Git historische Revisionen normalerweise im Zustand eines losgelösten HEAD (detached HEAD) aus. git bisect reset bringt dich zu der Revision zurück, die du vor der Untersuchung verwendet hast.
4. Die Untersuchung mit git bisect run automatisieren
Manuelles Testen ist nützlich, wenn ein Fehler eine visuelle Prüfung erfordert. Wenn das Verhalten aber durch einen Befehl überprüft werden kann, ist die Automatisierung effizienter.
Git unterstützt git bisect run <command>. Der Befehl teilt sein Ergebnis über einen Exit-Code mit:
| Exit-Code | Bedeutung |
|---|---|
0 |
Gute Revision |
1–124 oder 126–127 |
Schlechte Revision |
125 |
Diese Revision kann nicht getestet werden |
| Andere Werte | Die Untersuchung abbrechen |
Diese Regeln stammen aus dem offiziellen Git-bisect-Handbuch.
Erstelle ein Testskript außerhalb des Repositories, zum Beispiel ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
Das Skript geht davon aus, dass der Projektordner git-bisect-demo heißt und neben check-price.php liegt. Führe diese Befehle von innerhalb des Projektordners aus:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git führt den Test auf ausgewählten historischen Revisionen aus, bis der erste fehlerhafte Commit identifiziert ist. Da das Testskript außerhalb des Repositories liegt, entfernt das Auschecken einer älteren Revision es nicht.
Verwende für echte Projekte einen stabilen Testbefehl oder ein externes Testskript, das mit den untersuchten historischen Revisionen funktioniert.
5. Die Technik auf ein echtes Webprojekt anwenden
Derselbe Workflow funktioniert für ein WordPress-Plugin, eine Joomla-Erweiterung, eine JavaScript-Anwendung oder eine PHP-Bibliothek.
Angenommen, eine Checkout-Funktion ist in der neuesten Version defekt, hat aber in Release v1.4.0 funktioniert. Überprüfe zuerst, ob das Release tatsächlich gut ist, und starte dann:
git bisect start HEAD v1.4.0
Wenn das Projekt einen PHPUnit-Test hat, der über die ausgewählten Revisionen hinweg funktioniert, kannst du ihn manuell ausführen:
vendor/bin/phpunit tests/CheckoutTest.php
Melde nach jedem Test git bisect good oder git bisect bad.
Wenn der Test zuverlässig automatisiert ist:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
Historische Commits können unterschiedliche PHP-Versionen, Abhängigkeiten, Datenbankschemata oder Build-Werkzeuge erfordern. Ein Test, der fehlschlägt, weil die Umgebung inkompatibel ist, deutet nicht zwangsläufig auf die Regression hin. Stelle sicher, dass deine Testumgebung die relevanten historischen Versionen reproduzieren kann.

6. Was, wenn ein alter Commit nicht getestet werden kann?
Manchmal schlägt eine historische Revision aus einem unabhängigen Grund beim Build fehl. Markiere sie nicht automatisch als schlecht.
Verwende:
git bisect skip
Git versucht einen anderen Kandidaten. Bei automatisierten Tests teilt der Exit-Code 125 Git mit, die Revision zu überspringen.
Zu viele Commits zu überspringen verringert die Genauigkeit. Wenn ein nicht testbarer Commit neben der Regression liegt, kann Git mehrere mögliche Verursacher anstelle eines exakten Commits melden.
Eine gute langfristige Praxis besteht darin, reproduzierbare Entwicklungsumgebungen zu pflegen, Abhängigkeitsversionen festzuschreiben (locken) und kritische Regressionstests unabhängig von unzusammenhängender Infrastruktur zu halten.
7. Den Commit untersuchen, der den Fehler eingeführt hat
Sobald Git den ersten fehlerhaften Commit identifiziert, untersuche ihn:
git show <commit-hash>
Um zu sehen, welche Dateien geändert wurden:
git show --stat <commit-hash>
Um eine bestimmte Datei zu untersuchen:
git show <commit-hash> -- price.php
Der erste fehlerhafte Commit ist nicht zwangsläufig die einzige Ursache des Fehlers. Ein Commit könnte ein zuvor verborgenes Problem aufdecken, mit einer anderen Änderung interagieren oder von einem externen Dienst abhängen, der sich inzwischen geändert hat.
Verwende den identifizierten Commit, um die Grundursache zu untersuchen, nicht als automatischen Beweis dafür, dass jede Zeile in diesem Commit falsch ist.
8. Häufige Probleme und Lösungen
Der Fehler tritt inkonsistent auf
Wenn ein Test auf derselben Revision manchmal besteht und manchmal fehlschlägt, werden die Bisect-Ergebnisse unzuverlässig. Führe den Test mehrmals aus, entferne wo möglich zeitabhängige Abhängigkeiten und kontrolliere externe Eingaben. Wiederholtes Testen verbessert die Sicherheit, erhöht aber die Untersuchungszeit.
Der Test schlägt bei jeder historischen Revision fehl
Bestätige, dass dein bekannt-guter Commit wirklich gut ist. Checke diese Revision separat aus und führe den Test aus, bevor du eine neue Bisect-Sitzung beginnst. Wenn er dort ebenfalls fehlschlägt, sind möglicherweise dein Test oder deine Umgebung fehlerhaft.
Git weigert sich, die Revision zu wechseln
Nicht committete Änderungen können das Auschecken verhindern. Überprüfe git status und sichere deine Änderungen, bevor du neu startest. Vermeide destruktive Befehle wie git reset --hard, sofern du nicht genau verstehst, was sie verwerfen.
Die Historie enthält viele Merge-Commits
Für komplexe Repositories unterstützt Git:
git bisect start --first-parent HEAD v1.4.0
Dies folgt der First-Parent-Historie und kann helfen, Regressionen zu untersuchen, die durch Merges eingeführt wurden. Es ändert, welche Commits berücksichtigt werden, und ist daher kein universeller Ersatz für einen normalen Bisect.
Der Fehler hängt von Produktionsdaten ab
Führe historischen Anwendungscode niemals gegen eine Live-Produktionsdatenbank aus. Verwende eine isolierte Testumgebung mit bereinigten Fixtures und einem reproduzierbaren Schema. Ältere Revisionen können Migrationen oder Annahmen enthalten, die mit der Produktion inkompatibel sind.
9. Eine praktische Debugging-Checkliste
- Bestätige, dass der Fehler reproduzierbar ist.
- Identifiziere eine Revision, von der bekannt ist, dass sie funktioniert, und eine, von der bekannt ist, dass sie fehlschlägt.
- Sichere nicht committete Änderungen.
- Definiere einen zuverlässigen Test mit einem klaren Bestanden-/Fehlgeschlagen-Ergebnis.
- Halte externe Dienste und Testdaten konsistent.
- Verwende
git bisect skipfür wirklich nicht testbare Revisionen. - Untersuche den identifizierten Commit und überprüfe die Grundursache.
- Beende den Vorgang mit
git bisect reset.
Fazit
Git bisect verwandelt eine unsichere Debugging-Aufgabe in eine strukturierte Untersuchung. Anstatt zu raten, welche kürzliche Änderung eine Anwendung zerstört hat, identifizierst du eine funktionierende Revision, eine fehlerhafte Revision und lässt Git die Historie eingrenzen.
Die Technik wird besonders mächtig, wenn sie mit automatisierten Tests kombiniert wird. Eine Regression, die unter Hunderten von Commits verborgen ist, lässt sich oft mit nur einer Handvoll Prüfungen lokalisieren.
Für Entwickler, die langlebige PHP-Projekte, WordPress-Plugins, Joomla-Erweiterungen oder JavaScript-Anwendungen pflegen, ist git bisect einer der nützlichsten Git-Befehle über das alltägliche Branching und Merging hinaus.