Git Bisect: Find the First Bad Commit

When a feature worked last week but fails today, checking commits one by one is slow. git bisect helps you find the commit that introduced the problem. You identify one revision where the behavior is broken and an older revision where it still works. Git then checks out a commit between them and asks you to test it. Repeating the check narrows the range until Git identifies the first bad commit.

Bisect is especially helpful when a repository has many commits and you can reproduce the problem reliably. It changes the checked-out revision while it runs, so first save or commit your current work.

Before you start

Choose a test with a clear pass or fail result. It might be an automated test, a build command, or a short manual check. Confirm that the problem exists at the current commit. Then find an earlier commit known to work, perhaps from a release tag or git log. The good and bad revisions must describe the same specific behavior.

Tip: A bisect session checks out historical commits and may leave you at a detached HEAD. Run git bisect reset when finished to return to your original branch.

Find a regression manually

Start the session, mark the current commit bad, and mark an older known-good revision. Replace the sample tag with one from your repository.

Example: Start bisecting

# Save your current work before Git switches revisions.
git status --short

# The current commit fails; release v2.4 passed.
git bisect start
git bisect bad
git bisect good v2.4

Git checks out a commit between the two endpoints and reports approximately how many revisions remain. Run the same check at this revision. If it works, enter git bisect good; if it fails, enter git bisect bad. Git then chooses the next commit. Keep testing until it reports the first bad commit.

Example: Mark each result

# Run your project's test at the commit Git selected.
./test-regression.sh

# Choose exactly one based on the observed result.
git bisect good
# Or, if the regression is present:
git bisect bad

A typical final message resembles this illustrative output:

a1b2c3d is the first bad commit
commit a1b2c3d
Author: Example Developer
    Change price rounding

The hash and message will differ in your repository. Inspect the candidate with git show a1b2c3d, then verify that the identified change explains the failure. A failing test at one commit is evidence, not a substitute for understanding the cause.

Automate the test with git bisect run

If a command can decide pass or fail without your input, let Git run it at every selected revision. The test must exit with status 0 for good and a nonzero status for bad. Use 125 when a revision cannot be tested and should be skipped. Keep the script focused on the regression, not an unrelated lint or network failure.

Example: Run an existing regression script

# After setting the good and bad endpoints:
git bisect run ./test-regression.sh

# Inspect the first bad commit and return to your branch.
git show --stat HEAD
git bisect reset

If your script needs dependencies, make its setup repeatable at historical commits. A newer test file may not exist in older revisions; place a self-contained check outside the checkout when needed. Avoid a script that modifies tracked files, because later checkout steps can fail when the working tree becomes dirty.

Skip an untestable commit

Some revisions do not build, even though they are not the regression you are looking for. Use git bisect skip at such a commit. Git tries other revisions, but too many skipped commits can prevent it from naming one exact culprit. In that case, it reports a range of possible first bad commits.

Example: Skip and finish

# This historical revision cannot run the focused test.
git bisect skip

# Check where the bisect session stands.
git bisect log

# Restore the original branch after investigating.
git bisect reset

Common mistakes to avoid

• Do not choose a “good” revision that was never tested; an incorrect endpoint makes the result misleading.
• Do not change the pass/fail rule halfway through the search.
• Do not treat a missing dependency as proof that the behavior is bad. Fix the test environment or skip the revision.
• Do not forget git bisect reset; it restores the checkout you had before the session.

Conclusion

git bisect turns a long commit history into a small sequence of focused checks. Give it a verified good revision and a verified bad one, test every selected commit consistently, and inspect the reported first bad commit. For a repeatable regression test, git bisect run makes the search even faster.