1git-bisect(1) 2============= 3 4NAME 5---- 6git-bisect - Find by binary search the change that introduced a bug 7 8 9SYNOPSIS 10-------- 11'git bisect' <subcommand> <options> 12 13DESCRIPTION 14----------- 15The command takes various subcommands, and different options depending 16on the subcommand: 17 18 git bisect help 19 git bisect start [<bad> [<good>...]] [--] [<paths>...] 20 git bisect bad [<rev>] 21 git bisect good [<rev>...] 22 git bisect skip [(<rev>|<range>)...] 23 git bisect reset [<branch>] 24 git bisect visualize 25 git bisect replay <logfile> 26 git bisect log 27 git bisect run <cmd>... 28 29This command uses 'git rev-list --bisect' to help drive the 30binary search process to find which change introduced a bug, given an 31old "good" commit object name and a later "bad" commit object name. 32 33Getting help 34~~~~~~~~~~~~ 35 36Use "git bisect" to get a short usage description, and "git bisect 37help" or "git bisect -h" to get a long usage description. 38 39Basic bisect commands: start, bad, good 40~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 41 42Using the Linux kernel tree as an example, basic use of the bisect 43command is as follows: 44 45------------------------------------------------ 46$ git bisect start 47$ git bisect bad # Current version is bad 48$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version 49 # tested that was good 50------------------------------------------------ 51 52When you have specified at least one bad and one good version, the 53command bisects the revision tree and outputs something similar to 54the following: 55 56------------------------------------------------ 57Bisecting: 675 revisions left to test after this 58------------------------------------------------ 59 60The state in the middle of the set of revisions is then checked out. 61You would now compile that kernel and boot it. If the booted kernel 62works correctly, you would then issue the following command: 63 64------------------------------------------------ 65$ git bisect good # this one is good 66------------------------------------------------ 67 68The output of this command would be something similar to the following: 69 70------------------------------------------------ 71Bisecting: 337 revisions left to test after this 72------------------------------------------------ 73 74You keep repeating this process, compiling the tree, testing it, and 75depending on whether it is good or bad issuing the command "git bisect good" 76or "git bisect bad" to ask for the next bisection. 77 78Eventually there will be no more revisions left to bisect, and you 79will have been left with the first bad kernel revision in "refs/bisect/bad". 80 81Bisect reset 82~~~~~~~~~~~~ 83 84To return to the original head after a bisect session, issue the 85following command: 86 87------------------------------------------------ 88$ git bisect reset 89------------------------------------------------ 90 91This resets the tree to the original branch instead of being on the 92bisection commit ("git bisect start" will also do that, as it resets 93the bisection state). 94 95Bisect visualize 96~~~~~~~~~~~~~~~~ 97 98To see the currently remaining suspects in 'gitk', issue the following 99command during the bisection process: 100 101------------ 102$ git bisect visualize 103------------ 104 105`view` may also be used as a synonym for `visualize`. 106 107If the 'DISPLAY' environment variable is not set, 'git log' is used 108instead. You can also give command line options such as `-p` and 109`--stat`. 110 111------------ 112$ git bisect view --stat 113------------ 114 115Bisect log and bisect replay 116~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117 118After having marked revisions as good or bad, issue the following 119command to show what has been done so far: 120 121------------ 122$ git bisect log 123------------ 124 125If you discover that you made a mistake in specifying the status of a 126revision, you can save the output of this command to a file, edit it to 127remove the incorrect entries, and then issue the following commands to 128return to a corrected state: 129 130------------ 131$ git bisect reset 132$ git bisect replay that-file 133------------ 134 135Avoiding testing a commit 136~~~~~~~~~~~~~~~~~~~~~~~~~ 137 138If, in the middle of a bisect session, you know that the next suggested 139revision is not a good one to test (e.g. the change the commit 140introduces is known not to work in your environment and you know it 141does not have anything to do with the bug you are chasing), you may 142want to find a nearby commit and try that instead. 143 144For example: 145 146------------ 147$ git bisect good/bad # previous round was good or bad. 148Bisecting: 337 revisions left to test after this 149$ git bisect visualize # oops, that is uninteresting. 150$ git reset --hard HEAD~3 # try 3 revisions before what 151 # was suggested 152------------ 153 154Then compile and test the chosen revision, and afterwards mark 155the revision as good or bad in the usual manner. 156 157Bisect skip 158~~~~~~~~~~~~ 159 160Instead of choosing by yourself a nearby commit, you can ask git 161to do it for you by issuing the command: 162 163------------ 164$ git bisect skip # Current version cannot be tested 165------------ 166 167But computing the commit to test may be slower afterwards and git may 168eventually not be able to tell the first bad commit among a bad commit 169and one or more skipped commits. 170 171You can even skip a range of commits, instead of just one commit, 172using the "'<commit1>'..'<commit2>'" notation. For example: 173 174------------ 175$ git bisect skip v2.5..v2.6 176------------ 177 178This tells the bisect process that no commit after `v2.5`, up to and 179including `v2.6`, should be tested. 180 181Note that if you also want to skip the first commit of the range you 182would issue the command: 183 184------------ 185$ git bisect skip v2.5 v2.5..v2.6 186------------ 187 188This tells the bisect process that the commits between `v2.5` included 189and `v2.6` included should be skipped. 190 191 192Cutting down bisection by giving more parameters to bisect start 193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 194 195You can further cut down the number of trials, if you know what part of 196the tree is involved in the problem you are tracking down, by specifying 197path parameters when issuing the `bisect start` command: 198 199------------ 200$ git bisect start -- arch/i386 include/asm-i386 201------------ 202 203If you know beforehand more than one good commit, you can narrow the 204bisect space down by specifying all of the good commits immediately after 205the bad commit when issuing the `bisect start` command: 206 207------------ 208$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- 209 # v2.6.20-rc6 is bad 210 # v2.6.20-rc4 and v2.6.20-rc1 are good 211------------ 212 213Bisect run 214~~~~~~~~~~ 215 216If you have a script that can tell if the current source code is good 217or bad, you can bisect by issuing the command: 218 219------------ 220$ git bisect run my_script 221------------ 222 223Note that the script (`my_script` in the above example) should 224exit with code 0 if the current source code is good, and exit with a 225code between 1 and 127 (inclusive), except 125, if the current 226source code is bad. 227 228Any other exit code will abort the bisect process. It should be noted 229that a program that terminates via "exit(-1)" leaves $? = 255, (see the 230exit(3) manual page), as the value is chopped with "& 0377". 231 232The special exit code 125 should be used when the current source code 233cannot be tested. If the script exits with this code, the current 234revision will be skipped (see `git bisect skip` above). 235 236You may often find that during a bisect session you want to have 237temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a 238header file, or "revision that does not have this commit needs this 239patch applied to work around another problem this bisection is not 240interested in") applied to the revision being tested. 241 242To cope with such a situation, after the inner 'git bisect' finds the 243next revision to test, the script can apply the patch 244before compiling, run the real test, and afterwards decide if the 245revision (possibly with the needed patch) passed the test and then 246rewind the tree to the pristine state. Finally the script should exit 247with the status of the real test to let the "git bisect run" command loop 248determine the eventual outcome of the bisect session. 249 250EXAMPLES 251-------- 252 253* Automatically bisect a broken build between v1.2 and HEAD: 254+ 255------------ 256$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good 257$ git bisect run make # "make" builds the app 258------------ 259 260* Automatically bisect a broken test suite: 261+ 262------------ 263$ cat ~/test.sh 264#!/bin/sh 265make || exit 125 # this skips broken builds 266make test # "make test" runs the test suite 267$ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good 268$ git bisect run ~/test.sh 269------------ 270+ 271Here we use a "test.sh" custom script. In this script, if "make" 272fails, we skip the current commit. 273+ 274It is safer to use a custom script outside the repository to prevent 275interactions between the bisect, make and test processes and the 276script. 277+ 278"make test" should "exit 0", if the test suite passes, and 279"exit 1" otherwise. 280 281* Automatically bisect a broken test case: 282+ 283------------ 284$ cat ~/test.sh 285#!/bin/sh 286make || exit 125 # this skips broken builds 287~/check_test_case.sh # does the test case passes ? 288$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 289$ git bisect run ~/test.sh 290------------ 291+ 292Here "check_test_case.sh" should "exit 0" if the test case passes, 293and "exit 1" otherwise. 294+ 295It is safer if both "test.sh" and "check_test_case.sh" scripts are 296outside the repository to prevent interactions between the bisect, 297make and test processes and the scripts. 298 299Author 300------ 301Written by Linus Torvalds <torvalds@osdl.org> 302 303Documentation 304------------- 305Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 306 307GIT 308--- 309Part of the linkgit:git[1] suite