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