Git Bisect

Overview

git bisect performs a binary search across your history to find the exact commit that introduced a regression. You mark one commit as "bad" and an earlier one as "good", and Git repeatedly checks out the midpoint for you to test. With git bisect run you can fully automate the search using a test script, reducing hundreds of commits to a handful of checks.

Syntax / Usage

Begin a session, provide the known good and bad boundaries, then classify each checkout.

# Start bisecting
git bisect start
git bisect bad                 # current commit is broken
git bisect good v1.2.0         # this tag was known-good

# Git checks out the midpoint; test, then mark it:
git bisect good                # this commit works
git bisect bad                 # this commit is broken

# When finished, return to your original state
git bisect reset

Examples

Manually narrow down a failing test across many commits:

git bisect start HEAD v2.0.0
# Git checks out a midpoint commit
npm test
git bisect bad     # tests still fail here
# repeat until Git reports the first bad commit
git bisect reset

Automate the entire search with a script whose exit code signals good (0) or bad (non-zero):

git bisect start HEAD v2.0.0
git bisect run npm test
# Git prints "<sha> is the first bad commit" automatically
git bisect reset

Skip a commit that cannot be tested (e.g. it fails to build):

git bisect skip

Common Mistakes

• Reversing the boundaries—marking the broken commit "good" or vice versa
• Testing inconsistently, so the same commit gets classified differently
• Forgetting git bisect reset, leaving the repo on a detached midpoint
• Using a run script that exits non-zero for reasons unrelated to the bug
• Not using git bisect skip for untestable commits, corrupting the result

See Also

commit git-reflog-recovery branch