There is a particular kind of dread that comes with opening a bug report, running git log, and seeing 300 commits between "this worked" and "this doesn't." Most people start at HEAD and work backwards one commit at a time. There is a much better way.
git bisect does a binary search through your commit history. You tell it one commit where things were good and one where they are bad. It checks out the midpoint. You test and say good or bad. It halves the search space and repeats. It finds the culprit in at most eight steps regardless of whether you have 50 commits or 5,000.
How it works
You mark a known-good commit and a known-bad commit. Git checks out the midpoint. You test and tell Git whether that commit is good or bad. Git halves the search space and repeats. After a handful of rounds, it pinpoints the first bad commit.
Start a bisect session
git bisect start
git bisect bad # current commit is bad
git bisect good v1.4.0 # this tag (or hash) was working
Git checks out a commit halfway between the two. Test the code — does the bug exist?
git bisect good # bug is NOT present in this commit
git bisect bad # bug IS present in this commit
Repeat until Git announces the culprit:
b2c3d4e5 is the first bad commit
commit b2c3d4e5
Author: ...
Date: ...
feat: add pagination to user list
End the session
git bisect reset
This returns you to the branch you started from. Always run this when you are done — leaving a bisect session open causes confusing behaviour with other Git commands.
Automate with a test script
If you have a script that exits 0 when the code is good and non-zero when it is bad, you can automate the entire process:
git bisect start
git bisect bad HEAD
git bisect good v1.4.0
git bisect run ./scripts/test-feature.sh
Git runs the script at each step and marks the result automatically. The session finishes without any input from you, often in under a minute.
The script needs to be reliable — flaky tests will mislead the binary search. It also needs to be compatible with the range of commits being tested, which is sometimes a problem if the test itself depends on a file that did not exist in older commits.
Find when a file changed significantly
If you know which file is involved but not which commit touched it:
git log --oneline path/to/file.js
This narrows the suspect list. If the list is short enough, reviewing the diffs directly is faster than a bisect. For a long list, start bisect with the earliest commit that touches that file as the known-good point.
When bisect is hard to use
The bug is not reproducible with a simple script. Manual bisect still works — you just test by hand at each step. Even manually, binary search on 100 commits takes at most 7 rounds.
The build is broken on many commits. Tell Git to skip commits where you cannot test:
git bisect skip
Git moves to a nearby commit and continues. The final result will be a range of commits rather than a single one if the true culprit is adjacent to a skipped commit.
The bug is a performance regression. Benchmark scripts work fine as the test command — exit 0 if performance is acceptable, exit 1 if not. The threshold needs to be reliable enough that the result does not flip due to system noise.
The result is a starting point, not the full answer
git bisect finds the commit that first exhibited the bug — but the commit that caused it might be earlier. The commit git identifies might be an innocent victim: it calls a function that was broken by an earlier change, or it exercises a code path that already had a latent bug.
Once you have the commit, read the diff:
git show b2c3d4e5
Understand what it changed. Then look at the commits immediately before it if the change itself looks harmless. The bug is usually either in the identified commit or in a nearby one that set up the conditions.
Found this useful? SysEmperor has more Git tutorials and free developer tools at sysemperor.com — including a SQL Table Editor, chmod Calculator, and downloadable AI skills for Claude.
