From 556cb4e583ada79b7c2e632a548dca90a98c1b29 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 5 Dec 2005 00:15:24 -0800 Subject: Documentation: talk about pathspec in bisect. Also work-around asciidoc manpage trouble that does not seem to allow more than one line in the SYNOPSIS section. Signed-off-by: Junio C Hamano diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 8a39970..ac4b496 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -8,16 +8,21 @@ git-bisect - Find the change that introduced a bug SYNOPSIS -------- - 'git bisect' start - 'git bisect' bad - 'git bisect' good - 'git bisect' reset [] - 'git bisect' visualize - 'git bisect' replay - 'git bisect' log +'git bisect' DESCRIPTION ----------- +The command takes various subcommands, and different options +depending on the subcommand: + + git bisect start [...] + git bisect bad + git bisect good + git bisect reset [] + git bisect visualize + git bisect replay + 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 @@ -26,10 +31,10 @@ 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 +$ 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 @@ -43,7 +48,7 @@ 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 +$ git bisect good # this one is good ------------------------------------------------ which will now say @@ -62,7 +67,7 @@ kernel rev in "refs/bisect/bad". Oh, and then after you want to reset to the original head, do a ------------------------------------------------ -git bisect reset +$ git bisect reset ------------------------------------------------ to get back to the master branch, instead of being in one of the bisection @@ -72,7 +77,9 @@ not using some old bisection branch). During the bisection process, you can say - git bisect visualize +------------ +$ git bisect visualize +------------ to see the currently remaining suspects in `gitk`. @@ -80,11 +87,40 @@ 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 +------------ +$ 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 ------ -- cgit v0.10.2-6-g49f6