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