1GIT-BISECT(1) Git Manual GIT-BISECT(1)
2
6 git-bisect - Find the change that introduced a bug by binary search
7
9 git bisect <subcommand> <options>
10
12 The command takes various subcommands, and different options depending
13 on the subcommand:
14 git bisect start [<bad> [<good>...]] [--] [<paths>...]
17 git bisect bad <rev>
18 git bisect good <rev>
19 git bisect reset [<branch>]
20 git bisect visualize
21 git bisect replay <logfile>
22 git bisect log
23 git bisect run <cmd>...
24 This command uses git-rev-list --bisect option to help drive the binary
25 search process to find which change introduced a bug, given an old
26 "good" commit object name and a later "bad" commit object name.
27 Basic bisect commands: start, bad, good
29 The way you use it is:
30 $ git bisect start
34 $ git bisect bad # Current version is bad
35 $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
36 # tested that was good
37 When you give at least one bad and one good versions, it will bisect
39 the revision tree and say something like:
40 Bisecting: 675 revisions left to test after this
44 and check out the state in the middle. Now, compile that kernel, and
46 boot it. Now, let´s say that this booted kernel works fine, then just
47 do
48 $ git bisect good # this one is good
52 which will now say
54 Bisecting: 337 revisions left to test after this
58 and you continue along, compiling that one, testing it, and depending
60 on whether it is good or bad, you say "git bisect good" or "git bisect
61 bad", and ask for the next bisection.
62 Until you have no more left, and you´ll have been left with the first
64 bad kernel rev in "refs/bisect/bad".
65 Bisect reset
67 Oh, and then after you want to reset to the original head, do a
68 $ git bisect reset
72 to get back to the master branch, instead of being in one of the
74 bisection branches ("git bisect start" will do that for you too,
75 actually: it will reset the bisection state, and before it does that it
76 checks that you´re not using some old bisection branch).
77 Bisect visualize
79 During the bisection process, you can say
80 $ git bisect visualize
84 to see the currently remaining suspects in gitk.
86 Bisect log and bisect replay
88 The good/bad input is logged, and
89 $ git bisect log
93 shows what you have done so far. You can truncate its output somewhere
95 and save it in a file, and run
96 $ git bisect replay that-file
100 if you find later you made a mistake telling good/bad about a revision.
102 Avoiding to test a commit
104 If in a middle of bisect session, you know what the bisect suggested to
105 try next is not a good one to test (e.g. the change the commit
106 introduces is known not to work in your environment and you know it
107 does not have anything to do with the bug you are chasing), you may
108 want to find a near-by commit and try that instead.
109 It goes something like this:
111 $ git bisect good/bad # previous round was good/bad.
115 Bisecting: 337 revisions left to test after this
116 $ git bisect visualize # oops, that is uninteresting.
117 $ git reset --hard HEAD~3 # try 3 revs before what
118 # was suggested
119 Then compile and test the one you chose to try. After that, tell bisect
121 what the result was as usual.
122 Cutting down bisection by giving more parameters to bisect start
124 You can further cut down the number of trials if you know what part of
125 the tree is involved in the problem you are tracking down, by giving
126 paths parameters when you say bisect start, like this:
127 $ git bisect start -- arch/i386 include/asm-i386
131 If you know beforehand more than one good commits, you can narrow the
133 bisect space down without doing the whole tree checkout every time you
134 give good commits. You give the bad revision immediately after start
135 and then you give all the good revisions you have:
136 $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
140 # v2.6.20-rc6 is bad
141 # v2.6.20-rc4 and v2.6.20-rc1 are good
142 Bisect run
145 If you have a script that can tell if the current source code is good
146 or bad, you can automatically bisect using:
147 $ git bisect run my_script
151 Note that the "run" script (my_script in the above example) should exit
153 with code 0 in case the current source code is good and with a code
154 between 1 and 127 (included) in case the current source code is bad.
155 Any other exit code will abort the automatic bisect process. (A program
157 that does "exit(-1)" leaves $? = 255, see exit(3) manual page, the
158 value is chopped with "& 0377".)
159 You may often find that during bisect you want to have near-constant
161 tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
162 "revision that does not have this commit needs this patch applied to
163 work around other problem this bisection is not interested in") applied
164 to the revision being tested.
165 To cope with such a situation, after the inner git-bisect finds the
167 next revision to test, with the "run" script, you can apply that tweak
168 before compiling, run the real test, and after the test decides if the
169 revision (possibly with the needed tweaks) passed the test, rewind the
170 tree to the pristine state. Finally the "run" script can exit with the
171 status of the real test to let "git bisect run" command loop to know
172 the outcome.
173
175 Written by Linus Torvalds <torvalds@osdl.org>
176
178 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
179
181 Part of the git(7) suite
182Git 1.5.3.3 10/09/2007 GIT-BISECT(1)