]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-bisect(1) |
2 | ============= | |
7fc9d69f JH |
3 | |
4 | NAME | |
5 | ---- | |
2df5a846 | 6 | git-bisect - Use binary search to find the commit 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 | |
06e6a745 MM |
19 | git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>] |
20 | [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] | |
3f05402a CC |
21 | git bisect (bad|new|<term-new>) [<rev>] |
22 | git bisect (good|old|<term-old>) [<rev>...] | |
21b55e33 | 23 | git bisect terms [--term-good | --term-bad] |
5413812f | 24 | git bisect skip [(<rev>|<range>)...] |
6b87ce23 | 25 | git bisect reset [<commit>] |
556cb4e5 JH |
26 | git bisect visualize |
27 | git bisect replay <logfile> | |
28 | git bisect log | |
a17c4101 | 29 | git bisect run <cmd>... |
2df5a846 | 30 | git bisect help |
556cb4e5 | 31 | |
2df5a846 MH |
32 | This command uses a binary search algorithm to find which commit in |
33 | your project's history introduced a bug. You use it by first telling | |
34 | it a "bad" commit that is known to contain the bug, and a "good" | |
35 | commit that is known to be before the bug was introduced. Then `git | |
36 | bisect` picks a commit between those two endpoints and asks you | |
37 | whether the selected commit is "good" or "bad". It continues narrowing | |
38 | down the range until it finds the exact commit that introduced the | |
39 | change. | |
7fc9d69f | 40 | |
21e5cfd8 AD |
41 | In fact, `git bisect` can be used to find the commit that changed |
42 | *any* property of your project; e.g., the commit that fixed a bug, or | |
43 | the commit that caused a benchmark's performance to improve. To | |
44 | support this more general usage, the terms "old" and "new" can be used | |
06e6a745 | 45 | in place of "good" and "bad", or you can choose your own terms. See |
21e5cfd8 AD |
46 | section "Alternate terms" below for more information. |
47 | ||
1207f9e7 CC |
48 | Basic bisect commands: start, bad, good |
49 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
50 | ||
2df5a846 MH |
51 | As an example, suppose you are trying to find the commit that broke a |
52 | feature that was known to work in version `v2.6.13-rc2` of your | |
53 | project. You start a bisect session as follows: | |
7fc9d69f | 54 | |
f85a4191 | 55 | ------------------------------------------------ |
556cb4e5 | 56 | $ git bisect start |
6cea0555 | 57 | $ git bisect bad # Current version is bad |
2df5a846 MH |
58 | $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good |
59 | ------------------------------------------------ | |
60 | ||
61 | Once you have specified at least one bad and one good commit, `git | |
62 | bisect` selects a commit in the middle of that range of history, | |
63 | checks it out, and outputs something similar to the following: | |
64 | ||
65 | ------------------------------------------------ | |
66 | Bisecting: 675 revisions left to test after this (roughly 10 steps) | |
f85a4191 | 67 | ------------------------------------------------ |
7fc9d69f | 68 | |
2df5a846 MH |
69 | You should now compile the checked-out version and test it. If that |
70 | version works correctly, type | |
f85a4191 JH |
71 | |
72 | ------------------------------------------------ | |
2df5a846 | 73 | $ git bisect good |
f85a4191 JH |
74 | ------------------------------------------------ |
75 | ||
2df5a846 | 76 | If that version is broken, type |
f85a4191 JH |
77 | |
78 | ------------------------------------------------ | |
2df5a846 | 79 | $ git bisect bad |
f85a4191 JH |
80 | ------------------------------------------------ |
81 | ||
2df5a846 | 82 | Then `git bisect` will respond with something like |
f85a4191 JH |
83 | |
84 | ------------------------------------------------ | |
2df5a846 | 85 | Bisecting: 337 revisions left to test after this (roughly 9 steps) |
f85a4191 JH |
86 | ------------------------------------------------ |
87 | ||
2df5a846 MH |
88 | Keep repeating the process: compile the tree, test it, and depending |
89 | on whether it is good or bad run `git bisect good` or `git bisect bad` | |
90 | to ask for the next commit that needs testing. | |
91 | ||
92 | Eventually there will be no more revisions left to inspect, and the | |
93 | command will print out a description of the first bad commit. The | |
94 | reference `refs/bisect/bad` will be left pointing at that commit. | |
f85a4191 | 95 | |
f85a4191 | 96 | |
1207f9e7 CC |
97 | Bisect reset |
98 | ~~~~~~~~~~~~ | |
99 | ||
6b87ce23 | 100 | After a bisect session, to clean up the bisection state and return to |
2df5a846 | 101 | the original HEAD, issue the following command: |
f85a4191 JH |
102 | |
103 | ------------------------------------------------ | |
556cb4e5 | 104 | $ git bisect reset |
f85a4191 JH |
105 | ------------------------------------------------ |
106 | ||
6b87ce23 AK |
107 | By default, this will return your tree to the commit that was checked |
108 | out before `git bisect start`. (A new `git bisect start` will also do | |
109 | that, as it cleans up the old bisection state.) | |
110 | ||
111 | With an optional argument, you can return to a different commit | |
112 | instead: | |
113 | ||
114 | ------------------------------------------------ | |
115 | $ git bisect reset <commit> | |
116 | ------------------------------------------------ | |
117 | ||
2df5a846 MH |
118 | For example, `git bisect reset bisect/bad` will check out the first |
119 | bad revision, while `git bisect reset HEAD` will leave you on the | |
120 | current bisection commit and avoid switching commits at all. | |
121 | ||
7fc9d69f | 122 | |
21e5cfd8 AD |
123 | Alternate terms |
124 | ~~~~~~~~~~~~~~~ | |
125 | ||
126 | Sometimes you are not looking for the commit that introduced a | |
127 | breakage, but rather for a commit that caused a change between some | |
128 | other "old" state and "new" state. For example, you might be looking | |
129 | for the commit that introduced a particular fix. Or you might be | |
130 | looking for the first commit in which the source-code filenames were | |
131 | finally all converted to your company's naming standard. Or whatever. | |
132 | ||
133 | In such cases it can be very confusing to use the terms "good" and | |
134 | "bad" to refer to "the state before the change" and "the state after | |
135 | the change". So instead, you can use the terms "old" and "new", | |
136 | respectively, in place of "good" and "bad". (But note that you cannot | |
137 | mix "good" and "bad" with "old" and "new" in a single session.) | |
138 | ||
139 | In this more general usage, you provide `git bisect` with a "new" | |
140 | commit has some property and an "old" commit that doesn't have that | |
141 | property. Each time `git bisect` checks out a commit, you test if that | |
142 | commit has the property. If it does, mark the commit as "new"; | |
143 | otherwise, mark it as "old". When the bisection is done, `git bisect` | |
144 | will report which commit introduced the property. | |
145 | ||
146 | To use "old" and "new" instead of "good" and bad, you must run `git | |
147 | bisect start` without commits as argument and then run the following | |
148 | commands to add the commits: | |
149 | ||
150 | ------------------------------------------------ | |
151 | git bisect old [<rev>] | |
152 | ------------------------------------------------ | |
153 | ||
154 | to indicate that a commit was before the sought change, or | |
155 | ||
156 | ------------------------------------------------ | |
157 | git bisect new [<rev>...] | |
158 | ------------------------------------------------ | |
159 | ||
160 | to indicate that it was after. | |
161 | ||
21b55e33 MM |
162 | To get a reminder of the currently used terms, use |
163 | ||
164 | ------------------------------------------------ | |
165 | git bisect terms | |
166 | ------------------------------------------------ | |
167 | ||
168 | You can get just the old (respectively new) term with `git bisect term | |
169 | --term-old` or `git bisect term --term-good`. | |
170 | ||
06e6a745 MM |
171 | If you would like to use your own terms instead of "bad"/"good" or |
172 | "new"/"old", you can choose any names you like (except existing bisect | |
173 | subcommands like `reset`, `start`, ...) by starting the | |
174 | bisection using | |
175 | ||
176 | ------------------------------------------------ | |
177 | git bisect start --term-old <term-old> --term-new <term-new> | |
178 | ------------------------------------------------ | |
179 | ||
180 | For example, if you are looking for a commit that introduced a | |
181 | performance regression, you might use | |
182 | ||
183 | ------------------------------------------------ | |
184 | git bisect start --term-old fast --term-new slow | |
185 | ------------------------------------------------ | |
186 | ||
187 | Or if you are looking for the commit that fixed a bug, you might use | |
188 | ||
189 | ------------------------------------------------ | |
190 | git bisect start --term-new fixed --term-old broken | |
191 | ------------------------------------------------ | |
192 | ||
193 | Then, use `git bisect <term-old>` and `git bisect <term-new>` instead | |
194 | of `git bisect good` and `git bisect bad` to mark commits. | |
195 | ||
1207f9e7 CC |
196 | Bisect visualize |
197 | ~~~~~~~~~~~~~~~~ | |
198 | ||
a42dea32 DM |
199 | To see the currently remaining suspects in 'gitk', issue the following |
200 | command during the bisection process: | |
8db9307c | 201 | |
556cb4e5 JH |
202 | ------------ |
203 | $ git bisect visualize | |
204 | ------------ | |
8db9307c | 205 | |
4306bcb4 | 206 | `view` may also be used as a synonym for `visualize`. |
235997c9 | 207 | |
23642591 | 208 | If the 'DISPLAY' environment variable is not set, 'git log' is used |
06ab60c0 | 209 | instead. You can also give command-line options such as `-p` and |
235997c9 JH |
210 | `--stat`. |
211 | ||
212 | ------------ | |
213 | $ git bisect view --stat | |
214 | ------------ | |
8db9307c | 215 | |
1207f9e7 CC |
216 | Bisect log and bisect replay |
217 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
218 | ||
a42dea32 | 219 | After having marked revisions as good or bad, issue the following |
4306bcb4 | 220 | command to show what has been done so far: |
fed820ad CC |
221 | |
222 | ------------ | |
223 | $ git bisect log | |
224 | ------------ | |
225 | ||
4306bcb4 DM |
226 | If you discover that you made a mistake in specifying the status of a |
227 | revision, you can save the output of this command to a file, edit it to | |
228 | remove the incorrect entries, and then issue the following commands to | |
229 | return to a corrected state: | |
b595ed14 | 230 | |
556cb4e5 | 231 | ------------ |
ee9cf14d | 232 | $ git bisect reset |
556cb4e5 JH |
233 | $ git bisect replay that-file |
234 | ------------ | |
b595ed14 | 235 | |
23642591 | 236 | Avoiding testing a commit |
1207f9e7 CC |
237 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
238 | ||
2df5a846 MH |
239 | If, in the middle of a bisect session, you know that the suggested |
240 | revision is not a good one to test (e.g. it fails to build and you | |
241 | know that the failure does not have anything to do with the bug you | |
242 | are chasing), you can manually select a nearby commit and test that | |
243 | one instead. | |
fed820ad | 244 | |
23642591 | 245 | For example: |
556cb4e5 JH |
246 | |
247 | ------------ | |
ee9cf14d | 248 | $ git bisect good/bad # previous round was good or bad. |
2df5a846 | 249 | Bisecting: 337 revisions left to test after this (roughly 9 steps) |
556cb4e5 | 250 | $ git bisect visualize # oops, that is uninteresting. |
23642591 | 251 | $ git reset --hard HEAD~3 # try 3 revisions before what |
556cb4e5 JH |
252 | # was suggested |
253 | ------------ | |
254 | ||
19fa5e8c | 255 | Then compile and test the chosen revision, and afterwards mark |
a42dea32 | 256 | the revision as good or bad in the usual manner. |
556cb4e5 | 257 | |
c39ce918 CC |
258 | Bisect skip |
259 | ~~~~~~~~~~~~ | |
260 | ||
2df5a846 MH |
261 | Instead of choosing a nearby commit by yourself, you can ask Git to do |
262 | it for you by issuing the command: | |
c39ce918 CC |
263 | |
264 | ------------ | |
265 | $ git bisect skip # Current version cannot be tested | |
266 | ------------ | |
267 | ||
2df5a846 MH |
268 | However, if you skip a commit adjacent to the one you are looking for, |
269 | Git will be unable to tell exactly which of those commits was the | |
270 | first bad one. | |
c39ce918 | 271 | |
2df5a846 MH |
272 | You can also skip a range of commits, instead of just one commit, |
273 | using range notation. For example: | |
5413812f CC |
274 | |
275 | ------------ | |
276 | $ git bisect skip v2.5..v2.6 | |
277 | ------------ | |
278 | ||
19fa5e8c DM |
279 | This tells the bisect process that no commit after `v2.5`, up to and |
280 | including `v2.6`, should be tested. | |
5413812f | 281 | |
23642591 DM |
282 | Note that if you also want to skip the first commit of the range you |
283 | would issue the command: | |
5413812f CC |
284 | |
285 | ------------ | |
286 | $ git bisect skip v2.5 v2.5..v2.6 | |
287 | ------------ | |
288 | ||
2df5a846 MH |
289 | This tells the bisect process that the commits between `v2.5` and |
290 | `v2.6` (inclusive) should be skipped. | |
4306bcb4 | 291 | |
5413812f | 292 | |
6fe9c570 CC |
293 | Cutting down bisection by giving more parameters to bisect start |
294 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1207f9e7 | 295 | |
23642591 DM |
296 | You can further cut down the number of trials, if you know what part of |
297 | the tree is involved in the problem you are tracking down, by specifying | |
4306bcb4 | 298 | path parameters when issuing the `bisect start` command: |
556cb4e5 JH |
299 | |
300 | ------------ | |
6fe9c570 CC |
301 | $ git bisect start -- arch/i386 include/asm-i386 |
302 | ------------ | |
303 | ||
23642591 DM |
304 | If you know beforehand more than one good commit, you can narrow the |
305 | bisect space down by specifying all of the good commits immediately after | |
306 | the bad commit when issuing the `bisect start` command: | |
6fe9c570 CC |
307 | |
308 | ------------ | |
309 | $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- | |
310 | # v2.6.20-rc6 is bad | |
311 | # v2.6.20-rc4 and v2.6.20-rc1 are good | |
556cb4e5 JH |
312 | ------------ |
313 | ||
1207f9e7 CC |
314 | Bisect run |
315 | ~~~~~~~~~~ | |
316 | ||
7891a281 | 317 | If you have a script that can tell if the current source code is good |
23642591 | 318 | or bad, you can bisect by issuing the command: |
a17c4101 CC |
319 | |
320 | ------------ | |
fad5c967 | 321 | $ git bisect run my_script arguments |
a17c4101 CC |
322 | ------------ |
323 | ||
2df5a846 MH |
324 | Note that the script (`my_script` in the above example) should exit |
325 | with code 0 if the current source code is good/old, and exit with a | |
326 | code between 1 and 127 (inclusive), except 125, if the current source | |
327 | code is bad/new. | |
a17c4101 | 328 | |
23642591 | 329 | Any other exit code will abort the bisect process. It should be noted |
2df5a846 MH |
330 | that a program that terminates via `exit(-1)` leaves $? = 255, (see the |
331 | exit(3) manual page), as the value is chopped with `& 0377`. | |
a17c4101 | 332 | |
71b0251c | 333 | The special exit code 125 should be used when the current source code |
23642591 | 334 | cannot be tested. If the script exits with this code, the current |
958bf6b7 JH |
335 | revision will be skipped (see `git bisect skip` above). 125 was chosen |
336 | as the highest sensible value to use for this purpose, because 126 and 127 | |
337 | are used by POSIX shells to signal specific error status (127 is for | |
338 | command not found, 126 is for command found but not executable---these | |
339 | details do not matter, as they are normal errors in the script, as far as | |
2df5a846 | 340 | `bisect run` is concerned). |
71b0251c | 341 | |
23642591 DM |
342 | You may often find that during a bisect session you want to have |
343 | temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a | |
344 | header file, or "revision that does not have this commit needs this | |
345 | patch applied to work around another problem this bisection is not | |
346 | interested in") applied to the revision being tested. | |
a17c4101 | 347 | |
5bcce849 | 348 | To cope with such a situation, after the inner 'git bisect' finds the |
23642591 DM |
349 | next revision to test, the script can apply the patch |
350 | before compiling, run the real test, and afterwards decide if the | |
351 | revision (possibly with the needed patch) passed the test and then | |
352 | rewind the tree to the pristine state. Finally the script should exit | |
2df5a846 | 353 | with the status of the real test to let the `git bisect run` command loop |
ee9cf14d | 354 | determine the eventual outcome of the bisect session. |
7fc9d69f | 355 | |
88d78911 JS |
356 | OPTIONS |
357 | ------- | |
358 | --no-checkout:: | |
359 | + | |
360 | Do not checkout the new working tree at each iteration of the bisection | |
361 | process. Instead just update a special reference named 'BISECT_HEAD' to make | |
362 | it point to the commit that should be tested. | |
363 | + | |
364 | This option may be useful when the test you would perform in each step | |
365 | does not require a checked out tree. | |
24c51280 JS |
366 | + |
367 | If the repository is bare, `--no-checkout` is assumed. | |
88d78911 | 368 | |
bac59f19 CC |
369 | EXAMPLES |
370 | -------- | |
371 | ||
372 | * Automatically bisect a broken build between v1.2 and HEAD: | |
373 | + | |
374 | ------------ | |
375 | $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good | |
376 | $ git bisect run make # "make" builds the app | |
c787a454 | 377 | $ git bisect reset # quit the bisect session |
bac59f19 CC |
378 | ------------ |
379 | ||
fad5c967 JT |
380 | * Automatically bisect a test failure between origin and HEAD: |
381 | + | |
382 | ------------ | |
383 | $ git bisect start HEAD origin -- # HEAD is bad, origin is good | |
384 | $ git bisect run make test # "make test" builds and tests | |
c787a454 | 385 | $ git bisect reset # quit the bisect session |
fad5c967 JT |
386 | ------------ |
387 | ||
bac59f19 | 388 | * Automatically bisect a broken test case: |
bac59f19 CC |
389 | + |
390 | ------------ | |
391 | $ cat ~/test.sh | |
392 | #!/bin/sh | |
23642591 | 393 | make || exit 125 # this skips broken builds |
9d79b7e9 | 394 | ~/check_test_case.sh # does the test case pass? |
bac59f19 | 395 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 |
bac59f19 | 396 | $ git bisect run ~/test.sh |
c787a454 | 397 | $ git bisect reset # quit the bisect session |
bac59f19 CC |
398 | ------------ |
399 | + | |
2df5a846 | 400 | Here we use a `test.sh` custom script. In this script, if `make` |
23642591 | 401 | fails, we skip the current commit. |
2df5a846 MH |
402 | `check_test_case.sh` should `exit 0` if the test case passes, |
403 | and `exit 1` otherwise. | |
bac59f19 | 404 | + |
2df5a846 | 405 | It is safer if both `test.sh` and `check_test_case.sh` are |
23642591 DM |
406 | outside the repository to prevent interactions between the bisect, |
407 | make and test processes and the scripts. | |
bac59f19 | 408 | |
e235b916 | 409 | * Automatically bisect with temporary modifications (hot-fix): |
bac59f19 CC |
410 | + |
411 | ------------ | |
412 | $ cat ~/test.sh | |
413 | #!/bin/sh | |
e235b916 MG |
414 | |
415 | # tweak the working tree by merging the hot-fix branch | |
416 | # and then attempt a build | |
417 | if git merge --no-commit hot-fix && | |
418 | make | |
419 | then | |
420 | # run project specific test and report its status | |
421 | ~/check_test_case.sh | |
422 | status=$? | |
423 | else | |
424 | # tell the caller this is untestable | |
425 | status=125 | |
426 | fi | |
427 | ||
428 | # undo the tweak to allow clean flipping to the next commit | |
429 | git reset --hard | |
430 | ||
431 | # return control | |
432 | exit $status | |
bac59f19 CC |
433 | ------------ |
434 | + | |
e235b916 MG |
435 | This applies modifications from a hot-fix branch before each test run, |
436 | e.g. in case your build or test environment changed so that older | |
437 | revisions may need a fix which newer ones have already. (Make sure the | |
438 | hot-fix branch is based off a commit which is contained in all revisions | |
439 | which you are bisecting, so that the merge does not pull in too much, or | |
440 | use `git cherry-pick` instead of `git merge`.) | |
bac59f19 | 441 | |
9d79b7e9 | 442 | * Automatically bisect a broken test case: |
fad5c967 JT |
443 | + |
444 | ------------ | |
445 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 | |
446 | $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" | |
c787a454 | 447 | $ git bisect reset # quit the bisect session |
fad5c967 JT |
448 | ------------ |
449 | + | |
9d79b7e9 MG |
450 | This shows that you can do without a run script if you write the test |
451 | on a single line. | |
fad5c967 | 452 | |
88d78911 JS |
453 | * Locate a good region of the object graph in a damaged repository |
454 | + | |
455 | ------------ | |
456 | $ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout | |
457 | $ git bisect run sh -c ' | |
458 | GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) && | |
459 | git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ && | |
460 | git pack-objects --stdout >/dev/null <tmp.$$ | |
461 | rc=$? | |
462 | rm -f tmp.$$ | |
463 | test $rc = 0' | |
464 | ||
c787a454 | 465 | $ git bisect reset # quit the bisect session |
88d78911 JS |
466 | ------------ |
467 | + | |
468 | In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that | |
469 | has at least one parent whose reachable graph is fully traversable in the sense | |
470 | required by 'git pack objects'. | |
471 | ||
21e5cfd8 AD |
472 | * Look for a fix instead of a regression in the code |
473 | + | |
474 | ------------ | |
475 | $ git bisect start | |
476 | $ git bisect new HEAD # current commit is marked as new | |
477 | $ git bisect old HEAD~10 # the tenth commit from now is marked as old | |
478 | ------------ | |
06e6a745 MM |
479 | + |
480 | or: | |
481 | ------------ | |
482 | $ git bisect start --term-old broken --term-new fixed | |
483 | $ git bisect fixed | |
484 | $ git bisect broken HEAD~10 | |
485 | ------------ | |
21e5cfd8 | 486 | |
c9493973 MM |
487 | Getting help |
488 | ~~~~~~~~~~~~ | |
489 | ||
490 | Use `git bisect` to get a short usage description, and `git bisect | |
491 | help` or `git bisect -h` to get a long usage description. | |
88d78911 | 492 | |
69a9cd31 CC |
493 | SEE ALSO |
494 | -------- | |
495 | link:git-bisect-lk2009.html[Fighting regressions with git bisect], | |
496 | linkgit:git-blame[1]. | |
497 | ||
7fc9d69f JH |
498 | GIT |
499 | --- | |
9e1f0a85 | 500 | Part of the linkgit:git[1] suite |