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