Regression Bisecting

Purpose

When a feature used to work but is now broken, do not guess what broke it. Use binary search through git history to find the exact commit, then read the root cause out of that commit's diff.

When to Use

• A regression appeared and the offending commit is unknown
• A bug is reported "since some release" with a wide commit range
• A deterministic repro command exists or can be built

Inputs

• A test command that returns exit code 0 if good and non-zero if bad (e.g., npm run test:repro or node repro.js)
• A known-good ref and a known-bad ref (typically HEAD)

Workflow

1. Define the test. You must have a single command that returns exit code 0 if good, and non-zero if bad. If none exists, build one first (see minimal-reproduction).

2. Find a known good state. Ask the user or search git history for a commit where you are certain the feature worked (a release tag is a good candidate). Verify it by running the test on it.

3. Find the known bad state. Typically HEAD.

4. Bisect automatically:

   git bisect start <bad> <good>
   git bisect run npm run test:repro    # or: git bisect run node repro.js
   git bisect log                       # record of the search
   git bisect reset                     # always return to the original ref
   

   git bisect run checks out each midpoint and runs the command until it isolates the first bad commit. Use git bisect skip for midpoints that fail to build. For workflows where bisect run is not viable, manually check out the midpoint commit, run the test, and narrow the window with git bisect good / git bisect bad.

5. Analyze the offending commit. Once the exact commit is found, use git show <commit> to analyze the diff. The root cause is contained entirely within that diff.

Output

• The first bad commit (hash + subject) and the bisect log
• A root-cause explanation grounded in that commit's diff

Verification

• Test command verified deterministic (0/non-zero) before bisecting started
• Known-good ref actually tested as good, not assumed
• git bisect reset run afterward — repo back on the original ref
• Root cause explained from the offending diff, not just the commit named

Failure Modes

• Flaky test command — a non-deterministic repro sends the bisect to a random commit; stabilize it first (see flaky-test-investigation).
• Unverified "good" ref — if the good commit was never tested, the entire search window may be wrong.
• Forgetting git bisect reset — leaves the repo detached on a bisect commit.
• Build-broken midpoints — guess instead of git bisect skip and the result is corrupted.