Binary-Search Debugging with git bisect

"It worked in the January build and it doesn't now" describes about four hundred commits. git bisect finds the guilty one in around nine steps, and with a test script it finds it while you are away from your desk.

Why This Module Matters

This is the module that changes what a QA report can contain.

A normal regression report says what broke and how to reproduce it. A report that also says which commit introduced it skips the entire investigation phase for the developer who picks it up. That is often the difference between a fix today and a fix next sprint.

The method is binary search over history. Mark one commit as known-good and one as known-bad, and Git checks out the midpoint. You test it and say good or bad; Git halves the remaining range and checks out the new midpoint. Four hundred commits become nine tests, because each answer discards half of what is left.

Then it gets better. If the check can be expressed as a command that exits 0 for good and non-zero for bad — a unit test, an API call, a grep on a log file — then git bisect run performs the entire search automatically. No interaction, no judgement calls, just an answer.

What You'll Learn

• Why binary search reduces hundreds of commits to a handful of tests
• A complete manual session: bisect start, bisect bad, bisect good, and bisect reset
• Writing the five-line script that decides good or bad, and what its exit code must be
• Running the whole search unattended with git bisect run
• bisect skip for commits that will not build, and how Git works around them
• What to do when the test is flaky, and how to report the result so the developer trusts it

Pro Tip

Always end a session with git bisect reset. It puts you back on the branch you started from. Bisect leaves you in a detached HEAD on some historical commit, and more than one person has spent ten confused minutes wondering why their working copy looks like last March.