bisect: Binary Search for Bugs

bisect — binary search through history

You have a bug. You know it works in version 1.4 and is broken in 2.0. Somewhere in the 200 commits between them lives the regression. Manual search would be miserable. git bisect is the named recipe for binary-searching that range automatically: Git checks out commits halfway, you tell it good or bad, Git narrows by half, you repeat. log₂(200) is about 7 — seven test runs find the exact culprit commit.

The dance is simple. git bisect start, git bisect bad at the broken commit (or git bisect bad HEAD for now), git bisect good v1.4 at the known-good commit. Git checks out the midpoint. You build, test, decide, then git bisect good or git bisect bad. Git checks out the next midpoint. Repeat until Git announces the first bad commit. git bisect reset returns you to your original branch.

The automation upgrade: git bisect run <script>. Provide a script that exits 0 for "good" and non-zero for "bad" — typically your test command, or a one-line check like grep -q "expected output" log.txt. Git runs the script at each midpoint automatically, no human in the loop. Twenty commits between v1.4 and HEAD takes seconds. Hundreds of commits with a slow build take an hour, but you do nothing during it.

Two practical refinements. Skip uninteresting commits with git bisect skip when a particular checkpoint cannot be tested (broken build, missing dep, etc.) — Git tries another candidate. Save the bisect log with git bisect log > my-bisect.log and replay later with git bisect replay my-bisect.log if you need to abandon and resume. The bisect run is a tiny side-state that does not interfere with branches.

Code

Manual bisect — typical session·bash

# Start the search; tell Git the bad and good ends:
git bisect start
git bisect bad HEAD
git bisect good v1.4.0

# Git checks out a midpoint commit. Test it:
npm test
# Or run the actual symptom-checker:
./scripts/check-bug.sh

# Decide and tell Git:
git bisect good       # or: git bisect bad

# Repeat until Git announces:
# 'abc1234 is the first bad commit'

# Return to where you started:
git bisect reset

Automated bisect run·bash

# Provide an exit-code script. Examples:
git bisect start HEAD v1.4.0
git bisect run npm test           # run full test suite each step

# Or a focused check:
git bisect run bash -c 'npm run build && grep -q OK dist/output.txt'

# Or a single-test invocation:
git bisect run npm test -- search-results.test.js

# Capture and replay:
git bisect log > bisect-2026-05-03.log
# ... days later, want to revisit:
git bisect replay bisect-2026-05-03.log

Exercise

Construct a fake regression in a scratch repo: make a commit that introduces a deliberately wrong constant, then six more commits doing unrelated things. Run git bisect manually, decide good/bad at each step, and confirm Git points at the introducing commit. Then write a one-line script that detects the bad constant and run git bisect run against it. Note the difference in time and effort.

bisect: Binary Search for Bugs

bisect — binary search through history

Code

External links

Exercise

Progress

Comments 0