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 [<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 path parameter 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 148Bisect run 149~~~~~~~~~~ 150 151If you have a script that can tell if the current source code is good 152or bad, you can automatically bisect using: 153 154------------ 155$ git bisect run my_script 156------------ 157 158Note that the "run" script (`my_script` in the above example) should 159exit with code 0 in case the current source code is good and with a 160code between 1 and 127 (included) in case the current source code is 161bad. 162 163Any other exit code will abort the automatic bisect process. (A 164program that does "exit(-1)" leaves $? = 255, see exit(3) manual page, 165the value is chopped with "& 0377".) 166 167You may often find that during bisect you want to have near-constant 168tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or 169"revision that does not have this commit needs this patch applied to 170work around other problem this bisection is not interested in") 171applied to the revision being tested. 172 173To cope with such a situation, after the inner git-bisect finds the 174next revision to test, with the "run" script, you can apply that tweak 175before compiling, run the real test, and after the test decides if the 176revision (possibly with the needed tweaks) passed the test, rewind the 177tree to the pristine state. Finally the "run" script can exit with 178the status of the real test to let "git bisect run" command loop to 179know the outcome. 180 181Author 182------ 183Written by Linus Torvalds <torvalds@osdl.org> 184 185Documentation 186------------- 187Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 188 189GIT 190--- 191Part of the gitlink:git[7] suite 192