25 Makefile
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[2ddcca36c8bcfa251724fe342c8327451988be0d] Linux 2.6.26-rc1
running grep ^SUBLEVEL = 25 Makefile
2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit
commit 2ddcca36c8bcfa251724fe342c8327451988be0d
Author: Linus Torvalds <torvalds@linux-foundation.org>
Date:   Sat May 3 11:59:44 2008 -0700

    Linux 2.6.26-rc1

:100644 100644 5cf82581... 4492984e... M      Makefile
bisect run success
-------------

In this example, we passed "grep '^SUBLEVEL = 25' Makefile" as
parameter to "git bisect run". This means that at each step, the grep
command we passed will be launched. And if it exits with code 0 (that
means success) then git bisect will mark the current state as
"good". If it exits with code 1 (or any code between 1 and 127
included, except the special code 125), then the current state will be
marked as "bad".

Exit code between 128 and 255 are special to "git bisect run". They
make it stop immediately the bisection process. This is useful for
example if the command passed takes too long to complete, because you
can kill it with a signal and it will stop the bisection process.

It can also be useful in scripts passed to "git bisect run" to "exit
255" if some very abnormal situation is detected.

Avoiding untestable commits
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes it happens that the current state cannot be tested, for
example if it does not compile because there was a bug preventing it
at that time. This is what the special exit code 125 is for. It tells
"git bisect run" that the current commit should be marked as
untestable and that another one should be chosen and checked out.

If the bisection process is driven manually, you can use "git bisect
skip" to do the same thing. (In fact the special exit code 125 makes
"git bisect run" use "git bisect skip" in the background.)

Or if you want more control, you can inspect the current state using
for example "git bisect visualize". It will launch gitk (or "git log"
if the `DISPLAY` environment variable is not set) to help you find a
better bisection point.

Either way, if you have a string of untestable commits, it might
happen that the regression you are looking for has been introduced by
one of these untestable commits. In this case it's not possible to
tell for sure which commit introduced the regression.

So if you used "git bisect skip" (or the run script exited with
special code 125) you could get a result like this:

-------------
There are only 'skip'ped commits left to test.
The first bad commit could be any of:
15722f2fa328eaba97022898a305ffc8172db6b1
78e86cf3e850bd755bb71831f42e200626fbd1e0
e15b73ad3db9b48d7d1ade32f8cd23a751fe0ace
070eab2303024706f2924822bfec8b9847e4ac1b
We cannot bisect more!
-------------

Saving a log and replaying it
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to show other people your bisection process, you can get a
log using for example:

-------------
$ git bisect log > bisect_log.txt
-------------

And it is possible to replay it using:

-------------
$ git bisect replay bisect_log.txt
-------------


"git bisect" details
--------------------

Bisection algorithm
~~~~~~~~~~~~~~~~~~~

As the Git commits form a directed acyclic graph (DAG), finding the
best bisection commit to test at each step is not so simple. Anyway
Linus found and implemented a "truly stupid" algorithm, later improved
by Junio Hamano, that works quite well.

So the algorithm used by "git bisect" to find the best bisection
commit when there are no skipped commits is the following:

1) keep only the commits that:

a) are ancestor of the "bad" commit (including the "bad" commit itself),
b) are not ancestor of a "good" commit (excluding the "good" commits).

This means that we get rid of the uninteresting commits in the DAG.

For example if we start with a graph like this:

-------------
G-Y-G-W-W-W-X-X-X-X
	   \ /
	    W-W-B
	   /
Y---G-W---W
 \ /   \
Y-Y     X-X-X-X

-> time goes this way ->
-------------