git-bisect

git bisect subcommand [options]

git bisect finds the commit that introduced a problem by binary search. You tell it one commit where the bug exists and one where it does not; it checks out a commit in the middle, you test and report the result, and it halves the remaining range each time. The search is logarithmic, so roughly 10 tests suffice for 1000 commits and 20 for a million.The good/bad vocabulary assumes you are hunting a bug, but the mechanism is general: any property that changed at some point can be bisected. old/new, and the custom --term-old/--term-new, exist for hunting a performance regression, a behaviour change, or even the commit that fixed something.git bisect run is where the command earns its reputation. Given a script that exits 0 for good and non-zero for bad, git drives the whole search unattended. The special exit code 125 means "cannot test this commit", producing the same effect as skip, and any exit code between 126 and 255 aborts the session. Because run takes a command line rather than only a file, git bisect run make test works directly.When the search finishes, git reports the first bad commit and leaves you at it. git bisect reset returns you to where you were.

start [bad [good...]] [--] [paths...]

Begin a session. Optionally give the bad and good commits immediately, and limit the search to paths.

Mark a commit as containing the bug. Defaults to the current commit.

Mark one or more commits as free of the bug.

Aliases for bad and good, for hunting any change in behaviour rather than a bug.

Use your own words, e.g. --term-old=fast --term-new=slow.

Skip commits that cannot be tested, e.g. ones that do not build.

Run cmd at each step and mark automatically from its exit status.

End the session and return to the original branch, or to commit.

Print the log of what has been marked.

Replay a bisect log, resuming a previous session.

Show the remaining candidate commits in gitk or git log.

Follow only the first parent of merge commits.

Do not check out the tree; just update BISECT_HEAD. Useful when checkout is expensive.

Exit code 1 means bad, but so do most failures, including a compile error or a missing dependency. A test script that cannot distinguish "the bug is present" from "this commit does not build" will blame the wrong commit. Return 125 for untestable commits.Avoid exit code 255 in a test script: it aborts the bisect. grep returns 1 when it finds nothing, which is convenient, but a script ending in a bare grep inverts the meaning you probably intended, so be explicit about the exit status.Bisect checks out arbitrary historical commits, so a dirty working tree can block the checkout or silently contaminate the test. Commit or stash first. Build artifacts and generated files also survive between checkouts and can mask the real result: clean them in the test script.skip does not narrow the range as effectively as a real answer, and skipping a whole region can leave git unable to identify a single culprit, reporting a range of candidates instead.The result is only the first commit where your test fails, which is not always the commit that caused the problem. A bug can be introduced latent and only exposed later by an unrelated change.If history contains merges, the first bad commit may be a merge, and the actual change lives on the merged branch. --first-parent limits the search to the mainline, which is often what you want on a repository that merges feature branches.

git bisect was added by Linus Torvalds in 2005, in git's first year, initially as a shell script. git bisect run followed shortly after, contributed by Christian Couder, who also added the old/new terminology in git 2.7 (2015) for bisecting changes that are not bugs. The implementation was gradually rewritten in C over subsequent releases.

git(1), git-log(1), git-blame(1), git-annotate(1), git-stash(1)

Source code · Homepage · Documentation