Introduction

git bisect is the fastest way to locate the commit that introduced a bug when you know one older commit was good and a newer commit is bad. It uses binary search over your commit history, so instead of checking dozens of commits one by one, you usually test only a small handful.

The Basic Workflow

A bisect session needs two anchor points:

• one known bad commit, often HEAD
• one known good commit, where the bug definitely does not exist

Then Git checks out a midpoint commit for you to test. After each test, you tell Git whether that revision is good or bad, and Git picks the next midpoint.

A typical session looks like this:

git bisect start
git bisect bad
git bisect good v1.4.2

Here, HEAD is assumed to be bad, and tag v1.4.2 is known good. Git now checks out a candidate commit in detached HEAD state.

Testing Each Candidate Commit

At each step, run the smallest reliable test that exposes the bug. That could be a unit test, a command-line invocation, or even a manual reproduction if automation is impossible.

If the bug is present:

git bisect bad

If the bug is absent:

git bisect good

Git repeats that process until it narrows the search to one commit. A final message identifies the first bad commit, along with the commit message and hash.

This process is efficient because every answer cuts the search space roughly in half.

Automate The Test When Possible

Manual bisecting works, but an automated test is much better because it removes guesswork and speeds up the whole search.

Create a script that exits with 0 for good and nonzero for bad. Then let Git run it for each midpoint:

1cat > /tmp/bisect-test.sh <<'SH'
2#!/bin/sh
3pytest tests/test_login.py -q
4SH
5chmod +x /tmp/bisect-test.sh
6
7git bisect start
8git bisect bad
9git bisect good v1.4.2
10git bisect run /tmp/bisect-test.sh

git bisect run checks out each midpoint, runs the script, reads the exit status, and continues automatically.

This is the best approach when the bug is reproducible in CI-like conditions.

Picking Good And Bad Commits Carefully

The search is only as good as your anchor commits. If the so-called good commit already contains the bug, or the bad commit fails for an unrelated reason, the result becomes misleading.

Pick commits with these properties:

• the repository builds successfully
• the test condition is stable
• the bug is clearly present or clearly absent

If some intermediate commits are broken for unrelated reasons, you can skip them:

git bisect skip

Skipping is useful when a midpoint cannot be tested because of a build failure unrelated to the bug you are chasing.

A Realistic Example

Assume your application crashes on startup today, but worked in release v2.0.0.

git bisect start
git bisect bad HEAD
git bisect good v2.0.0

Git checks out a midpoint. You run:

npm test -- --runInBand startup.spec.js

If the startup test fails, mark that midpoint bad. If it passes, mark it good. After several iterations, Git reports the first bad commit. At that point, inspect the diff:

git show <commit-hash>

The point of git bisect is not only to identify who changed the code, but to reduce the debugging surface area to one exact change.

Always Reset When You Finish

A bisect session leaves the repository in detached HEAD state. When you are done, restore your normal checkout:

git bisect reset

This returns you to the branch you were on before the bisect started.

If you forget this step, later commands can feel confusing because you are no longer on your working branch.

Common Pitfalls

The biggest pitfall is using an unreliable test. If the test is flaky, Git may classify the same commit differently on different runs, which undermines the search.

Another common mistake is picking a good commit that was never actually verified. A label like old release is not enough unless you know the specific bug was absent there.

People also forget about uncommitted changes. Start from a clean working tree so your local modifications do not affect the test result.

Finally, remember that git bisect only finds the first bad commit relative to your chosen good point. If the bug depends on multiple later changes or environmental drift, you may still need follow-up analysis.

Summary

• 'git bisect performs a binary search through commit history.'
• Start with one known bad commit and one known good commit.
• Test each midpoint and mark it good, bad, or skip.
• Prefer git bisect run with an automated script whenever possible.
• Finish with git bisect reset to return to your normal branch.