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