git bisect for Debugging
A regression appears: a test that passed last month now fails, but nobody knows which of the hundreds of commits since then introduced it. Checking each commit one at a time is painfully slow. git bisect solves this with binary search: you tell it one commit known to be 'good' (bug not present) and one known to be 'bad' (bug present), and it checks out the commit exactly halfway between them, asking you to test and report back 'good' or 'bad'. Each answer halves the remaining search space, so even thousands of commits can be narrowed down to the single culprit in roughly log2(n) steps — around 10 tests to search 1,000 commits.
Cricket analogy: Like a curator checking the pitch conditions from ball 500 of a five-day archive to find exactly when the pitch started spinning excessively, then jumping to ball 250, halving the search each time instead of reviewing every ball from day one.
Manual bisecting
git bisect start begins the session. You then mark a known-bad commit (often HEAD, if the bug is currently present) with git bisect bad, and a known-good commit further back — perhaps the last tagged release — with git bisect good <sha>. Git checks out the midpoint commit in detached HEAD state; you build and test that exact state, then run git bisect good or git bisect bad depending on the result. Git narrows the range and checks out the next midpoint automatically. This repeats until only one commit remains, which git bisect identifies as the first bad commit, printing its SHA and message.
Cricket analogy: Like starting a review session by flagging today's match as "problem present" and a match from last season as "problem absent," then the analyst pulls up the exact midpoint match to review in isolation, reporting back "fine" or "faulty" until only one match remains.
# Manual bisect session
$ git bisect start
$ git bisect bad # current HEAD has the bug
$ git bisect good v2.3.0 # this tagged release was known-good
Bisecting: 42 revisions left to test after this (roughly 6 steps)
[9f8e7d6...] Merge pull request #512 from feature/cache-layer
# ... build and run the app / test suite at this commit ...
$ git bisect bad # bug is present here too
Bisecting: 20 revisions left to test after this (roughly 5 steps)
$ git bisect good # bug NOT present here
Bisecting: 9 revisions left to test after this (roughly 3 steps)
# ... continue until Git reports the culprit ...
8a7b6c5 is the first bad commit
commit 8a7b6c5f...
Author: Dana Wu <dana@example.com>
Refactor cache eviction to use LRU
$ git bisect reset # return to your original branch/HEADAutomating with git bisect run
If the bug can be detected programmatically — a failing unit test, a script that exits non-zero on failure — you can fully automate the process with git bisect run <script>. Git checks out each midpoint, executes the script, and interprets its exit code: 0 means good, any nonzero value from 1-127 (except 125) means bad, and exit code 125 tells bisect to skip this commit entirely (useful when a commit doesn't build or the test is inapplicable at that point in history). This turns a search that might take an engineer an hour of manual testing into an unattended process that finishes in minutes.
Cricket analogy: Like automating pitch inspection with a sensor that reports pass or fail on spin-friendliness for each historical match automatically, skipping matches where no ball-by-ball data exists, turning a week of manual archive review into an unattended overnight scan.
# Fully automated bisect using a test script
$ git bisect start HEAD v2.3.0
$ git bisect run npm test -- --grep "cache eviction respects LRU order"
# Git checks out each midpoint, runs the test, and reads the exit code
# to decide good/bad automatically, printing the culprit at the end.git bisect skip is useful when a particular commit is untestable for reasons unrelated to the bug you're hunting — e.g. it doesn't compile because of an unrelated in-progress refactor. Skipping tells bisect to try a nearby commit instead of forcing an answer for that exact revision.
Bisect assumes the bug's presence is monotonic across the range — once introduced, it stays introduced until fixed. If the bug appears, gets accidentally fixed, then reappears (flaky or intermittent bugs, or reverted-and-reintroduced changes), bisect's binary search logic breaks down and can point to the wrong commit or terminate with a nonsensical result.
- git bisect performs binary search over commit history to find the exact commit that introduced a bug.
- You seed it with one known-bad and one known-good commit via git bisect bad / good.
- At each step, test the checked-out commit and report good or bad; git narrows the range automatically.
- git bisect run <script> automates the whole process using a script's exit code (0=good, 1-127 except 125=bad, 125=skip).
- git bisect skip handles commits that can't be meaningfully tested (e.g. broken builds unrelated to the bug).
- Bisect assumes monotonic bug presence; intermittent or flaky bugs can produce misleading results.
Practice what you learned
1. What algorithmic strategy does git bisect use to find a bug-introducing commit?
2. In `git bisect run <script>`, what does an exit code of 125 signal?
3. What must you do to seed a bisect session before Git starts checking out midpoints?
4. Roughly how many test steps would git bisect need to find a bug among 1,000 commits?
5. Why can git bisect produce misleading results for an intermittently flaky bug?
Was this page helpful?
You May Also Like
Viewing History with git log
Learn to inspect a repository's commit history using git log's filtering, formatting, and graph options to understand who changed what and why.
git reset Explained
How git reset moves the current branch pointer and optionally rewrites the staging area and working directory, and the meaningful difference between its --soft, --mixed, and --hard modes.
Interactive Rebase
Interactive rebase lets you reorder, squash, edit, or drop commits before they land, turning a messy work-in-progress history into a clean, reviewable narrative.
Common Git Pitfalls
A field guide to the mistakes that trip up both new and experienced Git users, why each one happens, and how to avoid or recover from it.
Related Reading
Related Study Notes in Software Engineering
Browse all study notesMicroservices Study Notes
Software Architecture · 30 topics
Software EngineeringTesting & TDD Study Notes
Software Testing · 30 topics
Software EngineeringDesign Patterns Study Notes
Software Design · 30 topics
Software EngineeringSoftware Engineering Study Notes
Python · 75 topics
Software EngineeringSystem Design Study Notes
Architecture · 46 topics