git bisect

Tell it good and bad. It tells you the guilty commit.

🎯 What & why

Binary-search through commit history to find the commit that introduced a bug. You mark a known-good and a known-bad commit; Git checks out the midpoint and asks you to test it. Repeat until it tells you the guilty commit.

🧠 Mental model

Bisect maintains a search range in the DAG. Each step halves it: if the midpoint tests good, the bug is in the newer half; if bad, the older half. Logarithmic — finds the bug in log2(N) steps.

🛠️ Synopsis

git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
                [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
git bisect (good|bad) [<rev>...]
git bisect skip [(<rev>|<range>)...]
git bisect reset [<commit>]
git bisect (visualize|view)
git bisect replay <logfile>
git bisect log
git bisect run <cmd>...
git bisect help

🎚️ Switches & options

Flag	What it does
`start`	Begin a bisect session.
`good <rev>`	Mark `<rev>` as known-good.
`bad <rev>`	Mark `<rev>` as known-bad.
`skip`	Skip the current commit (untestable).
`reset`	End the session, restore HEAD.
`run <cmd>`	Automate: Git runs `<cmd>` at each step. Exit 0 = good, non-zero = bad.

📦 Subcommands

start [<bad> [<good>...]] — Begin a bisect session.

$ git bisect start HEAD v1.0

good [<rev>] — Mark current (or <rev>) as known-good.

$ git bisect good

bad [<rev>] — Mark current (or <rev>) as known-bad.

$ git bisect bad

skip [<revs>] — Skip an untestable commit.

$ git bisect skip

run <cmd>... — Automate: exit 0 = good, non-zero = bad.

$ git bisect run make test

reset [<commit>] — End the session and restore HEAD.

$ git bisect reset

log — Print the bisect transcript.

$ git bisect log

replay <logfile> — Re-run a recorded bisect session.

$ git bisect replay /tmp/bisect.log

💡 Use cases

Hunting regressions in long histories.
Pinpointing which dependency bump broke the build.
Auditing when a security issue was introduced.

🧪 Examples

Manual bisect.

$ git bisect start
$ git bisect bad        # current is bad
$ git bisect good v1.0  # v1.0 was good
# ... test, mark good/bad each step ...
$ git bisect reset

Automated bisect with a test.

$ git bisect start HEAD v1.0
$ git bisect run make test

🎓 Recommendations

Automate with git bisect run whenever you can write a deterministic test that returns non-zero on failure.
If the test is flaky, git bisect skip rather than guessing.

🪤 Common pitfalls

Forgetting to git bisect reset leaves you on a strange detached HEAD.
Testing an untestable commit (build broken for other reasons) corrupts the search — skip it.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.