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