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 26This command uses 'git-rev-list --bisect' option to help drive 27the binary search process to find which change introduced a bug, 28given an old "good" commit object name and a later "bad" commit 29object name. 30 31The way you use it is: 32 33------------------------------------------------ 34$ git bisect start 35$ git bisect bad # Current version is bad 36$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version 37 # tested that was good 38------------------------------------------------ 39 40When you give at least one bad and one good versions, it will 41bisect the revision tree and say something like: 42 43------------------------------------------------ 44Bisecting: 675 revisions left to test after this 45------------------------------------------------ 46 47and check out the state in the middle. Now, compile that kernel, and boot 48it. Now, let's say that this booted kernel works fine, then just do 49 50------------------------------------------------ 51$ git bisect good # this one is good 52------------------------------------------------ 53 54which will now say 55 56------------------------------------------------ 57Bisecting: 337 revisions left to test after this 58------------------------------------------------ 59 60and you continue along, compiling that one, testing it, and depending on 61whether it is good or bad, you say "git bisect good" or "git bisect bad", 62and ask for the next bisection. 63 64Until you have no more left, and you'll have been left with the first bad 65kernel rev in "refs/bisect/bad". 66 67Oh, and then after you want to reset to the original head, do a 68 69------------------------------------------------ 70$ git bisect reset 71------------------------------------------------ 72 73to get back to the master branch, instead of being in one of the bisection 74branches ("git bisect start" will do that for you too, actually: it will 75reset the bisection state, and before it does that it checks that you're 76not using some old bisection branch). 77 78During the bisection process, you can say 79 80------------ 81$ git bisect visualize 82------------ 83 84to see the currently remaining suspects in `gitk`. 85 86The good/bad input is logged, and `git bisect 87log` shows what you have done so far. You can truncate its 88output somewhere and save it in a file, and run 89 90------------ 91$ git bisect replay that-file 92------------ 93 94if you find later you made a mistake telling good/bad about a 95revision. 96 97If in a middle of bisect session, you know what the bisect 98suggested to try next is not a good one to test (e.g. the change 99the commit introduces is known not to work in your environment 100and you know it does not have anything to do with the bug you 101are chasing), you may want to find a near-by commit and try that 102instead. It goes something like this: 103 104------------ 105$ git bisect good/bad # previous round was good/bad. 106Bisecting: 337 revisions left to test after this 107$ git bisect visualize # oops, that is uninteresting. 108$ git reset --hard HEAD~3 # try 3 revs before what 109 # was suggested 110------------ 111 112Then compile and test the one you chose to try. After that, 113tell bisect what the result was as usual. 114 115You can further cut down the number of trials if you know what 116part of the tree is involved in the problem you are tracking 117down, by giving paths parameters when you say `bisect start`, 118like this: 119 120------------ 121$ git bisect start arch/i386 include/asm-i386 122------------ 123 124 125Author 126------ 127Written by Linus Torvalds <torvalds@osdl.org> 128 129Documentation 130------------- 131Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 132 133GIT 134--- 135Part of the gitlink:git[7] suite 136