| name | bisect-debug |
| description | Find the commit that introduced a regression with an automated git bisect run, then fix it. Use when something that used to work is now broken and the cause isn't obvious — the user says "this worked last week", "which commit broke X", "find the commit that caused this bug", "it regressed", or asks to bisect. Best when you can express the bug as a pass/fail command. |
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
- 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).
- Find a known-good commit. Check out older commits and run the command
until it passes; note that commit as
[good-commit].
- 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.
- Analyze the culprit.
git show [bad-commit] — explain what in it caused
the regression.
- 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).
