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