Documentation: AsciiDoc spells em-dash as double-dashes, not triple
[git/git.git] / Documentation / git-bisect.txt
1 git-bisect(1)
2 =============
3
4 NAME
5 ----
6 git-bisect - Find by binary search the change that introduced a bug
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git bisect' <subcommand> <options>
13
14 DESCRIPTION
15 -----------
16 The command takes various subcommands, and different options depending
17 on the subcommand:
18
19 git bisect help
20 git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...]
21 git bisect bad [<rev>]
22 git bisect good [<rev>...]
23 git bisect skip [(<rev>|<range>)...]
24 git bisect reset [<commit>]
25 git bisect visualize
26 git bisect replay <logfile>
27 git bisect log
28 git bisect run <cmd>...
29
30 This command uses 'git rev-list --bisect' to help drive the
31 binary search process to find which change introduced a bug, given an
32 old "good" commit object name and a later "bad" commit object name.
33
34 Getting help
35 ~~~~~~~~~~~~
36
37 Use "git bisect" to get a short usage description, and "git bisect
38 help" or "git bisect -h" to get a long usage description.
39
40 Basic bisect commands: start, bad, good
41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42
43 Using the Linux kernel tree as an example, basic use of the bisect
44 command is as follows:
45
46 ------------------------------------------------
47 $ git bisect start
48 $ git bisect bad # Current version is bad
49 $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
50 # tested that was good
51 ------------------------------------------------
52
53 When you have specified at least one bad and one good version, the
54 command bisects the revision tree and outputs something similar to
55 the following:
56
57 ------------------------------------------------
58 Bisecting: 675 revisions left to test after this
59 ------------------------------------------------
60
61 The state in the middle of the set of revisions is then checked out.
62 You would now compile that kernel and boot it. If the booted kernel
63 works correctly, you would then issue the following command:
64
65 ------------------------------------------------
66 $ git bisect good # this one is good
67 ------------------------------------------------
68
69 The output of this command would be something similar to the following:
70
71 ------------------------------------------------
72 Bisecting: 337 revisions left to test after this
73 ------------------------------------------------
74
75 You keep repeating this process, compiling the tree, testing it, and
76 depending on whether it is good or bad issuing the command "git bisect good"
77 or "git bisect bad" to ask for the next bisection.
78
79 Eventually there will be no more revisions left to bisect, and you
80 will have been left with the first bad kernel revision in "refs/bisect/bad".
81
82 Bisect reset
83 ~~~~~~~~~~~~
84
85 After a bisect session, to clean up the bisection state and return to
86 the original HEAD (i.e., to quit bisecting), issue the following command:
87
88 ------------------------------------------------
89 $ git bisect reset
90 ------------------------------------------------
91
92 By default, this will return your tree to the commit that was checked
93 out before `git bisect start`. (A new `git bisect start` will also do
94 that, as it cleans up the old bisection state.)
95
96 With an optional argument, you can return to a different commit
97 instead:
98
99 ------------------------------------------------
100 $ git bisect reset <commit>
101 ------------------------------------------------
102
103 For example, `git bisect reset HEAD` will leave you on the current
104 bisection commit and avoid switching commits at all, while `git bisect
105 reset bisect/bad` will check out the first bad revision.
106
107 Bisect visualize
108 ~~~~~~~~~~~~~~~~
109
110 To see the currently remaining suspects in 'gitk', issue the following
111 command during the bisection process:
112
113 ------------
114 $ git bisect visualize
115 ------------
116
117 `view` may also be used as a synonym for `visualize`.
118
119 If the 'DISPLAY' environment variable is not set, 'git log' is used
120 instead. You can also give command-line options such as `-p` and
121 `--stat`.
122
123 ------------
124 $ git bisect view --stat
125 ------------
126
127 Bisect log and bisect replay
128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
130 After having marked revisions as good or bad, issue the following
131 command to show what has been done so far:
132
133 ------------
134 $ git bisect log
135 ------------
136
137 If you discover that you made a mistake in specifying the status of a
138 revision, you can save the output of this command to a file, edit it to
139 remove the incorrect entries, and then issue the following commands to
140 return to a corrected state:
141
142 ------------
143 $ git bisect reset
144 $ git bisect replay that-file
145 ------------
146
147 Avoiding testing a commit
148 ~~~~~~~~~~~~~~~~~~~~~~~~~
149
150 If, in the middle of a bisect session, you know that the next suggested
151 revision is not a good one to test (e.g. the change the commit
152 introduces is known not to work in your environment and you know it
153 does not have anything to do with the bug you are chasing), you may
154 want to find a nearby commit and try that instead.
155
156 For example:
157
158 ------------
159 $ git bisect good/bad # previous round was good or bad.
160 Bisecting: 337 revisions left to test after this
161 $ git bisect visualize # oops, that is uninteresting.
162 $ git reset --hard HEAD~3 # try 3 revisions before what
163 # was suggested
164 ------------
165
166 Then compile and test the chosen revision, and afterwards mark
167 the revision as good or bad in the usual manner.
168
169 Bisect skip
170 ~~~~~~~~~~~~
171
172 Instead of choosing by yourself a nearby commit, you can ask Git
173 to do it for you by issuing the command:
174
175 ------------
176 $ git bisect skip # Current version cannot be tested
177 ------------
178
179 But Git may eventually be unable to tell the first bad commit among
180 a bad commit and one or more skipped commits.
181
182 You can even skip a range of commits, instead of just one commit,
183 using the "'<commit1>'..'<commit2>'" notation. For example:
184
185 ------------
186 $ git bisect skip v2.5..v2.6
187 ------------
188
189 This tells the bisect process that no commit after `v2.5`, up to and
190 including `v2.6`, should be tested.
191
192 Note that if you also want to skip the first commit of the range you
193 would issue the command:
194
195 ------------
196 $ git bisect skip v2.5 v2.5..v2.6
197 ------------
198
199 This tells the bisect process that the commits between `v2.5` included
200 and `v2.6` included should be skipped.
201
202
203 Cutting down bisection by giving more parameters to bisect start
204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205
206 You can further cut down the number of trials, if you know what part of
207 the tree is involved in the problem you are tracking down, by specifying
208 path parameters when issuing the `bisect start` command:
209
210 ------------
211 $ git bisect start -- arch/i386 include/asm-i386
212 ------------
213
214 If you know beforehand more than one good commit, you can narrow the
215 bisect space down by specifying all of the good commits immediately after
216 the bad commit when issuing the `bisect start` command:
217
218 ------------
219 $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
220 # v2.6.20-rc6 is bad
221 # v2.6.20-rc4 and v2.6.20-rc1 are good
222 ------------
223
224 Bisect run
225 ~~~~~~~~~~
226
227 If you have a script that can tell if the current source code is good
228 or bad, you can bisect by issuing the command:
229
230 ------------
231 $ git bisect run my_script arguments
232 ------------
233
234 Note that the script (`my_script` in the above example) should
235 exit with code 0 if the current source code is good, and exit with a
236 code between 1 and 127 (inclusive), except 125, if the current
237 source code is bad.
238
239 Any other exit code will abort the bisect process. It should be noted
240 that a program that terminates via "exit(-1)" leaves $? = 255, (see the
241 exit(3) manual page), as the value is chopped with "& 0377".
242
243 The special exit code 125 should be used when the current source code
244 cannot be tested. If the script exits with this code, the current
245 revision will be skipped (see `git bisect skip` above). 125 was chosen
246 as the highest sensible value to use for this purpose, because 126 and 127
247 are used by POSIX shells to signal specific error status (127 is for
248 command not found, 126 is for command found but not executable--these
249 details do not matter, as they are normal errors in the script, as far as
250 "bisect run" is concerned).
251
252 You may often find that during a bisect session you want to have
253 temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
254 header file, or "revision that does not have this commit needs this
255 patch applied to work around another problem this bisection is not
256 interested in") applied to the revision being tested.
257
258 To cope with such a situation, after the inner 'git bisect' finds the
259 next revision to test, the script can apply the patch
260 before compiling, run the real test, and afterwards decide if the
261 revision (possibly with the needed patch) passed the test and then
262 rewind the tree to the pristine state. Finally the script should exit
263 with the status of the real test to let the "git bisect run" command loop
264 determine the eventual outcome of the bisect session.
265
266 OPTIONS
267 -------
268 --no-checkout::
269 +
270 Do not checkout the new working tree at each iteration of the bisection
271 process. Instead just update a special reference named 'BISECT_HEAD' to make
272 it point to the commit that should be tested.
273 +
274 This option may be useful when the test you would perform in each step
275 does not require a checked out tree.
276 +
277 If the repository is bare, `--no-checkout` is assumed.
278
279 EXAMPLES
280 --------
281
282 * Automatically bisect a broken build between v1.2 and HEAD:
283 +
284 ------------
285 $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
286 $ git bisect run make # "make" builds the app
287 $ git bisect reset # quit the bisect session
288 ------------
289
290 * Automatically bisect a test failure between origin and HEAD:
291 +
292 ------------
293 $ git bisect start HEAD origin -- # HEAD is bad, origin is good
294 $ git bisect run make test # "make test" builds and tests
295 $ git bisect reset # quit the bisect session
296 ------------
297
298 * Automatically bisect a broken test case:
299 +
300 ------------
301 $ cat ~/test.sh
302 #!/bin/sh
303 make || exit 125 # this skips broken builds
304 ~/check_test_case.sh # does the test case pass?
305 $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
306 $ git bisect run ~/test.sh
307 $ git bisect reset # quit the bisect session
308 ------------
309 +
310 Here we use a "test.sh" custom script. In this script, if "make"
311 fails, we skip the current commit.
312 "check_test_case.sh" should "exit 0" if the test case passes,
313 and "exit 1" otherwise.
314 +
315 It is safer if both "test.sh" and "check_test_case.sh" are
316 outside the repository to prevent interactions between the bisect,
317 make and test processes and the scripts.
318
319 * Automatically bisect with temporary modifications (hot-fix):
320 +
321 ------------
322 $ cat ~/test.sh
323 #!/bin/sh
324
325 # tweak the working tree by merging the hot-fix branch
326 # and then attempt a build
327 if git merge --no-commit hot-fix &&
328 make
329 then
330 # run project specific test and report its status
331 ~/check_test_case.sh
332 status=$?
333 else
334 # tell the caller this is untestable
335 status=125
336 fi
337
338 # undo the tweak to allow clean flipping to the next commit
339 git reset --hard
340
341 # return control
342 exit $status
343 ------------
344 +
345 This applies modifications from a hot-fix branch before each test run,
346 e.g. in case your build or test environment changed so that older
347 revisions may need a fix which newer ones have already. (Make sure the
348 hot-fix branch is based off a commit which is contained in all revisions
349 which you are bisecting, so that the merge does not pull in too much, or
350 use `git cherry-pick` instead of `git merge`.)
351
352 * Automatically bisect a broken test case:
353 +
354 ------------
355 $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
356 $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
357 $ git bisect reset # quit the bisect session
358 ------------
359 +
360 This shows that you can do without a run script if you write the test
361 on a single line.
362
363 * Locate a good region of the object graph in a damaged repository
364 +
365 ------------
366 $ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
367 $ git bisect run sh -c '
368 GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
369 git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
370 git pack-objects --stdout >/dev/null <tmp.$$
371 rc=$?
372 rm -f tmp.$$
373 test $rc = 0'
374
375 $ git bisect reset # quit the bisect session
376 ------------
377 +
378 In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that
379 has at least one parent whose reachable graph is fully traversable in the sense
380 required by 'git pack objects'.
381
382
383 SEE ALSO
384 --------
385 link:git-bisect-lk2009.html[Fighting regressions with git bisect],
386 linkgit:git-blame[1].
387
388 GIT
389 ---
390 Part of the linkgit:git[1] suite