diff options
Diffstat (limited to 'Documentation/git-bisect.txt')
| -rw-r--r-- | Documentation/git-bisect.txt | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt new file mode 100644 index 0000000000..c7981efcd9 --- /dev/null +++ b/Documentation/git-bisect.txt @@ -0,0 +1,285 @@ +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 |