How to Use git bisect to Find a Bad Commit

What git bisect does

git bisect performs a binary search through your commit history. You mark one commit as good (build passes) and another as bad (build fails). Git checks out the midpoint commit; you test and mark it good or bad. Repeat until git narrows it down to the single first-bad commit.

For 50 commits that's at most log2(50) = 6 test runs - regardless of which commit is the culprit.

Manual bisect

cd /workspace/repo

git bisect start
git bisect bad HEAD          # current commit is broken
git bisect good v1.0.0       # this tag built clean

# git checks out the midpoint - test it, then mark it:
./build.sh && git bisect good || git bisect bad

# repeat until git prints:
# "<sha> is the first bad commit"

git bisect reset             # return to HEAD when done

After git bisect reset you're back on your original branch, no detached HEAD left behind.

Automated bisect with git bisect run

If you have a script that exits 0 for a good commit and non-zero for a bad one, hand it to git bisect run and let git drive the whole search:

git bisect start
git bisect bad HEAD
git bisect good v1.0.0

git bisect run ./build.sh
# git runs build.sh at each midpoint automatically
# output ends with: "<sha> is the first bad commit"

git bisect reset

Git reads the script's exit code at each step and picks the next midpoint itself. The search is fully unattended.

Capturing the bad commit SHA

Once bisect prints the result, grab the SHA and record it:

# After git bisect run finishes, the bad ref is stored:
git rev-parse refs/bisect/bad

# Or parse it from bisect output directly:
git bisect run ./build.sh | grep "is the first bad commit" | awk '{print $1}'

After git bisect reset, inspect that commit to understand what changed:

git show <sha>

Choosing a good bisect script

• Use the fastest reproducer - not the full test suite. If a single unit test or make build catches the regression, use that. Faster script = faster bisect.
• The script must be deterministic - a flaky test causes git to mark good/bad commits wrong, leading to a false result.
• Exit 0 = good, any non-zero = bad. If your test runner uses other conventions, wrap it in a small shell script that normalizes the exit code.