]>
Commit | Line | Data |
---|---|---|
1 | git-bisect(1) | |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-bisect - Find the change that introduced a bug by binary search | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
11 | 'git bisect' <subcommand> <options> | |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | The command takes various subcommands, and different options depending | |
16 | on the subcommand: | |
17 | ||
18 | git bisect start [<bad> [<good>...]] [--] [<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 | git bisect run <cmd>... | |
26 | ||
27 | This command uses 'git-rev-list --bisect' option to help drive the | |
28 | binary search process to find which change introduced a bug, given an | |
29 | old "good" commit object name and a later "bad" commit object name. | |
30 | ||
31 | Basic bisect commands: start, bad, good | |
32 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33 | ||
34 | The way you use it is: | |
35 | ||
36 | ------------------------------------------------ | |
37 | $ git bisect start | |
38 | $ git bisect bad # Current version is bad | |
39 | $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version | |
40 | # tested that was good | |
41 | ------------------------------------------------ | |
42 | ||
43 | When you give at least one bad and one good versions, it will bisect | |
44 | the revision tree and say something like: | |
45 | ||
46 | ------------------------------------------------ | |
47 | Bisecting: 675 revisions left to test after this | |
48 | ------------------------------------------------ | |
49 | ||
50 | and check out the state in the middle. Now, compile that kernel, and | |
51 | boot it. Now, let's say that this booted kernel works fine, then just | |
52 | do | |
53 | ||
54 | ------------------------------------------------ | |
55 | $ git bisect good # this one is good | |
56 | ------------------------------------------------ | |
57 | ||
58 | which will now say | |
59 | ||
60 | ------------------------------------------------ | |
61 | Bisecting: 337 revisions left to test after this | |
62 | ------------------------------------------------ | |
63 | ||
64 | and you continue along, compiling that one, testing it, and depending | |
65 | on whether it is good or bad, you say "git bisect good" or "git bisect | |
66 | bad", and ask for the next bisection. | |
67 | ||
68 | Until you have no more left, and you'll have been left with the first | |
69 | bad kernel rev in "refs/bisect/bad". | |
70 | ||
71 | Bisect reset | |
72 | ~~~~~~~~~~~~ | |
73 | ||
74 | Oh, and then after you want to reset to the original head, do a | |
75 | ||
76 | ------------------------------------------------ | |
77 | $ git bisect reset | |
78 | ------------------------------------------------ | |
79 | ||
80 | to get back to the master branch, instead of being in one of the | |
81 | bisection branches ("git bisect start" will do that for you too, | |
82 | actually: it will reset the bisection state, and before it does that | |
83 | it checks that you're not using some old bisection branch). | |
84 | ||
85 | Bisect visualize | |
86 | ~~~~~~~~~~~~~~~~ | |
87 | ||
88 | During the bisection process, you can say | |
89 | ||
90 | ------------ | |
91 | $ git bisect visualize | |
92 | ------------ | |
93 | ||
94 | to see the currently remaining suspects in `gitk`. | |
95 | ||
96 | Bisect log and bisect replay | |
97 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
98 | ||
99 | The good/bad input is logged, and | |
100 | ||
101 | ------------ | |
102 | $ git bisect log | |
103 | ------------ | |
104 | ||
105 | shows what you have done so far. You can truncate its output somewhere | |
106 | and save it in a file, and run | |
107 | ||
108 | ------------ | |
109 | $ git bisect replay that-file | |
110 | ------------ | |
111 | ||
112 | if you find later you made a mistake telling good/bad about a | |
113 | revision. | |
114 | ||
115 | Avoiding to test a commit | |
116 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
117 | ||
118 | If in a middle of bisect session, you know what the bisect suggested | |
119 | to try next is not a good one to test (e.g. the change the commit | |
120 | introduces is known not to work in your environment and you know it | |
121 | does not have anything to do with the bug you are chasing), you may | |
122 | want to find a near-by commit and try that instead. | |
123 | ||
124 | It goes something like this: | |
125 | ||
126 | ------------ | |
127 | $ git bisect good/bad # previous round was good/bad. | |
128 | Bisecting: 337 revisions left to test after this | |
129 | $ git bisect visualize # oops, that is uninteresting. | |
130 | $ git reset --hard HEAD~3 # try 3 revs before what | |
131 | # was suggested | |
132 | ------------ | |
133 | ||
134 | Then compile and test the one you chose to try. After that, tell | |
135 | bisect what the result was as usual. | |
136 | ||
137 | Cutting down bisection by giving more parameters to bisect start | |
138 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
139 | ||
140 | You can further cut down the number of trials if you know what part of | |
141 | the tree is involved in the problem you are tracking down, by giving | |
142 | paths parameters when you say `bisect start`, like this: | |
143 | ||
144 | ------------ | |
145 | $ git bisect start -- arch/i386 include/asm-i386 | |
146 | ------------ | |
147 | ||
148 | If you know beforehand more than one good commits, you can narrow the | |
149 | bisect space down without doing the whole tree checkout every time you | |
150 | give good commits. You give the bad revision immediately after `start` | |
151 | and then you give all the good revisions you have: | |
152 | ||
153 | ------------ | |
154 | $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- | |
155 | # v2.6.20-rc6 is bad | |
156 | # v2.6.20-rc4 and v2.6.20-rc1 are good | |
157 | ------------ | |
158 | ||
159 | Bisect run | |
160 | ~~~~~~~~~~ | |
161 | ||
162 | If you have a script that can tell if the current source code is good | |
163 | or bad, you can automatically bisect using: | |
164 | ||
165 | ------------ | |
166 | $ git bisect run my_script | |
167 | ------------ | |
168 | ||
169 | Note that the "run" script (`my_script` in the above example) should | |
170 | exit with code 0 in case the current source code is good and with a | |
171 | code between 1 and 127 (included) in case the current source code is | |
172 | bad. | |
173 | ||
174 | Any other exit code will abort the automatic bisect process. (A | |
175 | program that does "exit(-1)" leaves $? = 255, see exit(3) manual page, | |
176 | the value is chopped with "& 0377".) | |
177 | ||
178 | You may often find that during bisect you want to have near-constant | |
179 | tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or | |
180 | "revision that does not have this commit needs this patch applied to | |
181 | work around other problem this bisection is not interested in") | |
182 | applied to the revision being tested. | |
183 | ||
184 | To cope with such a situation, after the inner git-bisect finds the | |
185 | next revision to test, with the "run" script, you can apply that tweak | |
186 | before compiling, run the real test, and after the test decides if the | |
187 | revision (possibly with the needed tweaks) passed the test, rewind the | |
188 | tree to the pristine state. Finally the "run" script can exit with | |
189 | the status of the real test to let "git bisect run" command loop to | |
190 | know the outcome. | |
191 | ||
192 | Author | |
193 | ------ | |
194 | Written by Linus Torvalds <torvalds@osdl.org> | |
195 | ||
196 | Documentation | |
197 | ------------- | |
198 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
199 | ||
200 | GIT | |
201 | --- | |
202 | Part of the gitlink:git[7] suite |