Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git bisect: Binary Search, Automated Scripts, and Bug Hunting

Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.

~5 min readGit
#Git#Bisect#Debugging#CLI
3D illustration of a row of commit cubes with a halving search path narrowing to one red faulty cube

Quick Summary

git bisect is a binary search over commits: you mark one commit bad and one good, and Git checks out the midpoint, asks you to test it, and halves the range each time. A regression across 2,000 commits resolves in about eleven steps.

The useful form is git bisect run <script>, which automates the loop: Git checks out each candidate on a clean tree, runs your command, and reads the exit code — 0 means good, 125 means skip, any other non-zero value means bad. Ten minutes of writing a test script replaces an afternoon of manual checkouts.

It works because of one assumption: monotonicity. Everything between the good and bad endpoints is either good or bad, so once a commit is bad every descendant is bad. Bugs that appear and disappear, or that depend on the environment rather than the commit, break that assumption and produce a confidently wrong answer.

Basic Syntax and Core Signatures

bash
# Manual session git bisect start git bisect bad # current HEAD is broken git bisect good v1.4.0 # a known working tag or sha git bisect good # after testing: still fine git bisect bad # after testing: broken git bisect skip # this commit cannot be built git bisect reset # end, return to the branch you started on # One-shot form: bad and good on the command line git bisect start HEAD v1.4.0 # Automated git bisect run npm test git bisect run ./scripts/check-regression.sh git bisect run sh -c 'npm ci --silent && npm test -- --runInBand' # Other words than good/bad (e.g. a performance regression) git bisect start --term-old=fast --term-new=slow git bisect fast v1.4.0 git bisect slow git bisect terms # print the active terms # Forensics git bisect log > bisect.log # exact session git bisect replay bisect.log # replay elsewhere git bisect visualize # gitk / log of the remaining range git bisect reset HEAD~2 # end and land somewhere specific

The exit-code contract of git bisect run decides everything. A test runner that returns 0 for "tests passed" and 1 for "tests failed" maps directly; a runner that also returns non-zero for "no tests found" or "config missing" will mark commits bad for the wrong reason, and the bisect will land on a build error rather than the regression.

Key Comparison Table

ApproachSteps for 1,000 commitsNeeds a clean treeHandles build failuresRepeatable
Manual good/bad~10 checksYesSkip by handNo, unless logged
git bisect run~10 automated checksYes125 from the scriptYes, replayable
Linear git log readingUp to 1,000NoNot applicableYes
git blame on the changed line1NoNot applicableYes, but the line must be the bug
git log -S (pickaxe)1 searchNoNot applicableFinds the introducing diff only if it is textual
Exit code from the run scriptBisect interpretationTypical cause
0goodTest suite passed
1 to 124, 126, 127badAssertion failed, build error
125skipMissing dependency, unbuildable commit
Killed by a signalabortSegfault, OOM, hang and kill
git bisect reset neededsession endsDo not leave the tree on a bisect checkout

Practical Edge Cases and Deep Dives

1. A run script that is actually deterministic

bash
#!/usr/bin/env bash set -u npm ci --silent --no-audit --no-fund >/dev/null 2>&1 || exit 125 # cannot build: skip out=$(npx jest --runInBand --silent test/regression.test.js 2>&1) || true if grep -q "Cannot find module" <<<"$out"; then exit 125; fi # environment, not a regression if ! grep -q "1 failed" <<<"$out" && ! grep -q "0 failed" <<<"$out"; then exit 125; fi grep -q "1 failed" <<<"$out" && exit 1 exit 0

Two rules make this reliable. Distinguish "the feature is broken" from "the commit does not compile" — a compile error must be 125, or every old commit that predates a new dependency gets marked bad and the result is garbage. And make the assertion specific to the regression, not "the suite is green": an old commit usually fails unrelated tests, which turns the whole bisect into noise.

2. Nondeterministic failures and repeated tests

bash
git bisect run bash -c 'for i in 1 2 3; do ./flaky-test.sh || exit 1; done'

A flaky test that fails one run in five gives a random midpoint answer, and one wrong bad is enough to discard the real commit. Run the test several times and fail only if all runs fail; if the failure is timing-dependent, pin the CPU (taskset -c 0) and the seed. If it cannot be made deterministic, bisect a proxy instead — a log line, an assertion on a counter, a unit test that reproduces the cause rather than the symptom.

3. Skips, and when the answer becomes inconclusive

bash
git bisect skip # this one does not build git bisect skip a1b2c3d..f6e5d4c # skip a whole range

Skipping is legitimate for commits that cannot be built (a broken intermediate state, a missing tag), and Git will test commits adjacent to the skipped ones to narrow the range anyway. Skip too much and the session ends with There are only 'skip'ped commits left to test. The first bad commit could be any of: … — an honest inconclusive result. At that point a git bisect log plus git log --oneline good..bad on the short list usually finds it by reading.

4. Why the working tree must be clean

git bisect checks out a different commit on every step, so uncommitted work is destroyed or blocks the checkout with error: Your local changes to the following files would be overwritten by checkout. Commit to a scratch branch or stash first:

bash
git stash push -u -m "before bisect" git bisect start HEAD v1.4.0 git bisect run npm test git bisect reset git stash pop

Build output directories make this worse: node_modules and dist change on every step, so the tree is technically dirty constantly. Add them to .gitignore rather than committing them, and give the run script a fixed install step so each candidate is built from its own lockfile.

5. Bisecting merges and long-lived branches

By default Git searches the whole ancestry, including commits that only exist on merged side branches — which is what you want for "when did this appear", but not for "which merge into main broke it".

bash
git bisect start --first-parent HEAD v1.4.0 # newer Git git bisect run npm test

--first-parent restricts the search to the mainline, so the reported commit is a merge rather than a random commit on a topic branch, and the answer is directly actionable ("revert that merge"). Without it, expect the result to be a commit from a side branch that was merged weeks later; that is correct, but it needs the merge context to act on.

6. Logging, replaying, and keeping the evidence

bash
git bisect log > /tmp/bisect-issue-812.log git bisect reset # later, on another machine with the same history: git bisect replay /tmp/bisect-issue-812.log

The log is the only artifact a bisect produces, and it is what makes the result reviewable: it records each step's commit, verdict, and the commands used. Attach it to the issue. git bisect replay re-runs the same decisions and lands on the same commit, which is exactly what you need when a colleague doubts the conclusion or when a CI machine rather than a laptop should do the work.

Common Git Operation Mistakes

SymptomCauseFix
You need to start by "git bisect start"Ran bad/good outside a sessiongit bisect start HEAD <good> first
Every midpoint marked badBuild error treated as a regressionReturn 125 from the script for unbuildable commits
Result points at an unrelated commitTest asserts more than the regressionNarrow the test to the behaviour that changed
There are only 'skip'ped commits leftToo many skipsgit bisect log, then inspect good..bad by hand
error: Your local changes would be overwrittenDirty treeCommit or stash, then restart
Bisect ends on a side-branch commitWhole-ancestry searchgit bisect start --first-parent
Tree left on an old commitSession abandonedgit bisect reset returns to the starting ref
Same bisect gives different answersFlaky test or unstable environmentRepeat the run, pin CPU and seed
Cannot reproduce after resetRegression depends on the checkout state, not the commitCompare with the exact commit: git switch --detach <sha>

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.