Home / Guides / Bisect
Git guide / 02

Find the first bad commit

When a behavior changed somewhere in a long history, git bisect narrows the range by asking you to test selected commits.

You need one commit where the problem exists and an older commit where it does not. The check must mean the same thing at every revision: for example, a test exits successfully when the bug is absent and fails when it is present.

Mark the ends of the range

Start from a clean working tree so switching revisions does not mix your edits with old code. Save the branch name or current commit, then begin the search:

git status --short
git bisect start
git bisect bad HEAD
git bisect good GOOD_COMMIT

Git checks out a commit between those endpoints. Reproduce the issue there. Mark it bad if the issue is present, or good if it is absent; Git then chooses another commit. An unbuildable revision can be marked git bisect skip, though too many skipped commits may leave several candidates.

# run the same check at the commit Git selected
git bisect good   # or: git bisect bad
# repeat until Git reports the first bad commit
git bisect reset

git bisect reset restores the checkout you had before the search. Inspect the reported commit and its neighbors before assigning blame: a failed test may depend on an external service, generated files, or a setup change rather than the code in that commit.

Automate only a trustworthy check

If a script reliably returns 0 for good and a nonzero status for bad, git bisect run ./check.sh can perform the remaining checks. The script must set up its own test environment and avoid writing to external systems. Git treats exit code 125 as “cannot test this revision.”

Before you start: verify the chosen good revision really passes the same check. Otherwise bisect will efficiently answer the wrong question.

Read the rebase guide →

Further reading

Primary sources