bisect-debug

bisect-debug

A regression means there's a specific commit where behavior flipped from good to bad. Bisect finds it in O(log n) steps by binary-searching history with a pass/fail test. The payoff is a precise culprit commit you can read and fix, instead of guessing.

Steps

1. Turn the bug into a pass/fail command.
   • If an existing test already covers it, use that — it should fail at HEAD.
   • Otherwise write a throwaway check outside the repo, e.g. /tmp/bisect-check.sh, that reproduces the bug and exits 0 when the behavior is good and non-zero when it's bad. Keeping it outside the working tree is the trick: it stays put across every checkout, so you never add it to the repo or shuffle a test commit through history. git bisect run executes it from the repo root, so reference repo files by their normal paths (and include a build step if the project needs one).
2. Find a known-good commit. Check out older commits and run the command until it passes; note that commit as [good-commit].
3. Run the bisect automatically:

   git bisect start HEAD [good-commit]
   git bisect run bash /tmp/bisect-check.sh   # or the existing test command
   

   Git checks out midpoints and runs the command at each until it reports [bad-commit] is the first bad commit. Finish with git bisect reset to return to where you started.
4. Analyze the culprit. git show [bad-commit] — explain what in it caused the regression.
5. Fix it properly. Suggest a new bug-fix commit that resolves the bug and adds a proper regression test committed into the repo, so the behavior is protected going forward (the throwaway /tmp script was only scaffolding — discard it). Always a fresh commit, never a rewrite of the culprit — it is almost always already on shared history, which must not be rewritten (others may have built on it). Write the fix commit with an imperative subject line and a body explaining why the bug occurred, not how the diff works.

Why automate with bisect run

Manually marking each midpoint good/bad is slow and error-prone. A scripted command turns the whole search into one step — you only think at the start (pick the check and the good commit) and the end (fix the culprit).