The Problem: Finding a Needle in a Haystack
Imagine your test suite passes on the commit from two weeks ago but fails on today's commit. Somewhere in the 200 commits between them, someone introduced a regression. Reading through 200 commits manually is impractical.
git bisect uses binary search to find the culprit commit. Instead of checking all 200 commits, it checks log₂(200) ≈ 8 commits. You tell Git which commit is "good" (bug absent) and which is "bad" (bug present), and Git checks out the midpoint for you to test.
Manual vs. Automated Bisect
In manual mode, you run git bisect good or git bisect bad after testing each commit Git checks out. This works, but it requires you to stay at your keyboard.
git bisect run <command> automates the entire process. Git runs your command at each candidate commit and interprets the exit code:
- Exit code 0 → Git marks the commit Good (no bug)
- Exit code 1–127 → Git marks the commit Bad (bug present)
- Exit code 125 → Git marks the commit Skip (untestable — e.g., it doesn't compile)
Your test script can be anything: a shell one-liner, a unit test runner, a grep command, a Python script. As long as it exits with 0 for "working" and non-zero for "broken," Git handles the rest.
The Exit Code Contract
The exit code contract is strict. If your test script crashes with exit code 128 or higher (which some shells use for signals), Git will abort the bisect session entirely rather than marking the commit bad. Always test your script manually before running git bisect run to confirm it exits cleanly with 0 or 1.