bisect: mention "view" as an alternative to "visualize"
[git/git.git] / Documentation / git-bisect.txt
CommitLineData
215a7ad1
JH
1git-bisect(1)
2=============
7fc9d69f
JH
3
4NAME
5----
2df5a846 6git-bisect - Use binary search to find the commit that introduced a bug
7fc9d69f
JH
7
8
9SYNOPSIS
10--------
7791a1d9 11[verse]
a6080a0a 12'git bisect' <subcommand> <options>
7fc9d69f
JH
13
14DESCRIPTION
15-----------
fed820ad
CC
16The command takes various subcommands, and different options depending
17on the subcommand:
556cb4e5 18
06e6a745
MM
19 git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>]
20 [--no-checkout] [<bad> [<good>...]] [--] [<paths>...]
3f05402a
CC
21 git bisect (bad|new|<term-new>) [<rev>]
22 git bisect (good|old|<term-old>) [<rev>...]
21b55e33 23 git bisect terms [--term-good | --term-bad]
5413812f 24 git bisect skip [(<rev>|<range>)...]
6b87ce23 25 git bisect reset [<commit>]
dbc349bb 26 git bisect (visualize|view)
556cb4e5
JH
27 git bisect replay <logfile>
28 git bisect log
a17c4101 29 git bisect run <cmd>...
2df5a846 30 git bisect help
556cb4e5 31
2df5a846
MH
32This command uses a binary search algorithm to find which commit in
33your project's history introduced a bug. You use it by first telling
34it a "bad" commit that is known to contain the bug, and a "good"
35commit that is known to be before the bug was introduced. Then `git
36bisect` picks a commit between those two endpoints and asks you
37whether the selected commit is "good" or "bad". It continues narrowing
38down the range until it finds the exact commit that introduced the
39change.
7fc9d69f 40
21e5cfd8
AD
41In fact, `git bisect` can be used to find the commit that changed
42*any* property of your project; e.g., the commit that fixed a bug, or
43the commit that caused a benchmark's performance to improve. To
44support this more general usage, the terms "old" and "new" can be used
06e6a745 45in place of "good" and "bad", or you can choose your own terms. See
21e5cfd8
AD
46section "Alternate terms" below for more information.
47
1207f9e7
CC
48Basic bisect commands: start, bad, good
49~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50
2df5a846
MH
51As an example, suppose you are trying to find the commit that broke a
52feature that was known to work in version `v2.6.13-rc2` of your
53project. You start a bisect session as follows:
7fc9d69f 54
f85a4191 55------------------------------------------------
556cb4e5 56$ git bisect start
6cea0555 57$ git bisect bad # Current version is bad
2df5a846
MH
58$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good
59------------------------------------------------
60
61Once you have specified at least one bad and one good commit, `git
62bisect` selects a commit in the middle of that range of history,
63checks it out, and outputs something similar to the following:
64
65------------------------------------------------
66Bisecting: 675 revisions left to test after this (roughly 10 steps)
f85a4191 67------------------------------------------------
7fc9d69f 68
2df5a846
MH
69You should now compile the checked-out version and test it. If that
70version works correctly, type
f85a4191
JH
71
72------------------------------------------------
2df5a846 73$ git bisect good
f85a4191
JH
74------------------------------------------------
75
2df5a846 76If that version is broken, type
f85a4191
JH
77
78------------------------------------------------
2df5a846 79$ git bisect bad
f85a4191
JH
80------------------------------------------------
81
2df5a846 82Then `git bisect` will respond with something like
f85a4191
JH
83
84------------------------------------------------
2df5a846 85Bisecting: 337 revisions left to test after this (roughly 9 steps)
f85a4191
JH
86------------------------------------------------
87
2df5a846
MH
88Keep repeating the process: compile the tree, test it, and depending
89on whether it is good or bad run `git bisect good` or `git bisect bad`
90to ask for the next commit that needs testing.
91
92Eventually there will be no more revisions left to inspect, and the
93command will print out a description of the first bad commit. The
94reference `refs/bisect/bad` will be left pointing at that commit.
f85a4191 95
f85a4191 96
1207f9e7
CC
97Bisect reset
98~~~~~~~~~~~~
99
6b87ce23 100After a bisect session, to clean up the bisection state and return to
2df5a846 101the original HEAD, issue the following command:
f85a4191
JH
102
103------------------------------------------------
556cb4e5 104$ git bisect reset
f85a4191
JH
105------------------------------------------------
106
6b87ce23
AK
107By default, this will return your tree to the commit that was checked
108out before `git bisect start`. (A new `git bisect start` will also do
109that, as it cleans up the old bisection state.)
110
111With an optional argument, you can return to a different commit
112instead:
113
114------------------------------------------------
115$ git bisect reset <commit>
116------------------------------------------------
117
2df5a846
MH
118For example, `git bisect reset bisect/bad` will check out the first
119bad revision, while `git bisect reset HEAD` will leave you on the
120current bisection commit and avoid switching commits at all.
121
7fc9d69f 122
21e5cfd8
AD
123Alternate terms
124~~~~~~~~~~~~~~~
125
126Sometimes you are not looking for the commit that introduced a
127breakage, but rather for a commit that caused a change between some
128other "old" state and "new" state. For example, you might be looking
129for the commit that introduced a particular fix. Or you might be
130looking for the first commit in which the source-code filenames were
131finally all converted to your company's naming standard. Or whatever.
132
133In such cases it can be very confusing to use the terms "good" and
134"bad" to refer to "the state before the change" and "the state after
135the change". So instead, you can use the terms "old" and "new",
136respectively, in place of "good" and "bad". (But note that you cannot
137mix "good" and "bad" with "old" and "new" in a single session.)
138
139In this more general usage, you provide `git bisect` with a "new"
60b091c6 140commit that has some property and an "old" commit that doesn't have that
21e5cfd8
AD
141property. Each time `git bisect` checks out a commit, you test if that
142commit has the property. If it does, mark the commit as "new";
143otherwise, mark it as "old". When the bisection is done, `git bisect`
144will report which commit introduced the property.
145
146To use "old" and "new" instead of "good" and bad, you must run `git
147bisect start` without commits as argument and then run the following
148commands to add the commits:
149
150------------------------------------------------
151git bisect old [<rev>]
152------------------------------------------------
153
154to indicate that a commit was before the sought change, or
155
156------------------------------------------------
157git bisect new [<rev>...]
158------------------------------------------------
159
160to indicate that it was after.
161
21b55e33
MM
162To get a reminder of the currently used terms, use
163
164------------------------------------------------
165git bisect terms
166------------------------------------------------
167
168You can get just the old (respectively new) term with `git bisect term
169--term-old` or `git bisect term --term-good`.
170
06e6a745
MM
171If you would like to use your own terms instead of "bad"/"good" or
172"new"/"old", you can choose any names you like (except existing bisect
173subcommands like `reset`, `start`, ...) by starting the
174bisection using
175
176------------------------------------------------
177git bisect start --term-old <term-old> --term-new <term-new>
178------------------------------------------------
179
180For example, if you are looking for a commit that introduced a
181performance regression, you might use
182
183------------------------------------------------
184git bisect start --term-old fast --term-new slow
185------------------------------------------------
186
187Or if you are looking for the commit that fixed a bug, you might use
188
189------------------------------------------------
190git bisect start --term-new fixed --term-old broken
191------------------------------------------------
192
193Then, use `git bisect <term-old>` and `git bisect <term-new>` instead
194of `git bisect good` and `git bisect bad` to mark commits.
195
dbc349bb
RD
196Bisect visualize/view
197~~~~~~~~~~~~~~~~~~~~~
1207f9e7 198
a42dea32 199To see the currently remaining suspects in 'gitk', issue the following
dbc349bb
RD
200command during the bisection process (the subcommand `view` can be used
201as an alternative to `visualize`):
8db9307c 202
556cb4e5
JH
203------------
204$ git bisect visualize
205------------
8db9307c 206
47d81b5c 207If the `DISPLAY` environment variable is not set, 'git log' is used
06ab60c0 208instead. You can also give command-line options such as `-p` and
235997c9
JH
209`--stat`.
210
211------------
dbc349bb 212$ git bisect visualize --stat
235997c9 213------------
8db9307c 214
1207f9e7
CC
215Bisect log and bisect replay
216~~~~~~~~~~~~~~~~~~~~~~~~~~~~
217
a42dea32 218After having marked revisions as good or bad, issue the following
4306bcb4 219command to show what has been done so far:
fed820ad
CC
220
221------------
222$ git bisect log
223------------
224
4306bcb4
DM
225If you discover that you made a mistake in specifying the status of a
226revision, you can save the output of this command to a file, edit it to
227remove the incorrect entries, and then issue the following commands to
228return to a corrected state:
b595ed14 229
556cb4e5 230------------
ee9cf14d 231$ git bisect reset
556cb4e5
JH
232$ git bisect replay that-file
233------------
b595ed14 234
23642591 235Avoiding testing a commit
1207f9e7
CC
236~~~~~~~~~~~~~~~~~~~~~~~~~
237
2df5a846
MH
238If, in the middle of a bisect session, you know that the suggested
239revision is not a good one to test (e.g. it fails to build and you
240know that the failure does not have anything to do with the bug you
241are chasing), you can manually select a nearby commit and test that
242one instead.
fed820ad 243
23642591 244For example:
556cb4e5
JH
245
246------------
ee9cf14d 247$ git bisect good/bad # previous round was good or bad.
2df5a846 248Bisecting: 337 revisions left to test after this (roughly 9 steps)
556cb4e5 249$ git bisect visualize # oops, that is uninteresting.
23642591 250$ git reset --hard HEAD~3 # try 3 revisions before what
556cb4e5
JH
251 # was suggested
252------------
253
19fa5e8c 254Then compile and test the chosen revision, and afterwards mark
a42dea32 255the revision as good or bad in the usual manner.
556cb4e5 256
c39ce918 257Bisect skip
142d035a 258~~~~~~~~~~~
c39ce918 259
2df5a846
MH
260Instead of choosing a nearby commit by yourself, you can ask Git to do
261it for you by issuing the command:
c39ce918
CC
262
263------------
264$ git bisect skip # Current version cannot be tested
265------------
266
2df5a846
MH
267However, if you skip a commit adjacent to the one you are looking for,
268Git will be unable to tell exactly which of those commits was the
269first bad one.
c39ce918 270
2df5a846
MH
271You can also skip a range of commits, instead of just one commit,
272using range notation. For example:
5413812f
CC
273
274------------
275$ git bisect skip v2.5..v2.6
276------------
277
19fa5e8c
DM
278This tells the bisect process that no commit after `v2.5`, up to and
279including `v2.6`, should be tested.
5413812f 280
23642591
DM
281Note that if you also want to skip the first commit of the range you
282would issue the command:
5413812f
CC
283
284------------
285$ git bisect skip v2.5 v2.5..v2.6
286------------
287
2df5a846
MH
288This tells the bisect process that the commits between `v2.5` and
289`v2.6` (inclusive) should be skipped.
4306bcb4 290
5413812f 291
6fe9c570
CC
292Cutting down bisection by giving more parameters to bisect start
293~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1207f9e7 294
23642591
DM
295You can further cut down the number of trials, if you know what part of
296the tree is involved in the problem you are tracking down, by specifying
4306bcb4 297path parameters when issuing the `bisect start` command:
556cb4e5
JH
298
299------------
6fe9c570
CC
300$ git bisect start -- arch/i386 include/asm-i386
301------------
302
23642591
DM
303If you know beforehand more than one good commit, you can narrow the
304bisect space down by specifying all of the good commits immediately after
305the bad commit when issuing the `bisect start` command:
6fe9c570
CC
306
307------------
308$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
309 # v2.6.20-rc6 is bad
310 # v2.6.20-rc4 and v2.6.20-rc1 are good
556cb4e5
JH
311------------
312
1207f9e7
CC
313Bisect run
314~~~~~~~~~~
315
7891a281 316If you have a script that can tell if the current source code is good
23642591 317or bad, you can bisect by issuing the command:
a17c4101
CC
318
319------------
fad5c967 320$ git bisect run my_script arguments
a17c4101
CC
321------------
322
2df5a846
MH
323Note that the script (`my_script` in the above example) should exit
324with code 0 if the current source code is good/old, and exit with a
325code between 1 and 127 (inclusive), except 125, if the current source
326code is bad/new.
a17c4101 327
23642591 328Any other exit code will abort the bisect process. It should be noted
2df5a846
MH
329that a program that terminates via `exit(-1)` leaves $? = 255, (see the
330exit(3) manual page), as the value is chopped with `& 0377`.
a17c4101 331
71b0251c 332The special exit code 125 should be used when the current source code
23642591 333cannot be tested. If the script exits with this code, the current
958bf6b7
JH
334revision will be skipped (see `git bisect skip` above). 125 was chosen
335as the highest sensible value to use for this purpose, because 126 and 127
336are used by POSIX shells to signal specific error status (127 is for
3b19dba7 337command not found, 126 is for command found but not executable--these
958bf6b7 338details do not matter, as they are normal errors in the script, as far as
2df5a846 339`bisect run` is concerned).
71b0251c 340
23642591
DM
341You may often find that during a bisect session you want to have
342temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
343header file, or "revision that does not have this commit needs this
344patch applied to work around another problem this bisection is not
345interested in") applied to the revision being tested.
a17c4101 346
5bcce849 347To cope with such a situation, after the inner 'git bisect' finds the
23642591
DM
348next revision to test, the script can apply the patch
349before compiling, run the real test, and afterwards decide if the
350revision (possibly with the needed patch) passed the test and then
351rewind the tree to the pristine state. Finally the script should exit
2df5a846 352with the status of the real test to let the `git bisect run` command loop
ee9cf14d 353determine the eventual outcome of the bisect session.
7fc9d69f 354
88d78911
JS
355OPTIONS
356-------
357--no-checkout::
358+
359Do not checkout the new working tree at each iteration of the bisection
661c3e9b 360process. Instead just update a special reference named `BISECT_HEAD` to make
88d78911
JS
361it point to the commit that should be tested.
362+
363This option may be useful when the test you would perform in each step
364does not require a checked out tree.
24c51280
JS
365+
366If the repository is bare, `--no-checkout` is assumed.
88d78911 367
bac59f19
CC
368EXAMPLES
369--------
370
371* Automatically bisect a broken build between v1.2 and HEAD:
372+
373------------
374$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
375$ git bisect run make # "make" builds the app
c787a454 376$ git bisect reset # quit the bisect session
bac59f19
CC
377------------
378
fad5c967
JT
379* Automatically bisect a test failure between origin and HEAD:
380+
381------------
382$ git bisect start HEAD origin -- # HEAD is bad, origin is good
383$ git bisect run make test # "make test" builds and tests
c787a454 384$ git bisect reset # quit the bisect session
fad5c967
JT
385------------
386
bac59f19 387* Automatically bisect a broken test case:
bac59f19
CC
388+
389------------
390$ cat ~/test.sh
391#!/bin/sh
23642591 392make || exit 125 # this skips broken builds
9d79b7e9 393~/check_test_case.sh # does the test case pass?
bac59f19 394$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
bac59f19 395$ git bisect run ~/test.sh
c787a454 396$ git bisect reset # quit the bisect session
bac59f19
CC
397------------
398+
2df5a846 399Here we use a `test.sh` custom script. In this script, if `make`
23642591 400fails, we skip the current commit.
2df5a846
MH
401`check_test_case.sh` should `exit 0` if the test case passes,
402and `exit 1` otherwise.
bac59f19 403+
2df5a846 404It is safer if both `test.sh` and `check_test_case.sh` are
23642591
DM
405outside the repository to prevent interactions between the bisect,
406make and test processes and the scripts.
bac59f19 407
e235b916 408* Automatically bisect with temporary modifications (hot-fix):
bac59f19
CC
409+
410------------
411$ cat ~/test.sh
412#!/bin/sh
e235b916
MG
413
414# tweak the working tree by merging the hot-fix branch
415# and then attempt a build
416if git merge --no-commit hot-fix &&
417 make
418then
419 # run project specific test and report its status
420 ~/check_test_case.sh
421 status=$?
422else
423 # tell the caller this is untestable
424 status=125
425fi
426
427# undo the tweak to allow clean flipping to the next commit
428git reset --hard
429
430# return control
431exit $status
bac59f19
CC
432------------
433+
e235b916
MG
434This applies modifications from a hot-fix branch before each test run,
435e.g. in case your build or test environment changed so that older
436revisions may need a fix which newer ones have already. (Make sure the
437hot-fix branch is based off a commit which is contained in all revisions
438which you are bisecting, so that the merge does not pull in too much, or
439use `git cherry-pick` instead of `git merge`.)
bac59f19 440
9d79b7e9 441* Automatically bisect a broken test case:
fad5c967
JT
442+
443------------
444$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
445$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
c787a454 446$ git bisect reset # quit the bisect session
fad5c967
JT
447------------
448+
9d79b7e9
MG
449This shows that you can do without a run script if you write the test
450on a single line.
fad5c967 451
88d78911
JS
452* Locate a good region of the object graph in a damaged repository
453+
454------------
455$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
456$ git bisect run sh -c '
457 GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
458 git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
459 git pack-objects --stdout >/dev/null <tmp.$$
460 rc=$?
461 rm -f tmp.$$
462 test $rc = 0'
463
c787a454 464$ git bisect reset # quit the bisect session
88d78911
JS
465------------
466+
467In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that
468has at least one parent whose reachable graph is fully traversable in the sense
469required by 'git pack objects'.
470
21e5cfd8
AD
471* Look for a fix instead of a regression in the code
472+
473------------
474$ git bisect start
475$ git bisect new HEAD # current commit is marked as new
476$ git bisect old HEAD~10 # the tenth commit from now is marked as old
477------------
06e6a745
MM
478+
479or:
480------------
481$ git bisect start --term-old broken --term-new fixed
482$ git bisect fixed
483$ git bisect broken HEAD~10
484------------
21e5cfd8 485
c9493973
MM
486Getting help
487~~~~~~~~~~~~
488
489Use `git bisect` to get a short usage description, and `git bisect
490help` or `git bisect -h` to get a long usage description.
88d78911 491
69a9cd31
CC
492SEE ALSO
493--------
494link:git-bisect-lk2009.html[Fighting regressions with git bisect],
495linkgit:git-blame[1].
496
7fc9d69f
JH
497GIT
498---
9e1f0a85 499Part of the linkgit:git[1] suite