Appearance
Finding Bugs with git bisect
You have a bug. You know the code worked last week. You do not know which commit broke it. Scrolling through a hundred commits looking for the culprit wastes time. git bisect automates the search.
Bisect performs binary search across your commit history. With 100 commits in the range, it finds the guilty one in 7 steps. With 1000 commits, 10 steps. It is the fastest way to answer "what introduced this bug?"
The basic workflow
1. Start the bisect
bash
git bisect start2. Mark a known-good and a known-bad commit
bash
git bisect good v2.0.0 # the last version where the bug did not exist
git bisect bad HEAD # the current version where the bug existsYou can use any ref: a tag, a branch name, a commit SHA, or HEAD.
3. Test, mark, repeat
Git checks out a commit halfway between good and bad. You test it:
bash
# Run your test
npm test
# or
python -m pytest tests/test_login.pyThen tell Git the result:
bash
git bisect good # the bug does not exist here
git bisect bad # the bug exists hereGit checks out the next midpoint. Repeat until Git prints:
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 is the first bad commit4. Exit the bisect
bash
git bisect resetThis returns your working tree and HEAD to where they were before you started.
A real example
You run a web app. Users cannot log in. You know it worked 3 days ago. Your last 40 commits look innocent.
bash
git bisect start
git bisect bad HEAD
git bisect good HEAD~40Git checks out commit 20 of 40. You open the app, try to log in. It works.
bash
git bisect goodGit checks out commit 30. Login fails.
bash
git bisect badGit checks out commit 25. Login works.
bash
git bisect goodGit checks out commit 27. Login fails.
bash
git bisect badGit checks out commit 26. Login fails.
bash
git bisect bad9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b is the first bad commitYou run git show 9a8b7c6 and see the commit changed the auth middleware. Found in 6 steps instead of reading 40 commits.
What bisect does to your working tree
When bisect checks out a commit, it updates your working tree to match that commit's state. If you have uncommitted changes, Git refuses to start:
error: Your local changes to the following files would be overwrittenCommit or stash your work before starting.
Automating the test with bisect run
For bugs that have a reliable reproduction script, you can let Git run the test automatically:
bash
git bisect start HEAD HEAD~40
git bisect run npm testOr with a custom script:
bash
git bisect run ./test-login.shThe script must exit with code 0 for "good" and any non-zero code (1-127, except 125) for "bad". Exit code 125 tells bisect to skip that commit (unbuildable, unrelated failure).
Git runs the script at each step and narrows the range automatically. Walk away while it works.
When to skip a commit
Some commits cannot be tested: a halfway-finished refactor that does not compile, a merge commit with no meaningful diff, or a commit in a completely unrelated area. Tell bisect to skip it:
bash
git bisect skipOr during bisect run, exit with code 125:
bash
#!/bin/bash
make build || exit 125 # skip if build fails
npm test # actual testViewing progress
bash
git bisect logShows the entire history of the current bisect session: every good/bad/skip marking in order. Useful if you think you made a mistake and want to replay.
bash
git bisect visualizeOpens git log --oneline --graph focused on the bisect range. Lets you see where you are in the commit graph.
Replaying a bisect
Save the log from a session, fix a mistake, then replay:
bash
git bisect log > bisect-log.txt
# Edit bisect-log.txt to fix the wrong marking
git bisect reset
git bisect replay bisect-log.txtThis saves time when you accidentally mark a commit wrong mid-session.
What makes a good bisect range
| Good range | Bad range |
|---|---|
| A known-working tag or commit | A known-broken commit |
| Close to the bug in time | As early as possible |
Narrow by file (-- src/auth/) | On the same branch |
| Right before the suspected change | HEAD or the broken release |
The narrower the range, the fewer steps. If you know the bug is in src/auth/, use:
bash
git bisect start HEAD v2.0.0 -- src/auth/Git only considers commits that touched that path. Everything else is skipped automatically.
Common pitfalls
| Pitfall | Why it hurts | How to avoid |
|---|---|---|
| Uncommitted changes when starting | Bisect refuses to start | Stash or commit first |
| Testing with wrong repro steps | False good/bad marking | Run the same test every time |
| Skipping too many commits | Range may not narrow to a single commit | Use -- src/path/ to skip irrelevant commits automatically |
| The bug is intermittent | Bisect lands on the wrong commit | Test multiple times, mark skip on uncertain results |
Forgetting to git bisect reset | HEAD stays on the bisected commit | Run git bisect reset as soon as you find the commit |
| The bug existed before your "good" commit | Bisect stops at the first commit in the range | Pick a truly good commit, not just "I think it worked here" |
When NOT to use bisect
Bisect is not the right tool for every situation:
- The bug is in uncommitted changes. Bisect only searches committed history. Commit your debug work or use
git stashfor experiments. - The bug is environment-specific. If the bug depends on deployment config, a database migration, or a specific OS version, bisect across commits alone will mislead you.
- You already know the culprit. If
git blameor a recent change log points directly at a commit, go look at it instead. - History has been rewritten. If the range includes a rebase or squash, the commit that introduced the bug may not exist anymore.
Quick reference
bash
git bisect start # Begin a bisect session
git bisect bad <ref> # Mark a known-bad commit
git bisect good <ref> # Mark a known-good commit
git bisect good # Current commit is good
git bisect bad # Current commit is bad
git bisect skip # Current commit is untestable
git bisect reset # End session, return to original HEAD
git bisect log # Show session history
git bisect run ./script.sh # Automatic bisect with a test script
git bisect visualize # Graph of the bisect range
git bisect start HEAD v2.0 -- src/ # Narrow to commits touching src/Next steps
Once you are comfortable with manual bisect, try git bisect run with a test script. The automated mode turns bisect into a fire-and-forget tool. Start it, walk away, and come back to the culprit commit. For more advanced patterns like bisecting across branches or integrating with CI, see the advanced bisect guide.