Buglyst
Start Debugging
Tools11 min read

Efficient Debugging with git bisect: Going Beyond Binary Search

This article explains how to incorporate git bisect into your debugging workflow, focusing on practical execution, automation, and common edge cases.

gitdebuggingversion controltooling

When you notice a bug that didn’t exist a week ago but can’t pinpoint the cause, git bisect can save hours of manual detective work. Most teams learn about binary search in git, but I still see underuse of bisect or, worse, incorrect usage leading to wasted cycles.

Let’s walk through a robust bisect workflow, highlight easy mistakes, and show a real-world example where automation cut our debugging time from hours to minutes.

Setting up a Reliable git bisect Session

  • arrow_rightIdentify two commits: a known-good and a known-bad one.
  • arrow_rightMake sure your repo is clean—no uncommitted changes.
  • arrow_rightIf your bug requires a particular environment or configuration, script that setup.

Automating the Tedious Parts

I rarely run a bisect session entirely by hand anymore. For non-trivial bugs, manual testing at every commit is error-prone, and it’s easy to forget edge conditions.

Here’s how I structure a test script for bisect automation:

Example of a bisect test script that builds and tests for a regression.
#!/bin/bash
set -e
# Run your build
make
# Run your test (adjust as needed)
./run_regression_test.sh
# If the test fails, exit 1
grep -q 'EXPECTED_OUTPUT' output.log || exit 1
# Otherwise, exit 0
exit 0
lightbulb

Always make your test script idempotent—no interactive prompts or external dependencies that might change between runs.

Real-World Example: When a Merge Masked a Regression

Production Regression Pinpointed Under Pressure

  1. 09:00PagerDuty triggers on customer complaint: API v2 returns 500s for a specific endpoint.
  2. 09:15Bug confirmed locally, but root cause unclear. Last week’s deploy was fine.
  3. 09:18git bisect start v2.0.0 (good) v2.1.1 (bad)
  4. 09:20Automated bisect script reveals test passes until a merge commit.
  5. 09:27Found culprit: Feature branch introduced a subtle change to API serialization, merged with no test coverage.
  6. 09:30Hotfix applied and deployed.

Lesson

Automating bisect not only found the breaking change, but also surfaced a coverage gap—prompting the team to add regression tests for all merged features.

If your team is still clicking through GUIs or running one-off patch queries, you're wasting time not letting git bisect work for you.

Handling Ambiguous or Unbuildable Commits

  1. 1If a commit fails to build, mark it with `git bisect skip`.
  2. 2When bisect stops on a merge, check both parent branches for the actual culprit.
  3. 3If tests are flaky, rerun with a fresh environment or seed.
15x

Faster bug isolation in a monorepo after scripting git bisect, measured over 8 recent incidents

Frequently asked questions

How do I automate git bisect with a test script?

You can use `git bisect run ./test-script.sh`, where your script exits 0 for good and nonzero for bad. This automates the process end-to-end.

What happens if a commit doesn’t build during bisect?

Mark that commit as 'skip' with `git bisect skip`. Bisect will avoid skipped commits and continue searching for the culprit.

Does bisect always return a single culprit commit?

Not necessarily—if the bug was introduced over multiple commits or merges, bisect will narrow it as much as possible but might stop at a merge.

How do I clean up after a bisect session?

Run `git bisect reset` to return to your original HEAD and clean up the bisect state. Don’t forget this step before starting new work.