@matheusbsbs / matheus-bagliano / commits / 556cb4e583
Fork 0

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 <junkio@cox.net>

Junio C Hamano committed Dec 5, 2005 at 00:15 UTC 556cb4e583ada79b7c2e632a548dca90a98c1b29
1 file changed +51 -15
Documentation/git-bisect.txt
+51 -15
@@ -8,16 +8,21 @@ git-bisect - Find the change that introduced a bug
8
9 SYNOPSIS
10 --------
11 - 'git bisect' start
12 - 'git bisect' bad <rev>
13 - 'git bisect' good <rev>
14 - 'git bisect' reset [<branch>]
15 - 'git bisect' visualize
16 - 'git bisect' replay <logfile>
17 - 'git bisect' log
11 +'git bisect' <subcommand> <options>
12
13 DESCRIPTION
14 -----------
15 +The command takes various subcommands, and different options
16 +depending on the subcommand:
17 +
18 + git bisect start [<paths>...]
19 + git bisect bad <rev>
20 + git bisect good <rev>
21 + git bisect reset [<branch>]
22 + git bisect visualize
23 + git bisect replay <logfile>
24 + git bisect log
25 +
26 This command uses 'git-rev-list --bisect' option to help drive
27 the binary search process to find which change introduced a bug,
28 given an old "good" commit object name and a later "bad" commit
@@ -26,10 +31,10 @@ object name.
31 The way you use it is:
32
33 ------------------------------------------------
29 -git bisect start
30 -git bisect bad # Current version is bad
31 -git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
32 - # tested that was good
34 +$ git bisect start
35 +$ git bisect bad # Current version is bad
36 +$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
37 + # tested that was good
38 ------------------------------------------------
39
40 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
48 it. Now, let's say that this booted kernel works fine, then just do
49
50 ------------------------------------------------
46 -git bisect good # this one is good
51 +$ git bisect good # this one is good
52 ------------------------------------------------
53
54 which will now say
@@ -62,7 +67,7 @@ kernel rev in "refs/bisect/bad".
67 Oh, and then after you want to reset to the original head, do a
68
69 ------------------------------------------------
65 -git bisect reset
70 +$ git bisect reset
71 ------------------------------------------------
72
73 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).
77
78 During the bisection process, you can say
79
75 - git bisect visualize
80 +------------
81 +$ git bisect visualize
82 +------------
83
84 to see the currently remaining suspects in `gitk`.
85
@@ -80,11 +87,40 @@ The good/bad input is logged, and `git bisect
87 log` shows what you have done so far. You can truncate its
88 output somewhere and save it in a file, and run
89
83 - git bisect replay that-file
90 +------------
91 +$ git bisect replay that-file
92 +------------
93
94 if you find later you made a mistake telling good/bad about a
95 revision.
96
97 +If in a middle of bisect session, you know what the bisect
98 +suggested to try next is not a good one to test (e.g. the change
99 +the commit introduces is known not to work in your environment
100 +and you know it does not have anything to do with the bug you
101 +are chasing), you may want to find a near-by commit and try that
102 +instead. It goes something like this:
103 +
104 +------------
105 +$ git bisect good/bad # previous round was good/bad.
106 +Bisecting: 337 revisions left to test after this
107 +$ git bisect visualize # oops, that is uninteresting.
108 +$ git reset --hard HEAD~3 # try 3 revs before what
109 + # was suggested
110 +------------
111 +
112 +Then compile and test the one you chose to try. After that,
113 +tell bisect what the result was as usual.
114 +
115 +You can further cut down the number of trials if you know what
116 +part of the tree is involved in the problem you are tracking
117 +down, by giving paths parameters when you say `bisect start`,
118 +like this:
119 +
120 +------------
121 +$ git bisect start arch/i386 include/asm-i386
122 +------------
123 +
124
125 Author
126 ------