Git Binary search (git bisect)


git bisect allows you to find which commit introduced a bug using a binary search.

Start by bisecting a session by providing two commit references: a good commit before the bug, and a bad commit after the bug. Generally, the bad commit is HEAD.

# start the git bisect session
$ git bisect start

# give a commit where the bug doesn't exist
$ git bisect good 49c747d

# give a commit where the bug exist
$ git bisect bad HEAD

git starts a binary search: It splits the revision in half and switches the repository to the intermediate revision. Inspect the code to determine if the revision is good or bad:

# tell git the revision is good,
# which means it doesn't contain the bug
$ git bisect good

# if the revision contains the bug,
# then tell git it's bad
$ git bisect bad

git will continue to run the binary search on each remaining subset of bad revisions depending on your instructions. git will present a single revision that, unless your flags were incorrect, will represent exactly the revision where the bug was introduced.

Afterwards remember to run git bisect reset to end the bisect session and return to HEAD.

$ git bisect reset

If you have a script that can check for the bug, you can automate the process with:

$ git bisect run [script] [arguments]

Where [script] is the path to your script and [arguments] is any arguments that should be passed to your script.

Running this command will automatically run through the binary search, executing git bisect good or git bisect bad at each step depending on the exit code of your script. Exiting with 0 indicates good, while exiting with 1-124, 126, or 127 indicates bad. 125 indicates that the script cannot test that revision (which will trigger a git bisect skip).