Git Bisect: Binary Search Through History

Advanced

Learner goal

By the end of this lesson, you should be able to use `git bisect` to narrow a history range to the first commit that changes a tested property, control a manual bisection, automate the checks with `git bisect run`, handle untestable revisions safely, replay a recorded session, and clean up the bisection state.

known good → candidate revisions → known bad
manual: git bisect good / bad
automated: git bisect run <test-command>
finish: inspect the first bad commit, then git bisect reset

You know an older revision has the old behavior and a later revision has the new behavior.?Git repeatedly selects a revision in the remaining range for testing.

Start with known endpoints

A normal regression investigation begins with one commit known to be good and a later commit known to be bad. `git bisect start` creates the bisection state; you can then mark the endpoints with `git bisect good` and `git bisect bad`. Once both sides are known, Git selects a commit between them and checks it out for testing.

git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>

The bisection has at least one good and one bad boundary.?A candidate revision becomes the current revision to test.

Mark each tested revision

Test the checked-out revision using the actual behavior you are investigating. If the property is still in its old or working state, run `git bisect good`; if the property is in its new or broken state, run `git bisect bad`. Git then narrows the remaining search and normally selects the next revision automatically.

# Test the current revision
git bisect good    # property is still good
# or
git bisect bad     # property is bad

A selected revision is checked out.?Your test result determines the next side of the search range to keep.

Finish the investigation and reset

When the bisection finishes, Git reports the first bad commit and leaves `refs/bisect/bad` pointing at it. Inspect that commit before making any corrective change. Then run `git bisect reset` to leave the bisection state and return to the commit that was checked out before the session started.

git show --no-patch --format=fuller refs/bisect/bad
git bisect reset

The search has finished and the first bad commit has been reported.?The bisection state is removed and the original checkout is restored.

Skip revisions that cannot be tested

Sometimes the selected revision cannot be tested—for example, it may fail to build for a reason unrelated to the property you are investigating. Use `git bisect skip` rather than inventing a good/bad result. Git can also skip a range, but skipping a revision adjacent to the sought change can make the exact first bad commit impossible to identify.

git bisect skip
# or skip an explicit revision
git bisect skip <revision>
# inspect the recorded decisions
git bisect log

A candidate revision cannot be tested reliably.?The candidate is excluded without fabricating a good/bad result, but the final answer may become less precise.

Automate with `git bisect run`

When a command can classify the current source automatically, `git bisect run <command>` repeats the test for each selected revision. Git interprets the test command's exit status: `0` means good/old, `1` through `127` except `125` means bad/new, `125` means the revision cannot be tested and should be skipped, and any other exit status aborts the bisection.

git bisect start HEAD <known-good-commit>
git bisect run ./test-regression.sh
git bisect reset

An automated test cannot produce a trustworthy classification for the current revision.?Git records the revision as skipped and continues the bisection.

A test command is run against the selected revision.?Its exit status supplies Git with the revision classification.

Record and replay a bisection

`git bisect log` records the decisions made during the session. If a classification was entered incorrectly, the official correction workflow is to save the log, correct the entries, run `git bisect reset`, and then run `git bisect replay <file>` to reconstruct the corrected state.

git bisect log > bisect.log
# edit bisect.log if a classification was wrong
git bisect reset
git bisect replay bisect.log

A bisect session has recorded decisions, including a mistake you need to correct.?After reset, replay rebuilds the bisection state from the corrected log.

Use alternate terms when good/bad is confusing

Bisection is not limited to regressions. Git also supports `old` and `new`, or custom terms, when the property changes in a direction where “good” and “bad” are misleading. In one session, do not mix the `good`/`bad` vocabulary with `old`/`new`; start the session with the alternate terms and then use those terms consistently.

git bisect start --term-old=broken --term-new=fixed
git bisect broken <old-revision>
git bisect fixed HEAD
git bisect terms

The investigation is easier to describe with property-oriented terms such as broken/fixed.?The bisect state uses the chosen terms consistently for its classifications.

Treat the test property as the critical evidence

`git bisect` is only as useful as the classification you give it. A test that is inconsistent across revisions, or a skipped revision near the transition, can prevent an exact answer. The result identifies the commit Git can establish as the first bad/new revision within the supplied search constraints; it does not replace the engineering work of inspecting that commit and confirming what changed.

git bisect log
git show --stat refs/bisect/bad
git bisect reset

Git has narrowed the range to a first bad/new candidate.?You inspect the identified commit before deciding what correction is appropriate.

Official-source boundary

This lesson uses only official Git project documentation: `git-bisect` for the binary-search workflow, endpoint classification, reset, skip, automation exit statuses, log/replay, and alternate terms; the official Git book for the debugging workflow. The live `git-bisect` manual was rechecked on 2026-10-01 and is current through Git 2.56.0 (2026-09-28). Foxipa's local verifier is Git 2.47.3, so execution evidence is reported for that installed executable. Current documentation also exposes newer options such as `--first-parent` and `--reset-when-found`; they are deliberately outside this lesson's core scope so learners can master the stable investigation workflow before the advanced variants.