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.

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
# 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 specificThe 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
| Approach | Steps for 1,000 commits | Needs a clean tree | Handles build failures | Repeatable |
|---|---|---|---|---|
Manual good/bad | ~10 checks | Yes | Skip by hand | No, unless logged |
git bisect run | ~10 automated checks | Yes | 125 from the script | Yes, replayable |
Linear git log reading | Up to 1,000 | No | Not applicable | Yes |
git blame on the changed line | 1 | No | Not applicable | Yes, but the line must be the bug |
git log -S (pickaxe) | 1 search | No | Not applicable | Finds the introducing diff only if it is textual |
| Exit code from the run script | Bisect interpretation | Typical cause |
|---|---|---|
0 | good | Test suite passed |
1 to 124, 126, 127 | bad | Assertion failed, build error |
125 | skip | Missing dependency, unbuildable commit |
| Killed by a signal | abort | Segfault, OOM, hang and kill |
git bisect reset needed | session ends | Do not leave the tree on a bisect checkout |
Practical Edge Cases and Deep Dives
1. A run script that is actually deterministic
#!/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 0Two 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
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
git bisect skip # this one does not build
git bisect skip a1b2c3d..f6e5d4c # skip a whole rangeSkipping 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:
git stash push -u -m "before bisect"
git bisect start HEAD v1.4.0
git bisect run npm test
git bisect reset
git stash popBuild 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".
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
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.logThe 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
| Symptom | Cause | Fix |
|---|---|---|
You need to start by "git bisect start" | Ran bad/good outside a session | git bisect start HEAD <good> first |
| Every midpoint marked bad | Build error treated as a regression | Return 125 from the script for unbuildable commits |
| Result points at an unrelated commit | Test asserts more than the regression | Narrow the test to the behaviour that changed |
There are only 'skip'ped commits left | Too many skips | git bisect log, then inspect good..bad by hand |
error: Your local changes would be overwritten | Dirty tree | Commit or stash, then restart |
| Bisect ends on a side-branch commit | Whole-ancestry search | git bisect start --first-parent |
| Tree left on an old commit | Session abandoned | git bisect reset returns to the starting ref |
| Same bisect gives different answers | Flaky test or unstable environment | Repeat the run, pin CPU and seed |
| Cannot reproduce after reset | Regression depends on the checkout state, not the commit | Compare with the exact commit: git switch --detach <sha> |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
Git worktree: Multiple Checked-Out Branches in One Repository
A linked worktree has its own HEAD, index, and files while sharing objects and refs. One branch per worktree, prune for deleted directories, and submodules that stay empty.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.