diff options
Diffstat (limited to 'Documentation/git-bisect.txt')
| -rw-r--r-- | Documentation/git-bisect.txt | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt new file mode 100644 index 0000000000..16ec7269b2 --- /dev/null +++ b/Documentation/git-bisect.txt @@ -0,0 +1,136 @@ +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 start [<paths>...] + git bisect bad <rev> + git bisect good <rev> + git bisect reset [<branch>] + git bisect visualize + git bisect replay <logfile> + git bisect log + +This command uses 'git-rev-list --bisect' option 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. + +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". + +Oh, and then after you want to reset to the original head, do a + +------------------------------------------------ +$ git bisect reset +------------------------------------------------ + +to get back to the master branch, instead of being in one of the bisection +branches ("git bisect start" will do that for you too, actually: it will +reset the bisection state, and before it does that it checks that you're +not using some old bisection branch). + +During the bisection process, you can say + +------------ +$ git bisect visualize +------------ + +to see the currently remaining suspects in `gitk`. + +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. + +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. + +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 +------------ + + +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 gitlink:git[7] suite + |