1git-bisect(1) 2============= 3 4NAME 5---- 6git-bisect - Find the change that introduced a bug by binary search 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 start [<bad> [<good>...]] [--] [<paths>...] 19 git bisect bad <rev> 20 git bisect good <rev> 21 git bisect reset [<branch>] 22 git bisect visualize 23 git bisect replay <logfile> 24 git bisect log 25 git bisect run <cmd>... 26 27This command uses 'git-rev-list --bisect' option to help drive the 28binary search process to find which change introduced a bug, given an 29old "good" commit object name and a later "bad" commit object name. 30 31Basic bisect commands: start, bad, good 32~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33 34The way you use it is: 35 36------------------------------------------------ 37$ git bisect start 38$ git bisect bad # Current version is bad 39$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version 40 # tested that was good 41------------------------------------------------ 42 43When you give at least one bad and one good versions, it will bisect 44the revision tree and say something like: 45 46------------------------------------------------ 47Bisecting: 675 revisions left to test after this 48------------------------------------------------ 49 50and check out the state in the middle. Now, compile that kernel, and 51boot it. Now, let's say that this booted kernel works fine, then just 52do 53 54------------------------------------------------ 55$ git bisect good # this one is good 56------------------------------------------------ 57 58which will now say 59 60------------------------------------------------ 61Bisecting: 337 revisions left to test after this 62------------------------------------------------ 63 64and you continue along, compiling that one, testing it, and depending 65on whether it is good or bad, you say "git bisect good" or "git bisect 66bad", and ask for the next bisection. 67 68Until you have no more left, and you'll have been left with the first 69bad kernel rev in "refs/bisect/bad". 70 71Bisect reset 72~~~~~~~~~~~~ 73 74Oh, and then after you want to reset to the original head, do a 75 76------------------------------------------------ 77$ git bisect reset 78------------------------------------------------ 79 80to get back to the master branch, instead of being in one of the 81bisection branches ("git bisect start" will do that for you too, 82actually: it will reset the bisection state, and before it does that 83it checks that you're not using some old bisection branch). 84 85Bisect visualize 86~~~~~~~~~~~~~~~~ 87 88During the bisection process, you can say 89 90------------ 91$ git bisect visualize 92------------ 93 94to see the currently remaining suspects in `gitk`. 95 96Bisect log and bisect replay 97~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 98 99The good/bad input is logged, and 100 101------------ 102$ git bisect log 103------------ 104 105shows what you have done so far. You can truncate its output somewhere 106and save it in a file, and run 107 108------------ 109$ git bisect replay that-file 110------------ 111 112if you find later you made a mistake telling good/bad about a 113revision. 114 115Avoiding to test a commit 116~~~~~~~~~~~~~~~~~~~~~~~~~ 117 118If in a middle of bisect session, you know what the bisect suggested 119to try next is not a good one to test (e.g. the change the commit 120introduces is known not to work in your environment and you know it 121does not have anything to do with the bug you are chasing), you may 122want to find a near-by commit and try that instead. 123 124It goes something like this: 125 126------------ 127$ git bisect good/bad # previous round was good/bad. 128Bisecting: 337 revisions left to test after this 129$ git bisect visualize # oops, that is uninteresting. 130$ git reset --hard HEAD~3 # try 3 revs before what 131 # was suggested 132------------ 133 134Then compile and test the one you chose to try. After that, tell 135bisect what the result was as usual. 136 137Cutting down bisection by giving more parameters to bisect start 138~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 139 140You can further cut down the number of trials if you know what part of 141the tree is involved in the problem you are tracking down, by giving 142paths parameters when you say `bisect start`, like this: 143 144------------ 145$ git bisect start -- arch/i386 include/asm-i386 146------------ 147 148If you know beforehand more than one good commits, you can narrow the 149bisect space down without doing the whole tree checkout every time you 150give good commits. You give the bad revision immediately after `start` 151and then you give all the good revisions you have: 152 153------------ 154$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- 155 # v2.6.20-rc6 is bad 156 # v2.6.20-rc4 and v2.6.20-rc1 are good 157------------ 158 159Bisect run 160~~~~~~~~~~ 161 162If you have a script that can tell if the current source code is good 163or bad, you can automatically bisect using: 164 165------------ 166$ git bisect run my_script 167------------ 168 169Note that the "run" script (`my_script` in the above example) should 170exit with code 0 in case the current source code is good and with a 171code between 1 and 127 (included) in case the current source code is 172bad. 173 174Any other exit code will abort the automatic bisect process. (A 175program that does "exit(-1)" leaves $? = 255, see exit(3) manual page, 176the value is chopped with "& 0377".) 177 178You may often find that during bisect you want to have near-constant 179tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or 180"revision that does not have this commit needs this patch applied to 181work around other problem this bisection is not interested in") 182applied to the revision being tested. 183 184To cope with such a situation, after the inner git-bisect finds the 185next revision to test, with the "run" script, you can apply that tweak 186before compiling, run the real test, and after the test decides if the 187revision (possibly with the needed tweaks) passed the test, rewind the 188tree to the pristine state. Finally the "run" script can exit with 189the status of the real test to let "git bisect run" command loop to 190know the outcome. 191 192Author 193------ 194Written by Linus Torvalds <torvalds@osdl.org> 195 196Documentation 197------------- 198Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 199 200GIT 201--- 202Part of the gitlink:git[7] suite 203