Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Inspecting History

git bisect command

Reference for git bisect: start, good, bad, skip, run, log, replay, terms and reset. Find the first bad commit with a binary search over history.

git bisect finds the first commit that changed some behavior by binary search. You name one commit that is known to be good and one that is bad. Git checks out a commit halfway between them, you (or a script) judge it, and each verdict removes half of the remaining candidates. A range of 1,000 commits needs about ten checks.

The search assumes the property flips once: good up to some commit, bad from there on. While a bisect session is active, HEAD is detached and moves; git bisect reset brings you back.

Terminal
git bisect start [--term-old=<word> --term-new=<word>] [<bad> [<good>...]]
git bisect good|bad [<rev>...]
git bisect skip [<rev>...]
git bisect run <command> [<args>...]
git bisect log | replay <file> | visualize | reset [<commit>]

Try it

Bash Automatic search with bisect run

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Manual verdicts and the session log

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

git bisect start <bad> <good> is shorthand for starting and then marking both ends. With no arguments, start only opens the session and you mark commits yourself.

Subcommand Description
start [<bad> [<good>...]] Begin a session. Several good commits are allowed. --no-checkout only updates BISECT_HEAD instead of the working tree; --first-parent follows only first parents.
good / bad Mark a commit (default HEAD). With --term-old/--term-new these become your own words.
skip The commit cannot be tested (does not build); Git picks a neighbor.
run <cmd> Run a command on each step and interpret its exit status.
log Print the verdicts recorded so far.
replay <file> Replay a saved log.
visualize / view Show the remaining candidates in gitk or, without a display, git log.
reset [<commit>] End the session and check out the original branch (or <commit>).

Exit status for run: 0 means good, 1 to 127 except 125 means bad, 125 means skip, and 128 or above stops the search.

Usage notes

  • If you mark commits in the wrong order, Git refuses: the "good" commit must be an ancestor of the "bad" one, or you get a message about the merge base.
  • The result line reads " is the first bad commit" followed by the commit message. Everything before it is good by your verdicts.
  • Use skip sparingly. Too many skipped commits lead to "only skipped commits left" and a list of possible culprits instead of one.
  • Do not use a flaky test as the check. One wrong verdict sends the search to the wrong half.
  • Your script may be untracked; the working tree is switched between commits, so keep the script outside the repository, as the first example does, or copy it first.
  • git bisect log > session.txt followed later by git bisect replay session.txt lets you resume or share a search.
  • Terms: old/new are the generic names that work for any kind of change, such as "which commit fixed the bug".