]>
Commit | Line | Data |
---|---|---|
1 | git-bisect(1) | |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-bisect - Find by binary search the change that introduced a bug | |
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 help | |
19 | git bisect start [<bad> [<good>...]] [--] [<paths>...] | |
20 | git bisect bad [<rev>] | |
21 | git bisect good [<rev>...] | |
22 | git bisect skip [(<rev>|<range>)...] | |
23 | git bisect reset [<commit>] | |
24 | git bisect visualize | |
25 | git bisect replay <logfile> | |
26 | git bisect log | |
27 | git bisect run <cmd>... | |
28 | ||
29 | This command uses 'git rev-list --bisect' to help drive the | |
30 | binary search process to find which change introduced a bug, given an | |
31 | old "good" commit object name and a later "bad" commit object name. | |
32 | ||
33 | Getting help | |
34 | ~~~~~~~~~~~~ | |
35 | ||
36 | Use "git bisect" to get a short usage description, and "git bisect | |
37 | help" or "git bisect -h" to get a long usage description. | |
38 | ||
39 | Basic bisect commands: start, bad, good | |
40 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
41 | ||
42 | Using the Linux kernel tree as an example, basic use of the bisect | |
43 | command is as follows: | |
44 | ||
45 | ------------------------------------------------ | |
46 | $ git bisect start | |
47 | $ git bisect bad # Current version is bad | |
48 | $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version | |
49 | # tested that was good | |
50 | ------------------------------------------------ | |
51 | ||
52 | When you have specified at least one bad and one good version, the | |
53 | command bisects the revision tree and outputs something similar to | |
54 | the following: | |
55 | ||
56 | ------------------------------------------------ | |
57 | Bisecting: 675 revisions left to test after this | |
58 | ------------------------------------------------ | |
59 | ||
60 | The state in the middle of the set of revisions is then checked out. | |
61 | You would now compile that kernel and boot it. If the booted kernel | |
62 | works correctly, you would then issue the following command: | |
63 | ||
64 | ------------------------------------------------ | |
65 | $ git bisect good # this one is good | |
66 | ------------------------------------------------ | |
67 | ||
68 | The output of this command would be something similar to the following: | |
69 | ||
70 | ------------------------------------------------ | |
71 | Bisecting: 337 revisions left to test after this | |
72 | ------------------------------------------------ | |
73 | ||
74 | You keep repeating this process, compiling the tree, testing it, and | |
75 | depending on whether it is good or bad issuing the command "git bisect good" | |
76 | or "git bisect bad" to ask for the next bisection. | |
77 | ||
78 | Eventually there will be no more revisions left to bisect, and you | |
79 | will have been left with the first bad kernel revision in "refs/bisect/bad". | |
80 | ||
81 | Bisect reset | |
82 | ~~~~~~~~~~~~ | |
83 | ||
84 | After a bisect session, to clean up the bisection state and return to | |
85 | the original HEAD, issue the following command: | |
86 | ||
87 | ------------------------------------------------ | |
88 | $ git bisect reset | |
89 | ------------------------------------------------ | |
90 | ||
91 | By default, this will return your tree to the commit that was checked | |
92 | out before `git bisect start`. (A new `git bisect start` will also do | |
93 | that, as it cleans up the old bisection state.) | |
94 | ||
95 | With an optional argument, you can return to a different commit | |
96 | instead: | |
97 | ||
98 | ------------------------------------------------ | |
99 | $ git bisect reset <commit> | |
100 | ------------------------------------------------ | |
101 | ||
102 | For example, `git bisect reset HEAD` will leave you on the current | |
103 | bisection commit and avoid switching commits at all, while `git bisect | |
104 | reset bisect/bad` will check out the first bad revision. | |
105 | ||
106 | Bisect visualize | |
107 | ~~~~~~~~~~~~~~~~ | |
108 | ||
109 | To see the currently remaining suspects in 'gitk', issue the following | |
110 | command during the bisection process: | |
111 | ||
112 | ------------ | |
113 | $ git bisect visualize | |
114 | ------------ | |
115 | ||
116 | `view` may also be used as a synonym for `visualize`. | |
117 | ||
118 | If the 'DISPLAY' environment variable is not set, 'git log' is used | |
119 | instead. You can also give command line options such as `-p` and | |
120 | `--stat`. | |
121 | ||
122 | ------------ | |
123 | $ git bisect view --stat | |
124 | ------------ | |
125 | ||
126 | Bisect log and bisect replay | |
127 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
128 | ||
129 | After having marked revisions as good or bad, issue the following | |
130 | command to show what has been done so far: | |
131 | ||
132 | ------------ | |
133 | $ git bisect log | |
134 | ------------ | |
135 | ||
136 | If you discover that you made a mistake in specifying the status of a | |
137 | revision, you can save the output of this command to a file, edit it to | |
138 | remove the incorrect entries, and then issue the following commands to | |
139 | return to a corrected state: | |
140 | ||
141 | ------------ | |
142 | $ git bisect reset | |
143 | $ git bisect replay that-file | |
144 | ------------ | |
145 | ||
146 | Avoiding testing a commit | |
147 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
148 | ||
149 | If, in the middle of a bisect session, you know that the next suggested | |
150 | revision is not a good one to test (e.g. the change the commit | |
151 | introduces is known not to work in your environment and you know it | |
152 | does not have anything to do with the bug you are chasing), you may | |
153 | want to find a nearby commit and try that instead. | |
154 | ||
155 | For example: | |
156 | ||
157 | ------------ | |
158 | $ git bisect good/bad # previous round was good or bad. | |
159 | Bisecting: 337 revisions left to test after this | |
160 | $ git bisect visualize # oops, that is uninteresting. | |
161 | $ git reset --hard HEAD~3 # try 3 revisions before what | |
162 | # was suggested | |
163 | ------------ | |
164 | ||
165 | Then compile and test the chosen revision, and afterwards mark | |
166 | the revision as good or bad in the usual manner. | |
167 | ||
168 | Bisect skip | |
169 | ~~~~~~~~~~~~ | |
170 | ||
171 | Instead of choosing by yourself a nearby commit, you can ask git | |
172 | to do it for you by issuing the command: | |
173 | ||
174 | ------------ | |
175 | $ git bisect skip # Current version cannot be tested | |
176 | ------------ | |
177 | ||
178 | But git may eventually be unable to tell the first bad commit among | |
179 | a bad commit and one or more skipped commits. | |
180 | ||
181 | You can even skip a range of commits, instead of just one commit, | |
182 | using the "'<commit1>'..'<commit2>'" notation. For example: | |
183 | ||
184 | ------------ | |
185 | $ git bisect skip v2.5..v2.6 | |
186 | ------------ | |
187 | ||
188 | This tells the bisect process that no commit after `v2.5`, up to and | |
189 | including `v2.6`, should be tested. | |
190 | ||
191 | Note that if you also want to skip the first commit of the range you | |
192 | would issue the command: | |
193 | ||
194 | ------------ | |
195 | $ git bisect skip v2.5 v2.5..v2.6 | |
196 | ------------ | |
197 | ||
198 | This tells the bisect process that the commits between `v2.5` included | |
199 | and `v2.6` included should be skipped. | |
200 | ||
201 | ||
202 | Cutting down bisection by giving more parameters to bisect start | |
203 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
204 | ||
205 | You can further cut down the number of trials, if you know what part of | |
206 | the tree is involved in the problem you are tracking down, by specifying | |
207 | path parameters when issuing the `bisect start` command: | |
208 | ||
209 | ------------ | |
210 | $ git bisect start -- arch/i386 include/asm-i386 | |
211 | ------------ | |
212 | ||
213 | If you know beforehand more than one good commit, you can narrow the | |
214 | bisect space down by specifying all of the good commits immediately after | |
215 | the bad commit when issuing the `bisect start` command: | |
216 | ||
217 | ------------ | |
218 | $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- | |
219 | # v2.6.20-rc6 is bad | |
220 | # v2.6.20-rc4 and v2.6.20-rc1 are good | |
221 | ------------ | |
222 | ||
223 | Bisect run | |
224 | ~~~~~~~~~~ | |
225 | ||
226 | If you have a script that can tell if the current source code is good | |
227 | or bad, you can bisect by issuing the command: | |
228 | ||
229 | ------------ | |
230 | $ git bisect run my_script arguments | |
231 | ------------ | |
232 | ||
233 | Note that the script (`my_script` in the above example) should | |
234 | exit with code 0 if the current source code is good, and exit with a | |
235 | code between 1 and 127 (inclusive), except 125, if the current | |
236 | source code is bad. | |
237 | ||
238 | Any other exit code will abort the bisect process. It should be noted | |
239 | that a program that terminates via "exit(-1)" leaves $? = 255, (see the | |
240 | exit(3) manual page), as the value is chopped with "& 0377". | |
241 | ||
242 | The special exit code 125 should be used when the current source code | |
243 | cannot be tested. If the script exits with this code, the current | |
244 | revision will be skipped (see `git bisect skip` above). 125 was chosen | |
245 | as the highest sensible value to use for this purpose, because 126 and 127 | |
246 | are used by POSIX shells to signal specific error status (127 is for | |
247 | command not found, 126 is for command found but not executable---these | |
248 | details do not matter, as they are normal errors in the script, as far as | |
249 | "bisect run" is concerned). | |
250 | ||
251 | You may often find that during a bisect session you want to have | |
252 | temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a | |
253 | header file, or "revision that does not have this commit needs this | |
254 | patch applied to work around another problem this bisection is not | |
255 | interested in") applied to the revision being tested. | |
256 | ||
257 | To cope with such a situation, after the inner 'git bisect' finds the | |
258 | next revision to test, the script can apply the patch | |
259 | before compiling, run the real test, and afterwards decide if the | |
260 | revision (possibly with the needed patch) passed the test and then | |
261 | rewind the tree to the pristine state. Finally the script should exit | |
262 | with the status of the real test to let the "git bisect run" command loop | |
263 | determine the eventual outcome of the bisect session. | |
264 | ||
265 | EXAMPLES | |
266 | -------- | |
267 | ||
268 | * Automatically bisect a broken build between v1.2 and HEAD: | |
269 | + | |
270 | ------------ | |
271 | $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good | |
272 | $ git bisect run make # "make" builds the app | |
273 | ------------ | |
274 | ||
275 | * Automatically bisect a test failure between origin and HEAD: | |
276 | + | |
277 | ------------ | |
278 | $ git bisect start HEAD origin -- # HEAD is bad, origin is good | |
279 | $ git bisect run make test # "make test" builds and tests | |
280 | ------------ | |
281 | ||
282 | * Automatically bisect a broken test case: | |
283 | + | |
284 | ------------ | |
285 | $ cat ~/test.sh | |
286 | #!/bin/sh | |
287 | make || exit 125 # this skips broken builds | |
288 | ~/check_test_case.sh # does the test case pass? | |
289 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 | |
290 | $ git bisect run ~/test.sh | |
291 | ------------ | |
292 | + | |
293 | Here we use a "test.sh" custom script. In this script, if "make" | |
294 | fails, we skip the current commit. | |
295 | "check_test_case.sh" should "exit 0" if the test case passes, | |
296 | and "exit 1" otherwise. | |
297 | + | |
298 | It is safer if both "test.sh" and "check_test_case.sh" are | |
299 | outside the repository to prevent interactions between the bisect, | |
300 | make and test processes and the scripts. | |
301 | ||
302 | * Automatically bisect with temporary modifications (hot-fix): | |
303 | + | |
304 | ------------ | |
305 | $ cat ~/test.sh | |
306 | #!/bin/sh | |
307 | ||
308 | # tweak the working tree by merging the hot-fix branch | |
309 | # and then attempt a build | |
310 | if git merge --no-commit hot-fix && | |
311 | make | |
312 | then | |
313 | # run project specific test and report its status | |
314 | ~/check_test_case.sh | |
315 | status=$? | |
316 | else | |
317 | # tell the caller this is untestable | |
318 | status=125 | |
319 | fi | |
320 | ||
321 | # undo the tweak to allow clean flipping to the next commit | |
322 | git reset --hard | |
323 | ||
324 | # return control | |
325 | exit $status | |
326 | ------------ | |
327 | + | |
328 | This applies modifications from a hot-fix branch before each test run, | |
329 | e.g. in case your build or test environment changed so that older | |
330 | revisions may need a fix which newer ones have already. (Make sure the | |
331 | hot-fix branch is based off a commit which is contained in all revisions | |
332 | which you are bisecting, so that the merge does not pull in too much, or | |
333 | use `git cherry-pick` instead of `git merge`.) | |
334 | ||
335 | * Automatically bisect a broken test case: | |
336 | + | |
337 | ------------ | |
338 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 | |
339 | $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" | |
340 | ------------ | |
341 | + | |
342 | This shows that you can do without a run script if you write the test | |
343 | on a single line. | |
344 | ||
345 | Author | |
346 | ------ | |
347 | Written by Linus Torvalds <torvalds@osdl.org> | |
348 | ||
349 | Documentation | |
350 | ------------- | |
351 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
352 | ||
353 | SEE ALSO | |
354 | -------- | |
355 | link:git-bisect-lk2009.html[Fighting regressions with git bisect], | |
356 | linkgit:git-blame[1]. | |
357 | ||
358 | GIT | |
359 | --- | |
360 | Part of the linkgit:git[1] suite |