Git Bisect: Finding the Commit That Broke It
Bisect does a binary search through history to find the commit that introduced a bug. Learn the workflow and how to automate it.
By Velloreth
The idea
A bug exists now but did not exist at some earlier commit. Something between them introduced it. Bisect finds that commit by binary search.
You mark a known-good commit and a known-bad commit. Bisect checks out the midpoint. You test it and say whether it is good or bad. Bisect halves the range and repeats.
The number of steps is logarithmic. For 1000 commits, about 10 tests. For a million, about 20. This is why bisect is far faster than checking out commits one by one.
The manual workflow
Start:
git bisect start
Mark the current commit as bad:
git bisect bad
Mark a known-good commit:
git bisect good v1.2.0
Bisect checks out the midpoint and reports how many steps remain.
Bisecting: 12 revisions left to test after this (roughly 4 steps)
[a1b2c3d] Add caching layer
Test the current commit. Run the test, reproduce the bug, or check the behaviour.
Report the result:
git bisect good # the bug is not present here
git bisect bad # the bug is present here
Repeat until bisect identifies the culprit.
a1b2c3d is the first bad commit
commit a1b2c3d
Author: ...
Date: ...
Add caching layer
src/cache.js | 42 ++++++++++++++++++++++++++++++
Finish:
git bisect reset
This returns you to the branch you were on. Always run it, or you are left in a detached HEAD state.
The automated workflow
git bisect run runs a command at each step and uses the exit code.
git bisect start
git bisect bad
git bisect good v1.2.0
git bisect run npm test
The command must exit 0 for good and non-zero for bad. Bisect runs it at each step and decides which half to search.
This turns a tedious manual process into a single command. For a test suite that takes a minute, a 1000-commit search finishes in about ten minutes unattended.
A more targeted script:
#!/bin/sh
# bisect-test.sh
npm run build || exit 125 # 125 means "skip this commit"
npm test -- --grep "checkout" || exit 1
exit 0
The exit codes:
- 0 — good.
- 1-124, 126-127 — bad.
- 125 — skip this commit (it cannot be tested).
- 128+ — abort the bisect.
Skipping commits
A commit that does not build cannot be tested. Mark it as skipped.
git bisect skip
Bisect avoids it and tries a nearby commit. If too many commits are skipped, bisect may not be able to identify a single culprit, and it reports a range instead.
In an automated run, exit 125 to skip.
Narrowing the search
Limit to a path. If you know the bug is in a specific area, restrict the search to commits that touched it.
git bisect start -- src/checkout
This can reduce the number of steps dramatically, because most commits are irrelevant.
Use a tag or a date. A known-good release is a good starting point.
git bisect good v1.2.0
Use a merge base. If the bug is on a feature branch, the merge base with main is a good candidate for the good commit.
git bisect good $(git merge-base HEAD main)
A worked example
A checkout page started failing. The last release was two weeks ago.
git bisect start
git bisect bad HEAD
git bisect good v1.2.0
# Bisecting: 47 revisions left to test after this (roughly 6 steps)
Rather than testing manually, automate it:
git bisect run npm test -- --grep "checkout"
Six steps later:
b7c8d9e is the first bad commit
Refactor cart totals to use a shared helper
The refactor changed how totals were computed, and the checkout test caught it. The whole search took a few minutes.
Why it works
The assumption is that the bug is monotonic: once introduced, it stays present. If a commit fixes it and a later commit reintroduces it, bisect finds the first introduction, which may not be the one you care about.
The other assumption is that you can test a commit reliably. A flaky test makes bisect unreliable, because a false “good” or “bad” sends the search down the wrong half.
For flaky tests, run the test several times and treat any failure as bad. Or fix the flakiness first.
Bisect in practice
A few habits make bisect more reliable.
Write the test first. The value of bisect depends on a test that reliably distinguishes good from bad. If you are testing manually, write down the exact steps so you repeat them identically at each step.
Use a fast test. A test that takes ten minutes makes a ten-step bisect take over an hour. Narrow the test to the specific failure, even if it is not the full suite.
Record the result. Note the culprit commit and what it changed. The commit message and diff usually explain the bug, and the fix is often obvious once you see it.
Add a regression test. Once you know the culprit, add a test that would have caught it. This is the lasting value of the exercise.
Bisect is not only for bugs. It works for any monotonic change: a performance regression, a bundle size increase, or a behaviour change. Any question of the form “when did this start?” is a bisect candidate.
Practical guidance
- Use
git bisect runto automate the search. - Exit 0 for good, non-zero for bad, 125 to skip.
- Limit to a path with
-- <path>to reduce steps. - Always
git bisect resetwhen done. - Fix flaky tests first, or the result is unreliable.
- Use a release tag as the known-good commit.
- Skip commits that do not build with
git bisect skip. - Bisect finds the first bad commit, which is the one that introduced the problem.
For the related guides, see git-undo-changes-guide and git-commit-messages-guide. For the broader context, debugging-strategies-that-work and fixing-flaky-tests.
Quotable summary
Bisect performs a binary search through commits to find the one that introduced a bug, marking a known-good commit and a known-bad commit and checking out the midpoint for you to test. It finds the culprit in log2(n) steps, so 1000 commits take about 10 tests and a million take about 20, which is why it is far faster than checking out commits one by one. git bisect run automates the search with a script that exits 0 for good, non-zero for bad, and 125 to skip an untestable commit. The result is the first bad commit, which is the one that introduced the problem, and you should always run git bisect reset when done or you will be left in a detached HEAD state. Flaky tests make bisect unreliable, so fix them first.