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