Binary search through history

git bisect performs a binary search across commits to find the one that introduced a bug. Given a known-good and known-bad commit, Git checks out commits in the middle and asks you to test. Each answer halves the search space, so 1024 commits resolve in about 10 steps.

Manual bisect session

git bisect start
git bisect bad                    # current commit is bad
git bisect good v2.4.0            # this older tag was good
# Git checks out the midpoint
# Test the build, then:
git bisect bad                    # or: git bisect good
# Continue until Git names the first bad commit
git bisect reset                  # return to the original branch

Custom terms

Sometimes "good/bad" is the wrong vocabulary — for example, when bisecting a performance regression you might prefer "fast/slow":

git bisect start --term-old fast --term-new slow
git bisect slow
git bisect fast v2.4.0

Skipping untestable commits

If the checked-out commit cannot be tested (build broken, dependency missing), use git bisect skip. Git will pick a nearby commit and adjust.

git bisect skip
git bisect skip <sha1> <sha2>

Visualizing

At any time, see the remaining candidate set:

git bisect visualize
git bisect log > bisect.log       # save for replay
git bisect replay bisect.log

Narrowing the search

If you suspect the regression lies in a particular subdirectory, restrict bisect to commits touching it:

git bisect start -- src/parser/

Common mistakes

Forgetting to mark the initial endpoints — Git cannot bisect without one good and one bad. Marking a commit incorrectly poisons the search; if you suspect this, git bisect log followed by editing and git bisect replay recovers. Building takes time on every step, so pair with --first-parent if your project relies heavily on merges and you only care about merge points.

First-parent bisecting

Since Git 2.29, --first-parent tells bisect to follow only the first parent of each merge, drastically reducing steps in projects that integrate features as merges:

git bisect start --first-parent

Related

For automation, see "Bisect with automated test scripts". When the offending commit is found, "Cherry-picking strategies and pitfalls" helps you fix forward, and "Interactive rebase mastery" helps reshape any quick-fix commits before review.