Skip to content
Velloreth
Developer Tools 6 min read

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

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.

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 run to 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 reset when 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.

Frequently asked questions

What does git bisect do?
It performs a binary search through the commit history to find the first commit where a bug is present. You mark a good commit and a bad commit, and bisect checks out the midpoint for you to test.
How many steps does bisect take?
It takes about log2(n) steps. For 1000 commits that is about 10 tests, and for a million commits it is about 20. This is why it is far faster than checking out commits one by one.
What is git bisect run?
It automates the search by running a command at each step. The command must exit 0 if the commit is good and non-zero if it is bad. Bisect uses the exit code to decide which half to search next.
What if a commit does not build?
Use git bisect skip to mark it as untestable. Bisect will avoid it and try a nearby commit. If too many commits are skipped, bisect may not be able to identify a single culprit.
How do I stop bisect?
Use git bisect reset, which returns you to the branch you were on before the bisect started. Always run this when you are done, or you will be left in a detached HEAD state.
Can I bisect on a specific file or path?
Yes. Use git bisect start -- <path> to limit the search to commits that touched that path, which can dramatically reduce the number of steps.