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
------