Git Bisect: Finding the Commit That Broke Your Build

The Problem

You know something broke between last week's release and today. There are 200 commits in between. Manually testing each one would take hours.

git bisect performs a binary search: it splits the commit range in half, checks out the midpoint, asks you if it is good or bad, then splits again. You find the culprit in log₂(200) ≈ 8 steps.

---

Manual Bisect

# Start bisect
git bisect start

# Mark the current (broken) commit as bad
git bisect bad

# Mark a known-good commit (last week's release tag)
git bisect good v2.4.0

# Git checks out the midpoint commit
# Run your test, then tell git the result:
git bisect good    # this commit is fine
# or
git bisect bad     # this commit has the bug

# Git keeps halving until it finds the first bad commit
# When done, git prints:
# abc1234 is the first bad commit

# Always end the bisect session when finished
git bisect reset    # returns to your original branch/commit

---

Automated Bisect with a Test Script

Write a script that exits 0 for good and non-zero for bad:

#!/usr/bin/env bash
# test-regression.sh
npm run build --silent
result=$(npm test -- --testNamePattern="auth login" --silent 2>&1)
if echo "$result" | grep -q "PASS"; then exit 0; else exit 1; fi

git bisect start
git bisect bad HEAD
git bisect good v2.4.0
git bisect run ./test-regression.sh

Git runs the script at each step automatically. You walk away and come back to the first bad commit.

---

Tips for Effective Bisect

Use specific test commands. The more targeted the test, the faster and more reliable. Running your entire test suite at each step is slow; running one unit test is fast.

Handle flaky tests. If your test is flaky, bisect will mismark commits. Use git bisect skip to skip a commit if the test result is unreliable:

git bisect skip    # this commit's result is inconclusive

Binary search requires monotonicity. Bisect assumes once something breaks it stays broken toward the present. If the bug appears, disappears, and reappears, bisect will not find the right commit.

---

Reading the Bisect Log

git bisect log    # see the history of your good/bad markings

If you marked something wrong, you can replay the session from the log with corrections.

---

After Finding the Bad Commit

git show abc1234                   # see what changed
git log --all --oneline abc1234    # see context
git bisect reset                   # go back to where you were

Then fix the code or revert the commit:

git revert abc1234    # creates a new commit undoing the change

Practice in the ShellGenius Git Labs — the git-undo-changes and git-staging challenges cover real undo and recovery scenarios.