]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-bisect(1) |
2 | ============= | |
7fc9d69f JH |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-bisect - Find the change that introduced a bug by binary search |
7fc9d69f JH |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
a6080a0a | 11 | 'git bisect' <subcommand> <options> |
7fc9d69f JH |
12 | |
13 | DESCRIPTION | |
14 | ----------- | |
fed820ad CC |
15 | The command takes various subcommands, and different options depending |
16 | on the subcommand: | |
556cb4e5 | 17 | |
243a60fb | 18 | git bisect help |
6fe9c570 | 19 | git bisect start [<bad> [<good>...]] [--] [<paths>...] |
c39ce918 CC |
20 | git bisect bad [<rev>] |
21 | git bisect good [<rev>...] | |
5413812f | 22 | git bisect skip [(<rev>|<range>)...] |
556cb4e5 JH |
23 | git bisect reset [<branch>] |
24 | git bisect visualize | |
25 | git bisect replay <logfile> | |
26 | git bisect log | |
a17c4101 | 27 | git bisect run <cmd>... |
556cb4e5 | 28 | |
5bcce849 | 29 | This command uses 'git rev-list --bisect' to help drive the |
fed820ad CC |
30 | binary search process to find which change introduced a bug, given an |
31 | old "good" commit object name and a later "bad" commit object name. | |
7fc9d69f | 32 | |
243a60fb CC |
33 | Getting help |
34 | ~~~~~~~~~~~~ | |
35 | ||
36 | Use "git bisect" to get a short usage description, and "git bisect | |
37 | help" or "git bisect -h" to get a long usage description. | |
38 | ||
1207f9e7 CC |
39 | Basic bisect commands: start, bad, good |
40 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
41 | ||
f85a4191 | 42 | The way you use it is: |
7fc9d69f | 43 | |
f85a4191 | 44 | ------------------------------------------------ |
556cb4e5 | 45 | $ git bisect start |
6cea0555 CC |
46 | $ git bisect bad # Current version is bad |
47 | $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version | |
48 | # tested that was good | |
f85a4191 | 49 | ------------------------------------------------ |
7fc9d69f | 50 | |
fed820ad CC |
51 | When you give at least one bad and one good versions, it will bisect |
52 | the revision tree and say something like: | |
f85a4191 JH |
53 | |
54 | ------------------------------------------------ | |
55 | Bisecting: 675 revisions left to test after this | |
56 | ------------------------------------------------ | |
57 | ||
fed820ad CC |
58 | and check out the state in the middle. Now, compile that kernel, and |
59 | boot it. Now, let's say that this booted kernel works fine, then just | |
60 | do | |
f85a4191 JH |
61 | |
62 | ------------------------------------------------ | |
556cb4e5 | 63 | $ git bisect good # this one is good |
f85a4191 JH |
64 | ------------------------------------------------ |
65 | ||
66 | which will now say | |
67 | ||
68 | ------------------------------------------------ | |
69 | Bisecting: 337 revisions left to test after this | |
70 | ------------------------------------------------ | |
71 | ||
fed820ad CC |
72 | and you continue along, compiling that one, testing it, and depending |
73 | on whether it is good or bad, you say "git bisect good" or "git bisect | |
74 | bad", and ask for the next bisection. | |
f85a4191 | 75 | |
fed820ad CC |
76 | Until you have no more left, and you'll have been left with the first |
77 | bad kernel rev in "refs/bisect/bad". | |
f85a4191 | 78 | |
1207f9e7 CC |
79 | Bisect reset |
80 | ~~~~~~~~~~~~ | |
81 | ||
f85a4191 JH |
82 | Oh, and then after you want to reset to the original head, do a |
83 | ||
84 | ------------------------------------------------ | |
556cb4e5 | 85 | $ git bisect reset |
f85a4191 JH |
86 | ------------------------------------------------ |
87 | ||
65e73dba CC |
88 | to get back to the original branch, instead of being on the bisection |
89 | commit ("git bisect start" will do that for you too, actually: it will | |
90 | reset the bisection state). | |
7fc9d69f | 91 | |
1207f9e7 CC |
92 | Bisect visualize |
93 | ~~~~~~~~~~~~~~~~ | |
94 | ||
8db9307c JH |
95 | During the bisection process, you can say |
96 | ||
556cb4e5 JH |
97 | ------------ |
98 | $ git bisect visualize | |
99 | ------------ | |
8db9307c | 100 | |
42d36bb8 | 101 | to see the currently remaining suspects in 'gitk'. `visualize` is a bit |
235997c9 JH |
102 | too long to type and `view` is provided as a synonym. |
103 | ||
5bcce849 | 104 | If 'DISPLAY' environment variable is not set, 'git log' is used |
235997c9 JH |
105 | instead. You can even give command line options such as `-p` and |
106 | `--stat`. | |
107 | ||
108 | ------------ | |
109 | $ git bisect view --stat | |
110 | ------------ | |
8db9307c | 111 | |
1207f9e7 CC |
112 | Bisect log and bisect replay |
113 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
114 | ||
fed820ad CC |
115 | The good/bad input is logged, and |
116 | ||
117 | ------------ | |
118 | $ git bisect log | |
119 | ------------ | |
120 | ||
121 | shows what you have done so far. You can truncate its output somewhere | |
122 | and save it in a file, and run | |
b595ed14 | 123 | |
556cb4e5 JH |
124 | ------------ |
125 | $ git bisect replay that-file | |
126 | ------------ | |
b595ed14 JH |
127 | |
128 | if you find later you made a mistake telling good/bad about a | |
129 | revision. | |
130 | ||
1207f9e7 CC |
131 | Avoiding to test a commit |
132 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
133 | ||
fed820ad CC |
134 | If in a middle of bisect session, you know what the bisect suggested |
135 | to try next is not a good one to test (e.g. the change the commit | |
136 | introduces is known not to work in your environment and you know it | |
137 | does not have anything to do with the bug you are chasing), you may | |
138 | want to find a near-by commit and try that instead. | |
139 | ||
140 | It goes something like this: | |
556cb4e5 JH |
141 | |
142 | ------------ | |
143 | $ git bisect good/bad # previous round was good/bad. | |
144 | Bisecting: 337 revisions left to test after this | |
145 | $ git bisect visualize # oops, that is uninteresting. | |
146 | $ git reset --hard HEAD~3 # try 3 revs before what | |
147 | # was suggested | |
148 | ------------ | |
149 | ||
fed820ad CC |
150 | Then compile and test the one you chose to try. After that, tell |
151 | bisect what the result was as usual. | |
556cb4e5 | 152 | |
c39ce918 CC |
153 | Bisect skip |
154 | ~~~~~~~~~~~~ | |
155 | ||
156 | Instead of choosing by yourself a nearby commit, you may just want git | |
157 | to do it for you using: | |
158 | ||
159 | ------------ | |
160 | $ git bisect skip # Current version cannot be tested | |
161 | ------------ | |
162 | ||
163 | But computing the commit to test may be slower afterwards and git may | |
164 | eventually not be able to tell the first bad among a bad and one or | |
165 | more "skip"ped commits. | |
166 | ||
5413812f CC |
167 | You can even skip a range of commits, instead of just one commit, |
168 | using the "'<commit1>'..'<commit2>'" notation. For example: | |
169 | ||
170 | ------------ | |
171 | $ git bisect skip v2.5..v2.6 | |
172 | ------------ | |
173 | ||
174 | would mean that no commit between `v2.5` excluded and `v2.6` included | |
175 | can be tested. | |
176 | ||
177 | Note that if you want to also skip the first commit of a range you can | |
178 | use something like: | |
179 | ||
180 | ------------ | |
181 | $ git bisect skip v2.5 v2.5..v2.6 | |
182 | ------------ | |
183 | ||
184 | and the commit pointed to by `v2.5` will be skipped too. | |
185 | ||
6fe9c570 CC |
186 | Cutting down bisection by giving more parameters to bisect start |
187 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1207f9e7 | 188 | |
fed820ad CC |
189 | You can further cut down the number of trials if you know what part of |
190 | the tree is involved in the problem you are tracking down, by giving | |
191 | paths parameters when you say `bisect start`, like this: | |
556cb4e5 JH |
192 | |
193 | ------------ | |
6fe9c570 CC |
194 | $ git bisect start -- arch/i386 include/asm-i386 |
195 | ------------ | |
196 | ||
197 | If you know beforehand more than one good commits, you can narrow the | |
198 | bisect space down without doing the whole tree checkout every time you | |
199 | give good commits. You give the bad revision immediately after `start` | |
200 | and then you give all the good revisions you have: | |
201 | ||
202 | ------------ | |
203 | $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- | |
204 | # v2.6.20-rc6 is bad | |
205 | # v2.6.20-rc4 and v2.6.20-rc1 are good | |
556cb4e5 JH |
206 | ------------ |
207 | ||
1207f9e7 CC |
208 | Bisect run |
209 | ~~~~~~~~~~ | |
210 | ||
7891a281 CC |
211 | If you have a script that can tell if the current source code is good |
212 | or bad, you can automatically bisect using: | |
a17c4101 CC |
213 | |
214 | ------------ | |
215 | $ git bisect run my_script | |
216 | ------------ | |
217 | ||
7891a281 | 218 | Note that the "run" script (`my_script` in the above example) should |
71b0251c CC |
219 | exit with code 0 in case the current source code is good. Exit with a |
220 | code between 1 and 127 (inclusive), except 125, if the current | |
221 | source code is bad. | |
a17c4101 | 222 | |
cc070d1f CC |
223 | Any other exit code will abort the automatic bisect process. (A |
224 | program that does "exit(-1)" leaves $? = 255, see exit(3) manual page, | |
225 | the value is chopped with "& 0377".) | |
a17c4101 | 226 | |
71b0251c CC |
227 | The special exit code 125 should be used when the current source code |
228 | cannot be tested. If the "run" script exits with this code, the current | |
229 | revision will be skipped, see `git bisect skip` above. | |
230 | ||
a17c4101 CC |
231 | You may often find that during bisect you want to have near-constant |
232 | tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or | |
233 | "revision that does not have this commit needs this patch applied to | |
234 | work around other problem this bisection is not interested in") | |
235 | applied to the revision being tested. | |
236 | ||
5bcce849 | 237 | To cope with such a situation, after the inner 'git bisect' finds the |
a17c4101 CC |
238 | next revision to test, with the "run" script, you can apply that tweak |
239 | before compiling, run the real test, and after the test decides if the | |
240 | revision (possibly with the needed tweaks) passed the test, rewind the | |
241 | tree to the pristine state. Finally the "run" script can exit with | |
483bc4f0 JN |
242 | the status of the real test to let the "git bisect run" command loop to |
243 | determine the outcome. | |
7fc9d69f | 244 | |
bac59f19 CC |
245 | EXAMPLES |
246 | -------- | |
247 | ||
248 | * Automatically bisect a broken build between v1.2 and HEAD: | |
249 | + | |
250 | ------------ | |
251 | $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good | |
252 | $ git bisect run make # "make" builds the app | |
253 | ------------ | |
254 | ||
255 | * Automatically bisect a broken test suite: | |
256 | + | |
257 | ------------ | |
258 | $ cat ~/test.sh | |
259 | #!/bin/sh | |
260 | make || exit 125 # this "skip"s broken builds | |
261 | make test # "make test" runs the test suite | |
262 | $ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good | |
263 | $ git bisect run ~/test.sh | |
264 | ------------ | |
265 | + | |
266 | Here we use a "test.sh" custom script. In this script, if "make" | |
267 | fails, we "skip" the current commit. | |
268 | + | |
269 | It's safer to use a custom script outside the repo to prevent | |
270 | interactions between the bisect, make and test processes and the | |
271 | script. | |
272 | + | |
273 | And "make test" should "exit 0", if the test suite passes, and | |
274 | "exit 1" (for example) otherwise. | |
275 | ||
276 | * Automatically bisect a broken test case: | |
277 | + | |
278 | ------------ | |
279 | $ cat ~/test.sh | |
280 | #!/bin/sh | |
281 | make || exit 125 # this "skip"s broken builds | |
282 | ~/check_test_case.sh # does the test case passes ? | |
283 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 | |
284 | $ git bisect run ~/test.sh | |
285 | ------------ | |
286 | + | |
287 | Here "check_test_case.sh" should "exit 0", if the test case passes, | |
288 | and "exit 1" (for example) otherwise. | |
289 | + | |
290 | It's safer if both "test.sh" and "check_test_case.sh" scripts are | |
291 | outside the repo to prevent interactions between the bisect, make and | |
292 | test processes and the scripts. | |
293 | ||
7fc9d69f JH |
294 | Author |
295 | ------ | |
296 | Written by Linus Torvalds <torvalds@osdl.org> | |
297 | ||
298 | Documentation | |
df8baa42 | 299 | ------------- |
7fc9d69f JH |
300 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
301 | ||
302 | GIT | |
303 | --- | |
9e1f0a85 | 304 | Part of the linkgit:git[1] suite |