A bug exists on main but did not exist three weeks ago. Somewhere in the last two hundred commits, a change introduced it. Reading every diff is slow. Git bisect does a binary search instead: about log2(200), or eight tests, to find the first bad commit.

The manual loop

git bisect start
git bisect bad                 # current commit is broken
git bisect good v1.4.0         # this tag was known good

Git checks out a commit in the middle and prints how many steps remain. Run your test, then report:

git bisect good                # this commit works
git bisect bad                 # this commit is broken
git bisect skip                # this commit cannot be tested

Repeat until Git prints the first bad commit. Then:

git bisect reset

This returns you to the branch you started from.

The automated loop

Bisect can run a command and interpret its exit code:

git bisect start HEAD v1.4.0
git bisect run npm test -- --grep "checkout total"

Exit codes:

  • 0 — good.
  • 1–124, 126, 127 — bad.
  • 125 — skip this commit.
  • 128 or above — abort the bisect.

A script is usually more reliable than a test command because it can handle setup:

#!/usr/bin/env bash
set -e
npm ci --silent
npm run build --silent
npm test -- --grep "checkout total"
git bisect run ./scripts/check-regression.sh

The script runs once per candidate commit. Keep it fast; a bisect over 500 commits with a ten-minute build takes hours. Caching dependencies helps, but be careful that the cache does not mask the bug.

Choosing good and bad endpoints

The search only works if the endpoints are honest:

  • good must be a commit where the test definitely passes.
  • bad must be a commit where it definitely fails.
  • If the bug is intermittent, bisect may misclassify a commit. Fix the flakiness or use skip for commits you cannot judge.

A tag or a known release is a better good endpoint than “some commit from last month that probably worked”.

Merge commits

Bisect walks the commit graph. Merge commits can complicate the result because a merge brings in changes from a side branch. The first bad commit may be a merge, or the actual culprit may be on a branch that was merged. git bisect can usually identify the merge; inspecting its parents tells you which side introduced the change.

If the history is very tangled, git log --first-parent narrows the search to the mainline, at the cost of skipping side-branch commits.

After you find it

git show <bad-sha>
git log -1 --stat <bad-sha>

Read the diff, then decide:

  • Revert the commit if it is isolated.
  • Fix forward if the change is needed.
  • Add a regression test that fails on the bad commit and passes after the fix.

Record the result in the issue. “It was commit abc123” is useful; “it was the cache-key change in abc123” is more useful.

Recovering from a botched bisect

If you get lost or the working tree is dirty:

git bisect reset
git status

reset returns to the original branch. If you accidentally started from a dirty tree, stash first; bisect checks out commits and may refuse or overwrite local changes.

When not to bisect

  • The bug depends on external state (a database migration, a deploy, a feature flag). Bisect only sees code.
  • The test is flaky. A flaky test produces a random answer with high confidence.
  • The history is squashed into one commit. There is nothing to search.
  • The build is too slow to run hundreds of times. Optimize the test first.

Bisect is one of the highest-leverage Git commands: a few minutes of setup replaces hours of reading diffs. The bisect recipe includes the exit-code table and a script template.