mirror of
https://github.com/git/git.git
synced 2024-12-13 20:06:31 +08:00
483bc4f045
Following what appears to be the predominant style, format
names of commands and commandlines both as `teletype text`.
While we're at it, add articles ("a" and "the") in some
places, italicize the name of the command in the manual page
synopsis line, and add a comma or two where it seems appropriate.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
286 lines
8.6 KiB
Plaintext
286 lines
8.6 KiB
Plaintext
git-bisect(1)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
git-bisect - Find the change that introduced a bug by binary search
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
'git bisect' <subcommand> <options>
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
The command takes various subcommands, and different options depending
|
|
on the subcommand:
|
|
|
|
git bisect help
|
|
git bisect start [<bad> [<good>...]] [--] [<paths>...]
|
|
git bisect bad [<rev>]
|
|
git bisect good [<rev>...]
|
|
git bisect skip [<rev>...]
|
|
git bisect reset [<branch>]
|
|
git bisect visualize
|
|
git bisect replay <logfile>
|
|
git bisect log
|
|
git bisect run <cmd>...
|
|
|
|
This command uses `git rev-list --bisect` to help drive the
|
|
binary search process to find which change introduced a bug, given an
|
|
old "good" commit object name and a later "bad" commit object name.
|
|
|
|
Getting help
|
|
~~~~~~~~~~~~
|
|
|
|
Use "git bisect" to get a short usage description, and "git bisect
|
|
help" or "git bisect -h" to get a long usage description.
|
|
|
|
Basic bisect commands: start, bad, good
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The way you use it is:
|
|
|
|
------------------------------------------------
|
|
$ git bisect start
|
|
$ git bisect bad # Current version is bad
|
|
$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
|
|
# tested that was good
|
|
------------------------------------------------
|
|
|
|
When you give at least one bad and one good versions, it will bisect
|
|
the revision tree and say something like:
|
|
|
|
------------------------------------------------
|
|
Bisecting: 675 revisions left to test after this
|
|
------------------------------------------------
|
|
|
|
and check out the state in the middle. Now, compile that kernel, and
|
|
boot it. Now, let's say that this booted kernel works fine, then just
|
|
do
|
|
|
|
------------------------------------------------
|
|
$ git bisect good # this one is good
|
|
------------------------------------------------
|
|
|
|
which will now say
|
|
|
|
------------------------------------------------
|
|
Bisecting: 337 revisions left to test after this
|
|
------------------------------------------------
|
|
|
|
and you continue along, compiling that one, testing it, and depending
|
|
on whether it is good or bad, you say "git bisect good" or "git bisect
|
|
bad", and ask for the next bisection.
|
|
|
|
Until you have no more left, and you'll have been left with the first
|
|
bad kernel rev in "refs/bisect/bad".
|
|
|
|
Bisect reset
|
|
~~~~~~~~~~~~
|
|
|
|
Oh, and then after you want to reset to the original head, do a
|
|
|
|
------------------------------------------------
|
|
$ git bisect reset
|
|
------------------------------------------------
|
|
|
|
to get back to the original branch, instead of being on the bisection
|
|
commit ("git bisect start" will do that for you too, actually: it will
|
|
reset the bisection state).
|
|
|
|
Bisect visualize
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
During the bisection process, you can say
|
|
|
|
------------
|
|
$ git bisect visualize
|
|
------------
|
|
|
|
to see the currently remaining suspects in `gitk`. `visualize` is a bit
|
|
too long to type and `view` is provided as a synonym.
|
|
|
|
If `DISPLAY` environment variable is not set, `git log` is used
|
|
instead. You can even give command line options such as `-p` and
|
|
`--stat`.
|
|
|
|
------------
|
|
$ git bisect view --stat
|
|
------------
|
|
|
|
Bisect log and bisect replay
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The good/bad input is logged, and
|
|
|
|
------------
|
|
$ git bisect log
|
|
------------
|
|
|
|
shows what you have done so far. You can truncate its output somewhere
|
|
and save it in a file, and run
|
|
|
|
------------
|
|
$ git bisect replay that-file
|
|
------------
|
|
|
|
if you find later you made a mistake telling good/bad about a
|
|
revision.
|
|
|
|
Avoiding to test a commit
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If in a middle of bisect session, you know what the bisect suggested
|
|
to try next is not a good one to test (e.g. the change the commit
|
|
introduces is known not to work in your environment and you know it
|
|
does not have anything to do with the bug you are chasing), you may
|
|
want to find a near-by commit and try that instead.
|
|
|
|
It goes something like this:
|
|
|
|
------------
|
|
$ git bisect good/bad # previous round was good/bad.
|
|
Bisecting: 337 revisions left to test after this
|
|
$ git bisect visualize # oops, that is uninteresting.
|
|
$ git reset --hard HEAD~3 # try 3 revs before what
|
|
# was suggested
|
|
------------
|
|
|
|
Then compile and test the one you chose to try. After that, tell
|
|
bisect what the result was as usual.
|
|
|
|
Bisect skip
|
|
~~~~~~~~~~~~
|
|
|
|
Instead of choosing by yourself a nearby commit, you may just want git
|
|
to do it for you using:
|
|
|
|
------------
|
|
$ git bisect skip # Current version cannot be tested
|
|
------------
|
|
|
|
But computing the commit to test may be slower afterwards and git may
|
|
eventually not be able to tell the first bad among a bad and one or
|
|
more "skip"ped commits.
|
|
|
|
Cutting down bisection by giving more parameters to bisect start
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can further cut down the number of trials if you know what part of
|
|
the tree is involved in the problem you are tracking down, by giving
|
|
paths parameters when you say `bisect start`, like this:
|
|
|
|
------------
|
|
$ git bisect start -- arch/i386 include/asm-i386
|
|
------------
|
|
|
|
If you know beforehand more than one good commits, you can narrow the
|
|
bisect space down without doing the whole tree checkout every time you
|
|
give good commits. You give the bad revision immediately after `start`
|
|
and then you give all the good revisions you have:
|
|
|
|
------------
|
|
$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
|
|
# v2.6.20-rc6 is bad
|
|
# v2.6.20-rc4 and v2.6.20-rc1 are good
|
|
------------
|
|
|
|
Bisect run
|
|
~~~~~~~~~~
|
|
|
|
If you have a script that can tell if the current source code is good
|
|
or bad, you can automatically bisect using:
|
|
|
|
------------
|
|
$ git bisect run my_script
|
|
------------
|
|
|
|
Note that the "run" script (`my_script` in the above example) should
|
|
exit with code 0 in case the current source code is good. Exit with a
|
|
code between 1 and 127 (inclusive), except 125, if the current
|
|
source code is bad.
|
|
|
|
Any other exit code will abort the automatic bisect process. (A
|
|
program that does "exit(-1)" leaves $? = 255, see exit(3) manual page,
|
|
the value is chopped with "& 0377".)
|
|
|
|
The special exit code 125 should be used when the current source code
|
|
cannot be tested. If the "run" script exits with this code, the current
|
|
revision will be skipped, see `git bisect skip` above.
|
|
|
|
You may often find that during bisect you want to have near-constant
|
|
tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
|
|
"revision that does not have this commit needs this patch applied to
|
|
work around other problem this bisection is not interested in")
|
|
applied to the revision being tested.
|
|
|
|
To cope with such a situation, after the inner `git-bisect` finds the
|
|
next revision to test, with the "run" script, you can apply that tweak
|
|
before compiling, run the real test, and after the test decides if the
|
|
revision (possibly with the needed tweaks) passed the test, rewind the
|
|
tree to the pristine state. Finally the "run" script can exit with
|
|
the status of the real test to let the "git bisect run" command loop to
|
|
determine the outcome.
|
|
|
|
EXAMPLES
|
|
--------
|
|
|
|
* Automatically bisect a broken build between v1.2 and HEAD:
|
|
+
|
|
------------
|
|
$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
|
|
$ git bisect run make # "make" builds the app
|
|
------------
|
|
|
|
* Automatically bisect a broken test suite:
|
|
+
|
|
------------
|
|
$ cat ~/test.sh
|
|
#!/bin/sh
|
|
make || exit 125 # this "skip"s broken builds
|
|
make test # "make test" runs the test suite
|
|
$ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good
|
|
$ git bisect run ~/test.sh
|
|
------------
|
|
+
|
|
Here we use a "test.sh" custom script. In this script, if "make"
|
|
fails, we "skip" the current commit.
|
|
+
|
|
It's safer to use a custom script outside the repo to prevent
|
|
interactions between the bisect, make and test processes and the
|
|
script.
|
|
+
|
|
And "make test" should "exit 0", if the test suite passes, and
|
|
"exit 1" (for example) otherwise.
|
|
|
|
* Automatically bisect a broken test case:
|
|
+
|
|
------------
|
|
$ cat ~/test.sh
|
|
#!/bin/sh
|
|
make || exit 125 # this "skip"s broken builds
|
|
~/check_test_case.sh # does the test case passes ?
|
|
$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
|
|
$ git bisect run ~/test.sh
|
|
------------
|
|
+
|
|
Here "check_test_case.sh" should "exit 0", if the test case passes,
|
|
and "exit 1" (for example) otherwise.
|
|
+
|
|
It's safer if both "test.sh" and "check_test_case.sh" scripts are
|
|
outside the repo to prevent interactions between the bisect, make and
|
|
test processes and the scripts.
|
|
|
|
Author
|
|
------
|
|
Written by Linus Torvalds <torvalds@osdl.org>
|
|
|
|
Documentation
|
|
-------------
|
|
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|