English ▾ Themen ▾ Neueste Version ▾ git-bisect zuletzt aktualisiert in 2.52.0

NAME

git-bisect - Binäre Suche zum Finden des Commits, der einen Fehler eingeführt hat

SYNOPSIS

git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
		   [--no-checkout] [--first-parent] [<bad> [<good>…​]] [--] [<pathspec>…​]
git bisect (bad|new|<term-new>) [<rev>]
git bisect (good|old|<term-old>) [<rev>…​]
git bisect terms [--term-(good|old) | --term-(bad|new)]
git bisect skip [(<rev>|<range>)…​]
git bisect next
git bisect reset [<commit>]
git bisect (visualize|view)
git bisect replay <logfile>
git bisect log
git bisect run <cmd> [<arg>…​]
git bisect help

BESCHREIBUNG

Dieser Befehl verwendet einen binären Suchalgorithmus, um herauszufinden, welcher Commit in der Historie Ihres Projekts einen Fehler eingeführt hat. Sie verwenden ihn, indem Sie ihm zunächst einen "schlechten" Commit mitteilen, von dem bekannt ist, dass er den Fehler enthält, und einen "guten" Commit, von dem bekannt ist, dass er vor der Einführung des Fehlers liegt. Dann wählt git bisect einen Commit zwischen diesen beiden Endpunkten aus und fragt Sie, ob der ausgewählte Commit "gut" oder "schlecht" ist. Es wird der Bereich weiter eingegrenzt, bis der genaue Commit gefunden wird, der die Änderung eingeführt hat.

Tatsächlich kann git bisect verwendet werden, um den Commit zu finden, der beliebige Eigenschaften Ihres Projekts geändert hat; z.B. den Commit, der einen Fehler behoben hat, oder den Commit, der die Leistung eines Benchmarks verbessert hat. Um diese allgemeinere Verwendung zu unterstützen, können die Begriffe "alt" und "neu" anstelle von "gut" und "schlecht" verwendet werden, oder Sie können Ihre eigenen Begriffe wählen. Weitere Informationen finden Sie im Abschnitt "Alternative Begriffe" weiter unten.

Grundlegende Bisect-Befehle: start, bad, good

Nehmen wir zum Beispiel an, Sie versuchen, den Commit zu finden, der eine Funktion beeinträchtigt hat, von der bekannt ist, dass sie in Version v2.6.13-rc2 Ihres Projekts funktionierte. Sie starten eine Bisect-Sitzung wie folgt:

$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good

Sobald Sie mindestens einen schlechten und einen guten Commit angegeben haben, wählt git bisect einen Commit in der Mitte dieses Verlaufs aus, checked ihn aus und gibt etwas Ähnliches wie das Folgende aus:

Bisecting: 675 revisions left to test after this (roughly 10 steps)

Sie sollten nun die ausgecheckte Version kompilieren und testen. Wenn diese Version korrekt funktioniert, geben Sie ein:

$ git bisect good

Wenn diese Version fehlerhaft ist, geben Sie ein:

$ git bisect bad

Dann wird git bisect mit etwas wie dem Folgenden antworten:

Bisecting: 337 revisions left to test after this (roughly 9 steps)

Wiederholen Sie den Vorgang: kompilieren Sie den Baum, testen Sie ihn und geben Sie je nachdem, ob er gut oder schlecht ist, git bisect good oder git bisect bad ein, um nach dem nächsten zu testenden Commit zu fragen.

Schließlich werden keine Revisionen mehr zu inspizieren sein, und der Befehl gibt eine Beschreibung des ersten fehlerhaften Commits aus. Die Referenz refs/bisect/bad wird auf diesen Commit zeigen.

Bisect zurücksetzen

Um nach einer Bisect-Sitzung den Bisect-Zustand zu bereinigen und zum ursprünglichen HEAD zurückzukehren, geben Sie den folgenden Befehl ein:

$ git bisect reset

Standardmäßig wird Ihr Baum auf den Commit zurückgesetzt, der vor git bisect start ausgecheckt war. (Ein neues git bisect start tut dies ebenfalls, da es den alten Bisect-Zustand bereinigt.)

Mit einem optionalen Argument können Sie stattdessen zu einem anderen Commit zurückkehren:

$ git bisect reset <commit>

Zum Beispiel wird git bisect reset bisect/bad die erste fehlerhafte Revision auschecken, während git bisect reset HEAD Sie auf dem aktuellen Bisect-Commit belässt und gar keine Commits wechselt.

Alternative Begriffe

Manchmal suchen Sie nicht nach dem Commit, der einen Fehler eingeführt hat, sondern nach einem Commit, der eine Änderung zwischen einem anderen "alten" Zustand und einem "neuen" Zustand verursacht hat. Zum Beispiel könnten Sie nach dem Commit suchen, der eine bestimmte Korrektur eingeführt hat. Oder Sie suchen nach dem ersten Commit, in dem die Dateinamen im Quellcode endlich alle dem Namensstandard Ihres Unternehmens entsprachen. Oder was auch immer.

In solchen Fällen kann es sehr verwirrend sein, die Begriffe "gut" und "schlecht" zu verwenden, um sich auf "den Zustand vor der Änderung" und "den Zustand nach der Änderung" zu beziehen. Stattdessen können Sie die Begriffe "alt" und "neu" in Bezug auf "gut" und "schlecht" verwenden. (Beachten Sie jedoch, dass Sie "gut" und "schlecht" nicht mit "alt" und "neu" in einer einzigen Sitzung mischen können.)

Bei dieser allgemeineren Verwendung geben Sie git bisect einen "neuen" Commit, der eine bestimmte Eigenschaft hat, und einen "alten" Commit, der diese Eigenschaft nicht hat. Jedes Mal, wenn git bisect einen Commit auscheckt, testen Sie, ob der Commit die Eigenschaft hat. Wenn ja, markieren Sie den Commit als "neu"; andernfalls markieren Sie ihn als "alt". Wenn die Bisectierung abgeschlossen ist, meldet git bisect, welcher Commit die Eigenschaft eingeführt hat.

Um "alt" und "neu" anstelle von "gut" und "schlecht" zu verwenden, müssen Sie git bisect start ohne Argumente ausführen und dann die folgenden Befehle ausführen, um die Commits hinzuzufügen:

git bisect old [<rev>]

um anzuzeigen, dass ein Commit vor der gesuchten Änderung lag, oder

git bisect new [<rev>...]

um anzuzeigen, dass er danach lag.

Um eine Erinnerung an die aktuell verwendeten Begriffe zu erhalten, verwenden Sie:

git bisect terms

Sie können nur den alten Begriff mit git bisect terms --term-old oder git bisect terms --term-good abrufen; git bisect terms --term-new und git bisect terms --term-bad können verwendet werden, um zu erfahren, wie die Commits aufgerufen werden sollen, die neuer als die gesuchte Änderung sind.

Wenn Sie Ihre eigenen Begriffe anstelle von "schlecht"/"gut" oder "neu"/"alt" verwenden möchten, können Sie beliebige Namen wählen (außer bestehenden Bisect-Unterbefehlen wie reset, start, …), indem Sie die Bisectierung mit folgendem Befehl starten:

git bisect start --term-old <term-old> --term-new <term-new>

Wenn Sie beispielsweise nach einem Commit suchen, der eine Leistungsregression eingeführt hat, könnten Sie verwenden:

git bisect start --term-old fast --term-new slow

Oder wenn Sie nach dem Commit suchen, der einen Fehler behoben hat, könnten Sie verwenden:

git bisect start --term-new fixed --term-old broken

Verwenden Sie dann git bisect <term-old> und git bisect <term-new> anstelle von git bisect good und git bisect bad, um Commits zu markieren.

Bisect visualisieren/anzeigen

Um die verbleibenden Verdächtigen in gitk anzuzeigen, geben Sie während des Bisect-Vorgangs den folgenden Befehl ein (der Unterbefehl view kann als Alternative zu visualize verwendet werden):

$ git bisect visualize

Git erkennt eine grafische Umgebung anhand verschiedener Umgebungsvariablen: DISPLAY, die in X Window System-Umgebungen unter Unix-Systemen gesetzt wird. SESSIONNAME, die unter Cygwin in interaktiven Desktop-Sitzungen gesetzt wird. MSYSTEM, die unter Msys2 und Git für Windows gesetzt wird. SECURITYSESSIONID, die unter macOS in interaktiven Desktop-Sitzungen gesetzt werden kann.

Wenn keine dieser Umgebungsvariablen gesetzt ist, wird stattdessen git log verwendet. Sie können auch Befehlszeilenoptionen wie -p und --stat übergeben.

$ git bisect visualize --stat

Bisect log und bisect replay

Nachdem Sie Revisionen als gut oder schlecht markiert haben, geben Sie den folgenden Befehl ein, um anzuzeigen, was bisher getan wurde:

$ git bisect log

Wenn Sie feststellen, dass Sie einen Fehler bei der Angabe des Status einer Revision gemacht haben, können Sie die Ausgabe dieses Befehls in eine Datei speichern, sie bearbeiten, um die falschen Einträge zu entfernen, und dann die folgenden Befehle eingeben, um zu einem korrigierten Zustand zurückzukehren:

$ git bisect reset
$ git bisect replay that-file

Vermeiden des Testens eines Commits

Wenn Sie mitten in einer Bisect-Sitzung wissen, dass die vorgeschlagene Revision keine gute zum Testen ist (z.B. sie lässt sich nicht kompilieren und Sie wissen, dass der Fehler nichts mit dem Bug zu tun hat, den Sie verfolgen), können Sie manuell einen nahegelegenen Commit auswählen und diesen stattdessen testen.

Zum Beispiel

$ git bisect good/bad			# previous round was good or bad.
Bisecting: 337 revisions left to test after this (roughly 9 steps)
$ git bisect visualize			# oops, that is uninteresting.
$ git reset --hard HEAD~3		# try 3 revisions before what
					# was suggested

Kompilieren und testen Sie dann die ausgewählte Revision und markieren Sie anschließend die Revision auf übliche Weise als gut oder schlecht.

Bisect überspringen

Anstatt selbst einen nahegelegenen Commit auszuwählen, können Sie Git bitten, dies für Sie zu tun, indem Sie den folgenden Befehl eingeben:

$ git bisect skip                 # Current version cannot be tested

Wenn Sie jedoch einen Commit überspringen, der sich neben dem gesuchten befindet, kann Git nicht genau sagen, welcher dieser Commits der erste fehlerhafte war.

Sie können auch einen Bereich von Commits überspringen, anstatt nur einen einzigen Commit, indem Sie die Bereichsschreibweise verwenden. Zum Beispiel:

$ git bisect skip v2.5..v2.6

Dies teilt dem Bisect-Prozess mit, dass kein Commit nach v2.5, bis einschließlich v2.6, getestet werden sollte.

Beachten Sie, dass Sie, wenn Sie auch den ersten Commit des Bereichs überspringen möchten, den folgenden Befehl eingeben würden:

$ git bisect skip v2.5 v2.5..v2.6

Dies teilt dem Bisect-Prozess mit, dass die Commits zwischen v2.5 und v2.6 (einschließlich) übersprungen werden sollten.

Bisect weiter

Normalerweise berechnet und checked Git nach dem Markieren einer Revision als gut oder schlecht automatisch die nächste zu testende Revision aus. Wenn Sie jedoch explizit den nächsten Bisect-Schritt anfordern müssen, können Sie verwenden:

$ git bisect next

Dies könnten Sie verwenden, um den Bisect-Prozess fortzusetzen, nachdem Sie ihn durch das Auschecken einer anderen Revision unterbrochen haben.

Bisect-Vorgang einschränken durch Übergabe weiterer Parameter an bisect start

Sie können die Anzahl der Versuche weiter reduzieren, wenn Sie wissen, welcher Teil des Baumes an dem Problem beteiligt ist, das Sie verfolgen, indem Sie Pfadangaben angeben, wenn Sie den Befehl bisect start eingeben:

$ git bisect start -- arch/i386 include/asm-i386

Wenn Sie im Voraus mehr als einen guten Commit kennen, können Sie den Bisect-Bereich einschränken, indem Sie alle guten Commits unmittelbar nach dem schlechten Commit angeben, wenn Sie den Befehl bisect start eingeben:

$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
                   # v2.6.20-rc6 is bad
                   # v2.6.20-rc4 and v2.6.20-rc1 are good

Bisect ausführen

Wenn Sie ein Skript haben, das feststellen kann, ob der aktuelle Quellcode gut oder schlecht ist, können Sie die Bisectierung durchführen, indem Sie den Befehl eingeben:

$ git bisect run my_script arguments

Beachten Sie, dass das Skript (my_script im obigen Beispiel) mit dem Code 0 beendet werden sollte, wenn der aktuelle Quellcode gut/alt ist, und mit einem Code zwischen 1 und 127 (einschließlich), außer 125, wenn der aktuelle Quellcode schlecht/neu ist.

Jeder andere Exit-Code bricht den Bisect-Prozess ab. Es sollte beachtet werden, dass ein Programm, das über exit(-1) beendet wird, $? = 255 zurückgibt, da der Wert mit & 0377 abgeschnitten wird.

Der spezielle Exit-Code 125 sollte verwendet werden, wenn der aktuelle Quellcode nicht getestet werden kann. Wenn das Skript mit diesem Code endet, wird die aktuelle Revision übersprungen (siehe git bisect skip oben). 125 wurde als höchster sinnvoller Wert für diesen Zweck gewählt, da 126 und 127 von POSIX-Shells zur Signalgebung spezifischer Fehlerzustände verwendet werden (127 für "command not found", 126 für "command found but not executable" - diese Details sind nicht wichtig, da es sich aus Sicht von bisect run um normale Fehler im Skript handelt).

Sie werden oft feststellen, dass Sie während einer Bisect-Sitzung temporäre Änderungen vornehmen möchten (z.B. s/#define DEBUG 0/#define DEBUG 1/ in einer Header-Datei oder "Revision, die diesen Commit nicht hat, benötigt diesen Patch, um ein anderes Problem zu umgehen, das diese Bisectierung nicht interessiert").

Um eine solche Situation zu bewältigen, kann das Skript nach dem Auffinden der nächsten zu testenden Revision durch die innere git bisect den Patch anwenden, bevor es kompiliert, den eigentlichen Test durchführen und anschließend entscheiden, ob die Revision (möglicherweise mit dem benötigten Patch) den Test bestanden hat und dann den Baum in den ursprünglichen Zustand zurückversetzen. Schließlich sollte das Skript mit dem Status des tatsächlichen Tests beendet werden, damit der Befehl git bisect run die endgültige Entscheidung der Bisect-Sitzung ermitteln kann.

OPTIONEN

--no-checkout

Chelken Sie den neuen Arbeitsbaum bei jeder Iteration des Bisect-Prozesses nicht aus. Aktualisieren Sie stattdessen nur die Referenz namens BISECT_HEAD, damit sie auf den zu testenden Commit zeigt.

Diese Option kann nützlich sein, wenn der Test, den Sie in jedem Schritt durchführen würden, keinen ausgecheckten Baum erfordert.

Wenn das Repository bare ist, wird --no-checkout angenommen.

--first-parent

Verfolgen Sie nur den ersten Eltern-Commit, wenn Sie auf einen Merge-Commit stoßen.

Beim Erkennen von Regressionen, die durch das Zusammenführen eines Branches entstanden sind, wird der Merge-Commit als Einführung des Fehlers identifiziert und seine Vorfahren werden ignoriert.

Diese Option ist besonders nützlich, um Fehlalarme zu vermeiden, wenn ein zusammengeführter Branch fehlerhafte oder nicht kompilierbare Commits enthielt, aber der Merge selbst in Ordnung war.

BEISPIELE

  • Automatische Bisectierung eines fehlerhaften Builds zwischen v1.2 und HEAD

    $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
$ git bisect run make                # "make" builds the app
$ git bisect reset                   # quit the bisect session

  • Automatische Bisectierung eines Testfehlers zwischen origin und HEAD

    $ git bisect start HEAD origin --    # HEAD is bad, origin is good
$ git bisect run make test           # "make test" builds and tests
$ git bisect reset                   # quit the bisect session

  • Automatische Bisectierung eines fehlerhaften Testfalls

    $ cat ~/test.sh
#!/bin/sh
make || exit 125                     # this skips broken builds
~/check_test_case.sh                 # does the test case pass?
$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
$ git bisect run ~/test.sh
$ git bisect reset                   # quit the bisect session

    Hier verwenden wir ein benutzerdefiniertes Skript test.sh. In diesem Skript wird der aktuelle Commit übersprungen, wenn make fehlschlägt. check_test_case.sh sollte mit exit 0 beendet werden, wenn der Testfall erfolgreich ist, und mit exit 1 andernfalls.

    Es ist sicherer, wenn sowohl test.sh als auch check_test_case.sh außerhalb des Repositories liegen, um Interaktionen zwischen den Bisect-, Make- und Testprozessen und den Skripten zu vermeiden.

  • Automatische Bisectierung mit temporären Änderungen (Hotfix)

    $ cat ~/test.sh
#!/bin/sh

# tweak the working tree by merging the hot-fix branch
# and then attempt a build
if	git merge --no-commit --no-ff hot-fix &&
	make
then
	# run project specific test and report its status
	~/check_test_case.sh
	status=$?
else
	# tell the caller this is untestable
	status=125
fi

# undo the tweak to allow clean flipping to the next commit
git reset --hard

# return control
exit $status

    Dies wendet Änderungen aus einem Hotfix-Branch vor jedem Testlauf an, z.B. wenn sich Ihre Build- oder Testumgebung geändert hat, so dass ältere Revisionen möglicherweise einen Fix benötigen, den neuere bereits haben. (Stellen Sie sicher, dass der Hotfix-Branch auf einem Commit basiert, der in allen zu bisectierenden Revisionen enthalten ist, damit der Merge nicht zu viel einbringt, oder verwenden Sie git cherry-pick anstelle von git merge.)

  • Automatische Bisectierung eines fehlerhaften Testfalls

    $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
$ git bisect reset                   # quit the bisect session

    Dies zeigt, dass Sie ohne ein Ausführungsskript auskommen können, wenn Sie den Test auf einer einzigen Zeile schreiben.

  • Einen guten Bereich des Objektgraphen in einem beschädigten Repository lokalisieren

    $ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
$ git bisect run sh -c '
	GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
	git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
	git pack-objects --stdout >/dev/null <tmp.$$
	rc=$?
	rm -f tmp.$$
	test $rc = 0'

$ git bisect reset                   # quit the bisect session

    In diesem Fall wird, wenn git bisect run abgeschlossen ist, bisect/bad auf einen Commit verweisen, der mindestens einen Elternteil hat, dessen erreichbarer Graph im Sinne von git pack objects vollständig durchquerbar ist.

  • Nach einem Fix suchen statt einer Regression im Code

    $ git bisect start
$ git bisect new HEAD    # current commit is marked as new
$ git bisect old HEAD~10 # the tenth commit from now is marked as old

    oder

    $ git bisect start --term-old broken --term-new fixed
$ git bisect fixed
$ git bisect broken HEAD~10

Hilfe erhalten

Verwenden Sie git bisect, um eine kurze Beschreibung der Verwendung zu erhalten, und git bisect help oder git bisect -h, um eine ausführliche Beschreibung der Verwendung zu erhalten.

SIEHE AUCH

Regressionsbekämpfung mit git bisect, git-blame[1].

GIT

Teil der git[1] Suite