git-bisect.sh: don't accidentally override existing branch "bisect"
[git/git.git] / Documentation / git-bisect.txt
CommitLineData
215a7ad1
JH
1git-bisect(1)
2=============
7fc9d69f
JH
3
4NAME
5----
c3f0baac 6git-bisect - Find the change that introduced a bug by binary search
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
6fe9c570 18 git bisect start [<bad> [<good>...]] [--] [<paths>...]
c39ce918
CC
19 git bisect bad [<rev>]
20 git bisect good [<rev>...]
21 git bisect skip [<rev>...]
556cb4e5
JH
22 git bisect reset [<branch>]
23 git bisect visualize
24 git bisect replay <logfile>
25 git bisect log
a17c4101 26 git bisect run <cmd>...
556cb4e5 27
fed820ad
CC
28This command uses 'git-rev-list --bisect' option to help drive the
29binary search process to find which change introduced a bug, given an
30old "good" commit object name and a later "bad" commit object name.
7fc9d69f 31
1207f9e7
CC
32Basic bisect commands: start, bad, good
33~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34
f85a4191 35The way you use it is:
7fc9d69f 36
f85a4191 37------------------------------------------------
556cb4e5 38$ git bisect start
6cea0555
CC
39$ git bisect bad # Current version is bad
40$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
41 # tested that was good
f85a4191 42------------------------------------------------
7fc9d69f 43
fed820ad
CC
44When you give at least one bad and one good versions, it will bisect
45the revision tree and say something like:
f85a4191
JH
46
47------------------------------------------------
48Bisecting: 675 revisions left to test after this
49------------------------------------------------
50
fed820ad
CC
51and check out the state in the middle. Now, compile that kernel, and
52boot it. Now, let's say that this booted kernel works fine, then just
53do
f85a4191
JH
54
55------------------------------------------------
556cb4e5 56$ git bisect good # this one is good
f85a4191
JH
57------------------------------------------------
58
59which will now say
60
61------------------------------------------------
62Bisecting: 337 revisions left to test after this
63------------------------------------------------
64
fed820ad
CC
65and you continue along, compiling that one, testing it, and depending
66on whether it is good or bad, you say "git bisect good" or "git bisect
67bad", and ask for the next bisection.
f85a4191 68
fed820ad
CC
69Until you have no more left, and you'll have been left with the first
70bad kernel rev in "refs/bisect/bad".
f85a4191 71
1207f9e7
CC
72Bisect reset
73~~~~~~~~~~~~
74
f85a4191
JH
75Oh, and then after you want to reset to the original head, do a
76
77------------------------------------------------
556cb4e5 78$ git bisect reset
f85a4191
JH
79------------------------------------------------
80
ee831f7d 81to get back to the original branch, instead of being in one of the
fed820ad
CC
82bisection branches ("git bisect start" will do that for you too,
83actually: it will reset the bisection state, and before it does that
84it checks that you're not using some old bisection branch).
7fc9d69f 85
1207f9e7
CC
86Bisect visualize
87~~~~~~~~~~~~~~~~
88
8db9307c
JH
89During the bisection process, you can say
90
556cb4e5
JH
91------------
92$ git bisect visualize
93------------
8db9307c 94
235997c9
JH
95to see the currently remaining suspects in `gitk`. `visualize` is a bit
96too long to type and `view` is provided as a synonym.
97
98If `DISPLAY` environment variable is not set, `git log` is used
99instead. You can even give command line options such as `-p` and
100`--stat`.
101
102------------
103$ git bisect view --stat
104------------
8db9307c 105
1207f9e7
CC
106Bisect log and bisect replay
107~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108
fed820ad
CC
109The good/bad input is logged, and
110
111------------
112$ git bisect log
113------------
114
115shows what you have done so far. You can truncate its output somewhere
116and save it in a file, and run
b595ed14 117
556cb4e5
JH
118------------
119$ git bisect replay that-file
120------------
b595ed14
JH
121
122if you find later you made a mistake telling good/bad about a
123revision.
124
1207f9e7
CC
125Avoiding to test a commit
126~~~~~~~~~~~~~~~~~~~~~~~~~
127
fed820ad
CC
128If in a middle of bisect session, you know what the bisect suggested
129to try next is not a good one to test (e.g. the change the commit
130introduces is known not to work in your environment and you know it
131does not have anything to do with the bug you are chasing), you may
132want to find a near-by commit and try that instead.
133
134It goes something like this:
556cb4e5
JH
135
136------------
137$ git bisect good/bad # previous round was good/bad.
138Bisecting: 337 revisions left to test after this
139$ git bisect visualize # oops, that is uninteresting.
140$ git reset --hard HEAD~3 # try 3 revs before what
141 # was suggested
142------------
143
fed820ad
CC
144Then compile and test the one you chose to try. After that, tell
145bisect what the result was as usual.
556cb4e5 146
c39ce918
CC
147Bisect skip
148~~~~~~~~~~~~
149
150Instead of choosing by yourself a nearby commit, you may just want git
151to do it for you using:
152
153------------
154$ git bisect skip # Current version cannot be tested
155------------
156
157But computing the commit to test may be slower afterwards and git may
158eventually not be able to tell the first bad among a bad and one or
159more "skip"ped commits.
160
6fe9c570
CC
161Cutting down bisection by giving more parameters to bisect start
162~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1207f9e7 163
fed820ad
CC
164You can further cut down the number of trials if you know what part of
165the tree is involved in the problem you are tracking down, by giving
166paths parameters when you say `bisect start`, like this:
556cb4e5
JH
167
168------------
6fe9c570
CC
169$ git bisect start -- arch/i386 include/asm-i386
170------------
171
172If you know beforehand more than one good commits, you can narrow the
173bisect space down without doing the whole tree checkout every time you
174give good commits. You give the bad revision immediately after `start`
175and then you give all the good revisions you have:
176
177------------
178$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
179 # v2.6.20-rc6 is bad
180 # v2.6.20-rc4 and v2.6.20-rc1 are good
556cb4e5
JH
181------------
182
1207f9e7
CC
183Bisect run
184~~~~~~~~~~
185
7891a281
CC
186If you have a script that can tell if the current source code is good
187or bad, you can automatically bisect using:
a17c4101
CC
188
189------------
190$ git bisect run my_script
191------------
192
7891a281 193Note that the "run" script (`my_script` in the above example) should
71b0251c
CC
194exit with code 0 in case the current source code is good. Exit with a
195code between 1 and 127 (inclusive), except 125, if the current
196source code is bad.
a17c4101 197
cc070d1f
CC
198Any other exit code will abort the automatic bisect process. (A
199program that does "exit(-1)" leaves $? = 255, see exit(3) manual page,
200the value is chopped with "& 0377".)
a17c4101 201
71b0251c
CC
202The special exit code 125 should be used when the current source code
203cannot be tested. If the "run" script exits with this code, the current
204revision will be skipped, see `git bisect skip` above.
205
a17c4101
CC
206You may often find that during bisect you want to have near-constant
207tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
208"revision that does not have this commit needs this patch applied to
209work around other problem this bisection is not interested in")
210applied to the revision being tested.
211
212To cope with such a situation, after the inner git-bisect finds the
213next revision to test, with the "run" script, you can apply that tweak
214before compiling, run the real test, and after the test decides if the
215revision (possibly with the needed tweaks) passed the test, rewind the
216tree to the pristine state. Finally the "run" script can exit with
217the status of the real test to let "git bisect run" command loop to
218know the outcome.
7fc9d69f
JH
219
220Author
221------
222Written by Linus Torvalds <torvalds@osdl.org>
223
224Documentation
df8baa42 225-------------
7fc9d69f
JH
226Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
227
228GIT
229---
5162e697 230Part of the linkgit:git[7] suite