]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-bisect(1) |
2 | ============= | |
7fc9d69f JH |
3 | |
4 | NAME | |
5 | ---- | |
23642591 | 6 | git-bisect - Find by binary search the change that introduced a bug |
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>)...] |
6b87ce23 | 23 | git bisect reset [<commit>] |
556cb4e5 JH |
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 | ||
23642591 DM |
42 | Using the Linux kernel tree as an example, basic use of the bisect |
43 | command is as follows: | |
7fc9d69f | 44 | |
f85a4191 | 45 | ------------------------------------------------ |
556cb4e5 | 46 | $ git bisect start |
6cea0555 CC |
47 | $ git bisect bad # Current version is bad |
48 | $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version | |
49 | # tested that was good | |
f85a4191 | 50 | ------------------------------------------------ |
7fc9d69f | 51 | |
23642591 | 52 | When you have specified at least one bad and one good version, the |
4306bcb4 DM |
53 | command bisects the revision tree and outputs something similar to |
54 | the following: | |
f85a4191 JH |
55 | |
56 | ------------------------------------------------ | |
57 | Bisecting: 675 revisions left to test after this | |
58 | ------------------------------------------------ | |
59 | ||
4306bcb4 DM |
60 | The state in the middle of the set of revisions is then checked out. |
61 | You would now compile that kernel and boot it. If the booted kernel | |
62 | works correctly, you would then issue the following command: | |
f85a4191 JH |
63 | |
64 | ------------------------------------------------ | |
556cb4e5 | 65 | $ git bisect good # this one is good |
f85a4191 JH |
66 | ------------------------------------------------ |
67 | ||
4306bcb4 | 68 | The output of this command would be something similar to the following: |
f85a4191 JH |
69 | |
70 | ------------------------------------------------ | |
71 | Bisecting: 337 revisions left to test after this | |
72 | ------------------------------------------------ | |
73 | ||
4306bcb4 DM |
74 | You keep repeating this process, compiling the tree, testing it, and |
75 | depending on whether it is good or bad issuing the command "git bisect good" | |
23642591 | 76 | or "git bisect bad" to ask for the next bisection. |
f85a4191 | 77 | |
23642591 DM |
78 | Eventually there will be no more revisions left to bisect, and you |
79 | will have been left with the first bad kernel revision in "refs/bisect/bad". | |
f85a4191 | 80 | |
1207f9e7 CC |
81 | Bisect reset |
82 | ~~~~~~~~~~~~ | |
83 | ||
6b87ce23 AK |
84 | After a bisect session, to clean up the bisection state and return to |
85 | the original HEAD, issue the following command: | |
f85a4191 JH |
86 | |
87 | ------------------------------------------------ | |
556cb4e5 | 88 | $ git bisect reset |
f85a4191 JH |
89 | ------------------------------------------------ |
90 | ||
6b87ce23 AK |
91 | By default, this will return your tree to the commit that was checked |
92 | out before `git bisect start`. (A new `git bisect start` will also do | |
93 | that, as it cleans up the old bisection state.) | |
94 | ||
95 | With an optional argument, you can return to a different commit | |
96 | instead: | |
97 | ||
98 | ------------------------------------------------ | |
99 | $ git bisect reset <commit> | |
100 | ------------------------------------------------ | |
101 | ||
102 | For example, `git bisect reset HEAD` will leave you on the current | |
103 | bisection commit and avoid switching commits at all, while `git bisect | |
104 | reset bisect/bad` will check out the first bad revision. | |
7fc9d69f | 105 | |
1207f9e7 CC |
106 | Bisect visualize |
107 | ~~~~~~~~~~~~~~~~ | |
108 | ||
a42dea32 DM |
109 | To see the currently remaining suspects in 'gitk', issue the following |
110 | command during the bisection process: | |
8db9307c | 111 | |
556cb4e5 JH |
112 | ------------ |
113 | $ git bisect visualize | |
114 | ------------ | |
8db9307c | 115 | |
4306bcb4 | 116 | `view` may also be used as a synonym for `visualize`. |
235997c9 | 117 | |
23642591 DM |
118 | If the 'DISPLAY' environment variable is not set, 'git log' is used |
119 | instead. You can also give command line options such as `-p` and | |
235997c9 JH |
120 | `--stat`. |
121 | ||
122 | ------------ | |
123 | $ git bisect view --stat | |
124 | ------------ | |
8db9307c | 125 | |
1207f9e7 CC |
126 | Bisect log and bisect replay |
127 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
128 | ||
a42dea32 | 129 | After having marked revisions as good or bad, issue the following |
4306bcb4 | 130 | command to show what has been done so far: |
fed820ad CC |
131 | |
132 | ------------ | |
133 | $ git bisect log | |
134 | ------------ | |
135 | ||
4306bcb4 DM |
136 | If you discover that you made a mistake in specifying the status of a |
137 | revision, you can save the output of this command to a file, edit it to | |
138 | remove the incorrect entries, and then issue the following commands to | |
139 | return to a corrected state: | |
b595ed14 | 140 | |
556cb4e5 | 141 | ------------ |
ee9cf14d | 142 | $ git bisect reset |
556cb4e5 JH |
143 | $ git bisect replay that-file |
144 | ------------ | |
b595ed14 | 145 | |
23642591 | 146 | Avoiding testing a commit |
1207f9e7 CC |
147 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
148 | ||
a42dea32 | 149 | If, in the middle of a bisect session, you know that the next suggested |
23642591 | 150 | revision is not a good one to test (e.g. the change the commit |
fed820ad CC |
151 | introduces is known not to work in your environment and you know it |
152 | does not have anything to do with the bug you are chasing), you may | |
23642591 | 153 | want to find a nearby commit and try that instead. |
fed820ad | 154 | |
23642591 | 155 | For example: |
556cb4e5 JH |
156 | |
157 | ------------ | |
ee9cf14d | 158 | $ git bisect good/bad # previous round was good or bad. |
556cb4e5 JH |
159 | Bisecting: 337 revisions left to test after this |
160 | $ git bisect visualize # oops, that is uninteresting. | |
23642591 | 161 | $ git reset --hard HEAD~3 # try 3 revisions before what |
556cb4e5 JH |
162 | # was suggested |
163 | ------------ | |
164 | ||
19fa5e8c | 165 | Then compile and test the chosen revision, and afterwards mark |
a42dea32 | 166 | the revision as good or bad in the usual manner. |
556cb4e5 | 167 | |
c39ce918 CC |
168 | Bisect skip |
169 | ~~~~~~~~~~~~ | |
170 | ||
23642591 DM |
171 | Instead of choosing by yourself a nearby commit, you can ask git |
172 | to do it for you by issuing the command: | |
c39ce918 CC |
173 | |
174 | ------------ | |
175 | $ git bisect skip # Current version cannot be tested | |
176 | ------------ | |
177 | ||
32d86ca5 CC |
178 | But git may eventually be unable to tell the first bad commit among |
179 | a bad commit and one or more skipped commits. | |
c39ce918 | 180 | |
5413812f CC |
181 | You can even skip a range of commits, instead of just one commit, |
182 | using the "'<commit1>'..'<commit2>'" notation. For example: | |
183 | ||
184 | ------------ | |
185 | $ git bisect skip v2.5..v2.6 | |
186 | ------------ | |
187 | ||
19fa5e8c DM |
188 | This tells the bisect process that no commit after `v2.5`, up to and |
189 | including `v2.6`, should be tested. | |
5413812f | 190 | |
23642591 DM |
191 | Note that if you also want to skip the first commit of the range you |
192 | would issue the command: | |
5413812f CC |
193 | |
194 | ------------ | |
195 | $ git bisect skip v2.5 v2.5..v2.6 | |
196 | ------------ | |
197 | ||
a42dea32 DM |
198 | This tells the bisect process that the commits between `v2.5` included |
199 | and `v2.6` included should be skipped. | |
4306bcb4 | 200 | |
5413812f | 201 | |
6fe9c570 CC |
202 | Cutting down bisection by giving more parameters to bisect start |
203 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1207f9e7 | 204 | |
23642591 DM |
205 | You can further cut down the number of trials, if you know what part of |
206 | the tree is involved in the problem you are tracking down, by specifying | |
4306bcb4 | 207 | path parameters when issuing the `bisect start` command: |
556cb4e5 JH |
208 | |
209 | ------------ | |
6fe9c570 CC |
210 | $ git bisect start -- arch/i386 include/asm-i386 |
211 | ------------ | |
212 | ||
23642591 DM |
213 | If you know beforehand more than one good commit, you can narrow the |
214 | bisect space down by specifying all of the good commits immediately after | |
215 | the bad commit when issuing the `bisect start` command: | |
6fe9c570 CC |
216 | |
217 | ------------ | |
218 | $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- | |
219 | # v2.6.20-rc6 is bad | |
220 | # v2.6.20-rc4 and v2.6.20-rc1 are good | |
556cb4e5 JH |
221 | ------------ |
222 | ||
1207f9e7 CC |
223 | Bisect run |
224 | ~~~~~~~~~~ | |
225 | ||
7891a281 | 226 | If you have a script that can tell if the current source code is good |
23642591 | 227 | or bad, you can bisect by issuing the command: |
a17c4101 CC |
228 | |
229 | ------------ | |
fad5c967 | 230 | $ git bisect run my_script arguments |
a17c4101 CC |
231 | ------------ |
232 | ||
23642591 DM |
233 | Note that the script (`my_script` in the above example) should |
234 | exit with code 0 if the current source code is good, and exit with a | |
71b0251c CC |
235 | code between 1 and 127 (inclusive), except 125, if the current |
236 | source code is bad. | |
a17c4101 | 237 | |
23642591 DM |
238 | Any other exit code will abort the bisect process. It should be noted |
239 | that a program that terminates via "exit(-1)" leaves $? = 255, (see the | |
240 | exit(3) manual page), as the value is chopped with "& 0377". | |
a17c4101 | 241 | |
71b0251c | 242 | The special exit code 125 should be used when the current source code |
23642591 DM |
243 | cannot be tested. If the script exits with this code, the current |
244 | revision will be skipped (see `git bisect skip` above). | |
71b0251c | 245 | |
23642591 DM |
246 | You may often find that during a bisect session you want to have |
247 | temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a | |
248 | header file, or "revision that does not have this commit needs this | |
249 | patch applied to work around another problem this bisection is not | |
250 | interested in") applied to the revision being tested. | |
a17c4101 | 251 | |
5bcce849 | 252 | To cope with such a situation, after the inner 'git bisect' finds the |
23642591 DM |
253 | next revision to test, the script can apply the patch |
254 | before compiling, run the real test, and afterwards decide if the | |
255 | revision (possibly with the needed patch) passed the test and then | |
256 | rewind the tree to the pristine state. Finally the script should exit | |
257 | with the status of the real test to let the "git bisect run" command loop | |
ee9cf14d | 258 | determine the eventual outcome of the bisect session. |
7fc9d69f | 259 | |
bac59f19 CC |
260 | EXAMPLES |
261 | -------- | |
262 | ||
263 | * Automatically bisect a broken build between v1.2 and HEAD: | |
264 | + | |
265 | ------------ | |
266 | $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good | |
267 | $ git bisect run make # "make" builds the app | |
268 | ------------ | |
269 | ||
fad5c967 JT |
270 | * Automatically bisect a test failure between origin and HEAD: |
271 | + | |
272 | ------------ | |
273 | $ git bisect start HEAD origin -- # HEAD is bad, origin is good | |
274 | $ git bisect run make test # "make test" builds and tests | |
275 | ------------ | |
276 | ||
bac59f19 CC |
277 | * Automatically bisect a broken test suite: |
278 | + | |
279 | ------------ | |
280 | $ cat ~/test.sh | |
281 | #!/bin/sh | |
23642591 | 282 | make || exit 125 # this skips broken builds |
bac59f19 CC |
283 | make test # "make test" runs the test suite |
284 | $ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good | |
285 | $ git bisect run ~/test.sh | |
286 | ------------ | |
287 | + | |
288 | Here we use a "test.sh" custom script. In this script, if "make" | |
23642591 | 289 | fails, we skip the current commit. |
bac59f19 | 290 | + |
23642591 | 291 | It is safer to use a custom script outside the repository to prevent |
bac59f19 CC |
292 | interactions between the bisect, make and test processes and the |
293 | script. | |
294 | + | |
23642591 DM |
295 | "make test" should "exit 0", if the test suite passes, and |
296 | "exit 1" otherwise. | |
bac59f19 CC |
297 | |
298 | * Automatically bisect a broken test case: | |
299 | + | |
300 | ------------ | |
301 | $ cat ~/test.sh | |
302 | #!/bin/sh | |
23642591 | 303 | make || exit 125 # this skips broken builds |
bac59f19 CC |
304 | ~/check_test_case.sh # does the test case passes ? |
305 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 | |
306 | $ git bisect run ~/test.sh | |
307 | ------------ | |
308 | + | |
23642591 DM |
309 | Here "check_test_case.sh" should "exit 0" if the test case passes, |
310 | and "exit 1" otherwise. | |
bac59f19 | 311 | + |
23642591 DM |
312 | It is safer if both "test.sh" and "check_test_case.sh" scripts are |
313 | outside the repository to prevent interactions between the bisect, | |
314 | make and test processes and the scripts. | |
bac59f19 | 315 | |
fad5c967 JT |
316 | * Automatically bisect a broken test suite: |
317 | + | |
318 | ------------ | |
319 | $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 | |
320 | $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" | |
321 | ------------ | |
322 | + | |
323 | Does the same as the previous example, but on a single line. | |
324 | ||
7fc9d69f JH |
325 | Author |
326 | ------ | |
327 | Written by Linus Torvalds <torvalds@osdl.org> | |
328 | ||
329 | Documentation | |
df8baa42 | 330 | ------------- |
7fc9d69f JH |
331 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
332 | ||
69a9cd31 CC |
333 | SEE ALSO |
334 | -------- | |
335 | link:git-bisect-lk2009.html[Fighting regressions with git bisect], | |
336 | linkgit:git-blame[1]. | |
337 | ||
7fc9d69f JH |
338 | GIT |
339 | --- | |
9e1f0a85 | 340 | Part of the linkgit:git[1] suite |