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