freshlybakedca.ke
Git fork
1git-bisect(1)
2=============
3
4NAME
5----
6git-bisect - Use binary search to find the commit that introduced a bug
7
8
9SYNOPSIS
10--------
11[verse]
12'git bisect' <subcommand> <options>
13
14DESCRIPTION
15-----------
16The command takes various subcommands, and different options depending
17on the subcommand:
18
19 git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
20 [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
21 git bisect (bad|new|<term-new>) [<rev>]
22 git bisect (good|old|<term-old>) [<rev>...]
23 git bisect terms [--term-(good|old) | --term-(bad|new)]
24 git bisect skip [(<rev>|<range>)...]
25 git bisect reset [<commit>]
26 git bisect (visualize|view)
27 git bisect replay <logfile>
28 git bisect log
29 git bisect run <cmd> [<arg>...]
30 git bisect help
31
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.
40
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
45in place of "good" and "bad", or you can choose your own terms. See
46section "Alternate terms" below for more information.
47
48Basic bisect commands: start, bad, good
49~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50
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:
54
55------------------------------------------------
56$ git bisect start
57$ git bisect bad # Current version is bad
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)
67------------------------------------------------
68
69You should now compile the checked-out version and test it. If that
70version works correctly, type
71
72------------------------------------------------
73$ git bisect good
74------------------------------------------------
75
76If that version is broken, type
77
78------------------------------------------------
79$ git bisect bad
80------------------------------------------------
81
82Then `git bisect` will respond with something like
83
84------------------------------------------------
85Bisecting: 337 revisions left to test after this (roughly 9 steps)
86------------------------------------------------
87
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.
95
96
97Bisect reset
98~~~~~~~~~~~~
99
100After a bisect session, to clean up the bisection state and return to
101the original HEAD, issue the following command:
102
103------------------------------------------------
104$ git bisect reset
105------------------------------------------------
106
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
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
122
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"
140commit that has some property and an "old" commit that doesn't have that
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
162To get a reminder of the currently used terms, use
163
164------------------------------------------------
165git bisect terms
166------------------------------------------------
167
168You can get just the old term with `git bisect terms --term-old`
169or `git bisect terms --term-good`; `git bisect terms --term-new`
170and `git bisect terms --term-bad` can be used to learn how to call
171the commits more recent than the sought change.
172
173If you would like to use your own terms instead of "bad"/"good" or
174"new"/"old", you can choose any names you like (except existing bisect
175subcommands like `reset`, `start`, ...) by starting the
176bisection using
177
178------------------------------------------------
179git bisect start --term-old <term-old> --term-new <term-new>
180------------------------------------------------
181
182For example, if you are looking for a commit that introduced a
183performance regression, you might use
184
185------------------------------------------------
186git bisect start --term-old fast --term-new slow
187------------------------------------------------
188
189Or if you are looking for the commit that fixed a bug, you might use
190
191------------------------------------------------
192git bisect start --term-new fixed --term-old broken
193------------------------------------------------
194
195Then, use `git bisect <term-old>` and `git bisect <term-new>` instead
196of `git bisect good` and `git bisect bad` to mark commits.
197
198Bisect visualize/view
199~~~~~~~~~~~~~~~~~~~~~
200
201To see the currently remaining suspects in 'gitk', issue the following
202command during the bisection process (the subcommand `view` can be used
203as an alternative to `visualize`):
204
205------------
206$ git bisect visualize
207------------
208
209Git detects a graphical environment through various environment variables:
210`DISPLAY`, which is set in X Window System environments on Unix systems.
211`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions.
212`MSYSTEM`, which is set under Msys2 and Git for Windows.
213`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions.
214
215If none of these environment variables is set, 'git log' is used instead.
216You can also give command-line options such as `-p` and `--stat`.
217
218------------
219$ git bisect visualize --stat
220------------
221
222Bisect log and bisect replay
223~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224
225After having marked revisions as good or bad, issue the following
226command to show what has been done so far:
227
228------------
229$ git bisect log
230------------
231
232If you discover that you made a mistake in specifying the status of a
233revision, you can save the output of this command to a file, edit it to
234remove the incorrect entries, and then issue the following commands to
235return to a corrected state:
236
237------------
238$ git bisect reset
239$ git bisect replay that-file
240------------
241
242Avoiding testing a commit
243~~~~~~~~~~~~~~~~~~~~~~~~~
244
245If, in the middle of a bisect session, you know that the suggested
246revision is not a good one to test (e.g. it fails to build and you
247know that the failure does not have anything to do with the bug you
248are chasing), you can manually select a nearby commit and test that
249one instead.
250
251For example:
252
253------------
254$ git bisect good/bad # previous round was good or bad.
255Bisecting: 337 revisions left to test after this (roughly 9 steps)
256$ git bisect visualize # oops, that is uninteresting.
257$ git reset --hard HEAD~3 # try 3 revisions before what
258 # was suggested
259------------
260
261Then compile and test the chosen revision, and afterwards mark
262the revision as good or bad in the usual manner.
263
264Bisect skip
265~~~~~~~~~~~
266
267Instead of choosing a nearby commit by yourself, you can ask Git to do
268it for you by issuing the command:
269
270------------
271$ git bisect skip # Current version cannot be tested
272------------
273
274However, if you skip a commit adjacent to the one you are looking for,
275Git will be unable to tell exactly which of those commits was the
276first bad one.
277
278You can also skip a range of commits, instead of just one commit,
279using range notation. For example:
280
281------------
282$ git bisect skip v2.5..v2.6
283------------
284
285This tells the bisect process that no commit after `v2.5`, up to and
286including `v2.6`, should be tested.
287
288Note that if you also want to skip the first commit of the range you
289would issue the command:
290
291------------
292$ git bisect skip v2.5 v2.5..v2.6
293------------
294
295This tells the bisect process that the commits between `v2.5` and
296`v2.6` (inclusive) should be skipped.
297
298
299Cutting down bisection by giving more parameters to bisect start
300~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
301
302You can further cut down the number of trials, if you know what part of
303the tree is involved in the problem you are tracking down, by specifying
304pathspec parameters when issuing the `bisect start` command:
305
306------------
307$ git bisect start -- arch/i386 include/asm-i386
308------------
309
310If you know beforehand more than one good commit, you can narrow the
311bisect space down by specifying all of the good commits immediately after
312the bad commit when issuing the `bisect start` command:
313
314------------
315$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
316 # v2.6.20-rc6 is bad
317 # v2.6.20-rc4 and v2.6.20-rc1 are good
318------------
319
320Bisect run
321~~~~~~~~~~
322
323If you have a script that can tell if the current source code is good
324or bad, you can bisect by issuing the command:
325
326------------
327$ git bisect run my_script arguments
328------------
329
330Note that the script (`my_script` in the above example) should exit
331with code 0 if the current source code is good/old, and exit with a
332code between 1 and 127 (inclusive), except 125, if the current source
333code is bad/new.
334
335Any other exit code will abort the bisect process. It should be noted
336that a program that terminates via `exit(-1)` leaves $? = 255, (see the
337exit(3) manual page), as the value is chopped with `& 0377`.
338
339The special exit code 125 should be used when the current source code
340cannot be tested. If the script exits with this code, the current
341revision will be skipped (see `git bisect skip` above). 125 was chosen
342as the highest sensible value to use for this purpose, because 126 and 127
343are used by POSIX shells to signal specific error status (127 is for
344command not found, 126 is for command found but not executable--these
345details do not matter, as they are normal errors in the script, as far as
346`bisect run` is concerned).
347
348You may often find that during a bisect session you want to have
349temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
350header file, or "revision that does not have this commit needs this
351patch applied to work around another problem this bisection is not
352interested in") applied to the revision being tested.
353
354To cope with such a situation, after the inner 'git bisect' finds the
355next revision to test, the script can apply the patch
356before compiling, run the real test, and afterwards decide if the
357revision (possibly with the needed patch) passed the test and then
358rewind the tree to the pristine state. Finally the script should exit
359with the status of the real test to let the `git bisect run` command loop
360determine the eventual outcome of the bisect session.
361
362OPTIONS
363-------
364--no-checkout::
365+
366Do not checkout the new working tree at each iteration of the bisection
367process. Instead just update the reference named `BISECT_HEAD` to make
368it point to the commit that should be tested.
369+
370This option may be useful when the test you would perform in each step
371does not require a checked out tree.
372+
373If the repository is bare, `--no-checkout` is assumed.
374
375--first-parent::
376+
377Follow only the first parent commit upon seeing a merge commit.
378+
379In detecting regressions introduced through the merging of a branch, the merge
380commit will be identified as introduction of the bug and its ancestors will be
381ignored.
382+
383This option is particularly useful in avoiding false positives when a merged
384branch contained broken or non-buildable commits, but the merge itself was OK.
385
386EXAMPLES
387--------
388
389* Automatically bisect a broken build between v1.2 and HEAD:
390+
391------------
392$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
393$ git bisect run make # "make" builds the app
394$ git bisect reset # quit the bisect session
395------------
396
397* Automatically bisect a test failure between origin and HEAD:
398+
399------------
400$ git bisect start HEAD origin -- # HEAD is bad, origin is good
401$ git bisect run make test # "make test" builds and tests
402$ git bisect reset # quit the bisect session
403------------
404
405* Automatically bisect a broken test case:
406+
407------------
408$ cat ~/test.sh
409#!/bin/sh
410make || exit 125 # this skips broken builds
411~/check_test_case.sh # does the test case pass?
412$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
413$ git bisect run ~/test.sh
414$ git bisect reset # quit the bisect session
415------------
416+
417Here we use a `test.sh` custom script. In this script, if `make`
418fails, we skip the current commit.
419`check_test_case.sh` should `exit 0` if the test case passes,
420and `exit 1` otherwise.
421+
422It is safer if both `test.sh` and `check_test_case.sh` are
423outside the repository to prevent interactions between the bisect,
424make and test processes and the scripts.
425
426* Automatically bisect with temporary modifications (hot-fix):
427+
428------------
429$ cat ~/test.sh
430#!/bin/sh
431
432# tweak the working tree by merging the hot-fix branch
433# and then attempt a build
434if git merge --no-commit --no-ff hot-fix &&
435 make
436then
437 # run project specific test and report its status
438 ~/check_test_case.sh
439 status=$?
440else
441 # tell the caller this is untestable
442 status=125
443fi
444
445# undo the tweak to allow clean flipping to the next commit
446git reset --hard
447
448# return control
449exit $status
450------------
451+
452This applies modifications from a hot-fix branch before each test run,
453e.g. in case your build or test environment changed so that older
454revisions may need a fix which newer ones have already. (Make sure the
455hot-fix branch is based off a commit which is contained in all revisions
456which you are bisecting, so that the merge does not pull in too much, or
457use `git cherry-pick` instead of `git merge`.)
458
459* Automatically bisect a broken test case:
460+
461------------
462$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
463$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
464$ git bisect reset # quit the bisect session
465------------
466+
467This shows that you can do without a run script if you write the test
468on a single line.
469
470* Locate a good region of the object graph in a damaged repository
471+
472------------
473$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
474$ git bisect run sh -c '
475 GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
476 git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
477 git pack-objects --stdout >/dev/null <tmp.$$
478 rc=$?
479 rm -f tmp.$$
480 test $rc = 0'
481
482$ git bisect reset # quit the bisect session
483------------
484+
485In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that
486has at least one parent whose reachable graph is fully traversable in the sense
487required by 'git pack objects'.
488
489* Look for a fix instead of a regression in the code
490+
491------------
492$ git bisect start
493$ git bisect new HEAD # current commit is marked as new
494$ git bisect old HEAD~10 # the tenth commit from now is marked as old
495------------
496+
497or:
498+
499------------
500$ git bisect start --term-old broken --term-new fixed
501$ git bisect fixed
502$ git bisect broken HEAD~10
503------------
504
505Getting help
506~~~~~~~~~~~~
507
508Use `git bisect` to get a short usage description, and `git bisect
509help` or `git bisect -h` to get a long usage description.
510
511SEE ALSO
512--------
513link:git-bisect-lk2009.html[Fighting regressions with git bisect],
514linkgit:git-blame[1].
515
516GIT
517---
518Part of the linkgit:git[1] suite