git-bisect(1)
=============

NAME
----
git-bisect - Use binary search to find the commit that introduced a bug


SYNOPSIS
--------
[verse]
'git bisect' <subcommand> <options>

DESCRIPTION
-----------
The command takes various subcommands, and different options depending
on the subcommand:

 git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
 git bisect (bad|new|<term-new>) [<rev>]
 git bisect (good|old|<term-old>) [<rev>...]
 git bisect terms [--term-(good|old) | --term-(bad|new)]
 git bisect skip [(<rev>|<range>)...]
 git bisect reset [<commit>]
 git bisect (visualize|view)
 git bisect replay <logfile>
 git bisect log
 git bisect run <cmd> [<arg>...]
 git bisect help

This command uses a binary search algorithm to find which commit in
your project's history introduced a bug. You use it by first telling
it a "bad" commit that is known to contain the bug, and a "good"
commit that is known to be before the bug was introduced. Then `git
bisect` picks a commit between those two endpoints and asks you
whether the selected commit is "good" or "bad". It continues narrowing
down the range until it finds the exact commit that introduced the
change.

In fact, `git bisect` can be used to find the commit that changed
*any* property of your project; e.g., the commit that fixed a bug, or
the commit that caused a benchmark's performance to improve. To
support this more general usage, the terms "old" and "new" can be used
in place of "good" and "bad", or you can choose your own terms. See
section "Alternate terms" below for more information.

Basic bisect commands: start, bad, good
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As an example, suppose you are trying to find the commit that broke a
feature that was known to work in version `v2.6.13-rc2` of your
project. You start a bisect session as follows:

------------------------------------------------
$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good
------------------------------------------------

Once you have specified at least one bad and one good commit, `git
bisect` selects a commit in the middle of that range of history,
checks it out, and outputs something similar to the following:

------------------------------------------------
Bisecting: 675 revisions left to test after this (roughly 10 steps)
------------------------------------------------

You should now compile the checked-out version and test it. If that
version works correctly, type

------------------------------------------------
$ git bisect good
------------------------------------------------

If that version is broken, type

------------------------------------------------
$ git bisect bad
------------------------------------------------

Then `git bisect` will respond with something like

------------------------------------------------
Bisecting: 337 revisions left to test after this (roughly 9 steps)
------------------------------------------------

Keep repeating the process: compile the tree, test it, and depending
on whether it is good or bad run `git bisect good` or `git bisect bad`
to ask for the next commit that needs testing.

Eventually there will be no more revisions left to inspect, and the
command will print out a description of the first bad commit. The
reference `refs/bisect/bad` will be left pointing at that commit.


Bisect reset
~~~~~~~~~~~~

After a bisect session, to clean up the bisection state and return to
the original HEAD, issue the following command:

------------------------------------------------
$ git bisect reset
------------------------------------------------

By default, this will return your tree to the commit that was checked
out before `git bisect start`.  (A new `git bisect start` will also do
that, as it cleans up the old bisection state.)

With an optional argument, you can return to a different