]>
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>] |
dbc349bb | 26 | git bisect (visualize|view) |
556cb4e5 JH |
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" | |
60b091c6 | 140 | commit that has some property and an "old" commit that doesn't have that |
21e5cfd8 AD |
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 | ||
bbd374dd AK |
168 | You can get just the old (respectively new) term with `git bisect terms |
169 | --term-old` or `git bisect terms --term-good`. | |
21b55e33 | 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 | ||
dbc349bb RD |
196 | Bisect visualize/view |
197 | ~~~~~~~~~~~~~~~~~~~~~ | |
1207f9e7 | 198 | |
a42dea32 | 199 | To see the currently remaining suspects in 'gitk', issue the following |
dbc349bb RD |
200 | command during the bisection process (the subcommand `view` can be used |
201 | as an alternative to `visualize`): | |
8db9307c | 202 | |
556cb4e5 JH |
203 | ------------ |
204 | $ git bisect visualize | |
205 | ------------ | |
8db9307c | 206 | |
47d81b5c | 207 | If the `DISPLAY` environment variable is not set, 'git log' is used |
06ab60c0 | 208 | instead. You can also give command-line options such as `-p` and |
235997c9 JH |
209 | `--stat`. |
210 | ||
211 | ------------ | |
dbc349bb | 212 | $ git bisect visualize --stat |
235997c9 | 213 | ------------ |
8db9307c | 214 | |
1207f9e7 CC |
215 | Bisect log and bisect replay |
216 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
217 | ||
a42dea32 | 218 | After having marked revisions as good or bad, issue the following |
4306bcb4 | 219 | command to show what has been done so far: |
fed820ad CC |
220 | |
221 | ------------ | |
222 | $ git bisect log | |
223 | ------------ | |
224 | ||
4306bcb4 DM |
225 | If you discover that you made a mistake in specifying the status of a |
226 | revision, you can save the output of this command to a file, edit it to | |
227 | remove the incorrect entries, and then issue the following commands to | |
228 | return to a corrected state: | |
b595ed14 | 229 | |
556cb4e5 | 230 | ------------ |
ee9cf14d | 231 | $ git bisect reset |
556cb4e5 JH |
232 | $ git bisect replay that-file |
233 | ------------ | |
b595ed14 | 234 | |
23642591 | 235 | Avoiding testing a commit |
1207f9e7 CC |
236 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
237 | ||
2df5a846 MH |
238 | If, in the middle of a bisect session, you know that the suggested |
239 | revision is not a good one to test (e.g. it fails to build and you | |
240 | know that the failure does not have anything to do with the bug you | |
241 | are chasing), you can manually select a nearby commit and test that | |
242 | one instead. | |
fed820ad | 243 | |
23642591 | 244 | For example: |
556cb4e5 JH |
245 | |
246 | ------------ | |
ee9cf14d | 247 | $ git bisect good/bad # previous round was good or bad. |
2df5a846 | 248 | Bisecting: 337 revisions left to test after this (roughly 9 steps) |
556cb4e5 | 249 | $ git bisect visualize # oops, that is uninteresting. |
23642591 | 250 | $ git reset --hard HEAD~3 # try 3 revisions before what |
556cb4e5 JH |
251 | # was suggested |
252 | ------------ | |
253 | ||
19fa5e8c | 254 | Then compile and test the chosen revision, and afterwards mark |
a42dea32 | 255 | the revision as good or bad in the usual manner. |
556cb4e5 | 256 | |
c39ce918 | 257 | Bisect skip |
142d035a | 258 | ~~~~~~~~~~~ |
c39ce918 | 259 | |
2df5a846 MH |
260 | Instead of choosing a nearby commit by yourself, you can ask Git to do |
261 | it for you by issuing the command: | |
c39ce918 CC |
262 | |
263 | ------------ | |
264 | $ git bisect skip # Current version cannot be tested | |
265 | ------------ | |
266 | ||
2df5a846 MH |
267 | However, if you skip a commit adjacent to the one you are looking for, |
268 | Git will be unable to tell exactly which of those commits was the | |
269 | first bad one. | |
c39ce918 | 270 | |
2df5a846 MH |
271 | You can also skip a range of commits, instead of just one commit, |
272 | using range notation. For example: | |
5413812f CC |
273 | |
274 | ------------ | |
275 | $ git bisect skip v2.5..v2.6 | |
276 | ------------ | |
277 | ||
19fa5e8c DM |
278 | This tells the bisect process that no commit after `v2.5`, up to and |
279 | including `v2.6`, should be tested. | |
5413812f | 280 | |
23642591 DM |
281 | Note that if you also want to skip the first commit of the range you |
282 | would issue the command: | |
5413812f CC |
283 | |
284 | ------------ | |
285 | $ git bisect skip v2.5 v2.5..v2.6 | |
286 | ------------ | |
287 | ||
2df5a846 MH |
288 | This tells the bisect process that the commits between `v2.5` and |
289 | `v2.6` (inclusive) should be skipped. | |
4306bcb4 | 290 | |
5413812f | 291 | |
6fe9c570 CC |
292 | Cutting down bisection by giving more parameters to bisect start |
293 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1207f9e7 | 294 | |
23642591 DM |
295 | You can further cut down the number of trials, if you know what part of |
296 | the tree is involved in the problem you are tracking down, by specifying | |
4306bcb4 | 297 | path parameters when issuing the `bisect start` command: |
556cb4e5 JH |
298 | |
299 | ------------ | |
6fe9c570 CC |
300 | $ git bisect start -- arch/i386 include/asm-i386 |
301 | ------------ | |
302 | ||
23642591 DM |
303 | If you know beforehand more than one good commit, you can narrow the |
304 | bisect space down by specifying all of the good commits immediately after | |
305 | the bad commit when issuing the `bisect start` command: | |
6fe9c570 CC |
306 | |
307 | ------------ | |
308 | $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- | |
309 | # v2.6.20-rc6 is bad | |
310 | # v2.6.20-rc4 and v2.6.20-rc1 are good | |
556cb4e5 JH |
311 | ------------ |
312 | ||
1207f9e7 CC |
313 | Bisect run |
314 | ~~~~~~~~~~ | |
315 | ||
7891a281 | 316 | If you have a script that can tell if the current source code is good |
23642591 | 317 | or bad, you can bisect by issuing the command: |
a17c4101 CC |
318 | |
319 | ------------ | |
fad5c967 | 320 | $ git bisect run my_script arguments |
a17c4101 CC |
321 | ------------ |
322 | ||
2df5a846 MH |
323 | Note that the script (`my_script` in the above example) should exit |
324 | with code 0 if the current source code is good/old, and exit with a | |
325 | code between 1 and 127 (inclusive), except 125, if the current source | |
326 | code is bad/new. | |
a17c4101 | 327 | |
23642591 | 328 | Any other exit code will abort the bisect process. It should be noted |
2df5a846 MH |
329 | that a program that terminates via `exit(-1)` leaves $? = 255, (see the |
330 | exit(3) manual page), as the value is chopped with `& 0377`. | |
a17c4101 | 331 | |
71b0251c | 332 | The special exit code 125 should be used when the current source code |
23642591 | 333 | cannot be tested. If the script exits with this code, the current |
958bf6b7 JH |
334 | revision will be skipped (see `git bisect skip` above). 125 was chosen |
335 | as the highest sensible value to use for this purpose, because 126 and 127 | |
336 | are used by POSIX shells to signal specific error status (127 is for | |
3b19dba7 | 337 | command not found, 126 is for command found but not executable--these |
958bf6b7 | 338 | details do not matter, as they are normal errors in the script, as far as |
2df5a846 | 339 | `bisect run` is concerned). |
71b0251c | 340 | |
23642591 DM |
341 | You may often find that during a bisect session you want to have |
342 | temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a | |
343 | header file, or "revision that does not have this commit needs this | |
344 | patch applied to work around another problem this bisection is not | |
345 | interested in") applied to the revision being tested. | |
a17c4101 | 346 | |
5bcce849 | 347 | To cope with such a situation, after the inner 'git bisect' finds the |
23642591 DM |
348 | next revision to test, the script can apply the patch |
349 | before compiling, run the real test, and afterwards decide if the | |
350 | revision (possibly with the needed patch) passed the test and then | |
351 | rewind the tree to the pristine state. Finally the script should exit | |
2df5a846 | 352 | with the status of the real test to let the `git bisect run` command loop |
ee9cf14d | 353 | determine the eventual outcome of the bisect session. |
7fc9d69f | 354 | |
88d78911 JS |
355 | OPTIONS |
356 | ------- | |
357 | --no-checkout:: | |
358 | + | |
359 | Do not checkout the new working tree at each iteration of the bisection | |
661c3e9b | 360 | process. Instead just update a special reference named `BISECT_HEAD` to make |
88d78911 JS |
361 | it point to the commit that should be tested. |
362 | + | |
363 | This option may be useful when the test you would perform in each step | |
364 | does not require a checked out tree. | |
24c51280 JS |
365 | + |
366 | If the repository is bare, `--no-checkout` is assumed. | |
88d78911 | 367 | |
bac59f19 CC |
368 | EXAMPLES |
369 | -------- | |
370 | ||
371 | * Automatically bisect a broken build between v1.2 and HEAD: | |
372 | + | |
373 | ------------ | |
374 | $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good | |
375 | $ git bisect run make # "make" builds the app | |
c787a454 | 376 | $ git bisect reset # quit the bisect session |
bac59f19 CC |
377 | ------------ |
378 | ||
fad5c967 JT |
379 | * Automatically bisect a test failure between origin and HEAD: |
380 | + | |
381 | ------------ | |
382 | $ git bisect start HEAD origin -- # HEAD is bad, origin is good | |
383 | $ git bisect run make test # "make test" builds and tests | |
c787a454 | 384 | $ git bisect reset # quit the bisect session |
fad5c967 JT |
385 | ------------ |
386 | ||
bac59f19 | 387 | * Automatically bisect a broken test case: |
bac59f19 CC |
388 | + |
389 | ------------ | |
390 | $ cat ~/test.sh | |
391 | #!/bin/sh | |
23642591 | 392 | make || exit 125 # this skips broken builds |
9d79b7e9 | 393 | ~/check_test_case.sh # does the test case pass? |
bac59f19 | 394 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 |
bac59f19 | 395 | $ git bisect run ~/test.sh |
c787a454 | 396 | $ git bisect reset # quit the bisect session |
bac59f19 CC |
397 | ------------ |
398 | + | |
2df5a846 | 399 | Here we use a `test.sh` custom script. In this script, if `make` |
23642591 | 400 | fails, we skip the current commit. |
2df5a846 MH |
401 | `check_test_case.sh` should `exit 0` if the test case passes, |
402 | and `exit 1` otherwise. | |
bac59f19 | 403 | + |
2df5a846 | 404 | It is safer if both `test.sh` and `check_test_case.sh` are |
23642591 DM |
405 | outside the repository to prevent interactions between the bisect, |
406 | make and test processes and the scripts. | |
bac59f19 | 407 | |
e235b916 | 408 | * Automatically bisect with temporary modifications (hot-fix): |
bac59f19 CC |
409 | + |
410 | ------------ | |
411 | $ cat ~/test.sh | |
412 | #!/bin/sh | |
e235b916 MG |
413 | |
414 | # tweak the working tree by merging the hot-fix branch | |
415 | # and then attempt a build | |
416 | if git merge --no-commit hot-fix && | |
417 | make | |
418 | then | |
419 | # run project specific test and report its status | |
420 | ~/check_test_case.sh | |
421 | status=$? | |
422 | else | |
423 | # tell the caller this is untestable | |
424 | status=125 | |
425 | fi | |
426 | ||
427 | # undo the tweak to allow clean flipping to the next commit | |
428 | git reset --hard | |
429 | ||
430 | # return control | |
431 | exit $status | |
bac59f19 CC |
432 | ------------ |
433 | + | |
e235b916 MG |
434 | This applies modifications from a hot-fix branch before each test run, |
435 | e.g. in case your build or test environment changed so that older | |
436 | revisions may need a fix which newer ones have already. (Make sure the | |
437 | hot-fix branch is based off a commit which is contained in all revisions | |
438 | which you are bisecting, so that the merge does not pull in too much, or | |
439 | use `git cherry-pick` instead of `git merge`.) | |
bac59f19 | 440 | |
9d79b7e9 | 441 | * Automatically bisect a broken test case: |
fad5c967 JT |
442 | + |
443 | ------------ | |
444 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 | |
445 | $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" | |
c787a454 | 446 | $ git bisect reset # quit the bisect session |
fad5c967 JT |
447 | ------------ |
448 | + | |
9d79b7e9 MG |
449 | This shows that you can do without a run script if you write the test |
450 | on a single line. | |
fad5c967 | 451 | |
88d78911 JS |
452 | * Locate a good region of the object graph in a damaged repository |
453 | + | |
454 | ------------ | |
455 | $ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout | |
456 | $ git bisect run sh -c ' | |
457 | GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) && | |
458 | git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ && | |
459 | git pack-objects --stdout >/dev/null <tmp.$$ | |
460 | rc=$? | |
461 | rm -f tmp.$$ | |
462 | test $rc = 0' | |
463 | ||
c787a454 | 464 | $ git bisect reset # quit the bisect session |
88d78911 JS |
465 | ------------ |
466 | + | |
467 | In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that | |
468 | has at least one parent whose reachable graph is fully traversable in the sense | |
469 | required by 'git pack objects'. | |
470 | ||
21e5cfd8 AD |
471 | * Look for a fix instead of a regression in the code |
472 | + | |
473 | ------------ | |
474 | $ git bisect start | |
475 | $ git bisect new HEAD # current commit is marked as new | |
476 | $ git bisect old HEAD~10 # the tenth commit from now is marked as old | |
477 | ------------ | |
06e6a745 MM |
478 | + |
479 | or: | |
480 | ------------ | |
481 | $ git bisect start --term-old broken --term-new fixed | |
482 | $ git bisect fixed | |
483 | $ git bisect broken HEAD~10 | |
484 | ------------ | |
21e5cfd8 | 485 | |
c9493973 MM |
486 | Getting help |
487 | ~~~~~~~~~~~~ | |
488 | ||
489 | Use `git bisect` to get a short usage description, and `git bisect | |
490 | help` or `git bisect -h` to get a long usage description. | |
88d78911 | 491 | |
69a9cd31 CC |
492 | SEE ALSO |
493 | -------- | |
494 | link:git-bisect-lk2009.html[Fighting regressions with git bisect], | |
495 | linkgit:git-blame[1]. | |
496 | ||
7fc9d69f JH |
497 | GIT |
498 | --- | |
9e1f0a85 | 499 | Part of the linkgit:git[1] suite |