Git Bisect as a Debugging Tool

Find the commit that broke production. The bisect workflow, with examples.

Setup

Setup is three commands. Mark the current broken commit as bad and a known-working commit as good; git bisect binary-searches the range. Recording the bounds explicitly makes later postmortem reconstruction straightforward.

• git bisect start. Enters bisect mode. The working tree is now under bisect control.
• git bisect bad HEAD. Marks the current broken commit. Anchors the upper bound of the search.
• git bisect good <sha>. Marks the known-working commit. Anchors the lower bound.
• Documented bounds per bisect. Recorded good and bad SHAs. Supports later reconstruction in the postmortem.

Test each

Testing each midpoint can be manual (you mark good or bad after each checkout) or automated (a script returns the verdict). Automated bisect wins when the test is scriptable; the convergence happens at machine speed.

• git bisect run script.sh. Automation entry. Bisect drives commit checkout; script returns the verdict.
• Script returns 0 if good, 1 if bad. The contract. Bisect converges to the breaking commit.
• Deterministic test per bisect. No-flake-test rule. Flaky tests give wrong bisect answers and waste hours.
• Timeout per commit. Bounded test runtime. Total bisect time stays predictable.

Finish

Finishing cleans up the working tree and surfaces the breaking commit. The commit’s diff is usually the bug; the regression test goes into the suite so the bug cannot return.

• git bisect reset. Cleanup command. Returns the working tree to the original state.
• Bad commit identified. Named SHA. The diff is the bug.
• Postmortem note. Per-incident the bisect outcome documented. Supports later “how we found it” reconstruction.
• Regression test per bug. Captured test case. Catches recurrence at PR time.