1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.2.5" />
7 <style type=
"text/css">
9 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
11 border: 1px solid red;
16 margin: 1em 5% 1em 5%;
21 text-decoration: underline
;
39 h1
, h2
, h3
, h4
, h5
, h6
{
41 font-family: sans-serif
;
48 border-bottom: 2px solid silver
;
66 border: 1px solid silver
;
81 font-family: sans-serif
;
88 font-family: sans-serif
;
92 font-family: sans-serif
;
94 border-top: 2px solid silver
;
100 padding-bottom: 0.5em;
104 padding-bottom: 0.5em;
108 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
109 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
110 div
.admonitionblock
{
113 margin-bottom: 1.5em;
115 div
.admonitionblock
{
117 margin-bottom: 2.5em;
120 div
.content
{ /* Block element content. */
124 /* Block element titles. */
125 div
.title
, caption
.title
{
126 font-family: sans-serif
;
130 margin-bottom: 0.5em;
136 td div
.title:first-child
{
139 div
.content div
.title:first-child
{
142 div
.content
+ div
.title
{
146 div
.sidebarblock
> div
.content
{
148 border: 1px solid silver
;
155 div
.listingblock
> div
.content
{
156 border: 1px solid silver
;
161 div
.quoteblock
> div
.content
{
168 div
.verseblock
+ div
.attribution
{
172 div
.admonitionblock
.icon
{
176 text-decoration: underline
;
178 padding-right: 0.5em;
180 div
.admonitionblock td
.content
{
182 border-left: 2px solid silver
;
185 div
.exampleblock
> div
.content
{
186 border-left: 2px solid silver
;
190 div
.verseblock div
.content
{
194 div
.imageblock div
.content
{ padding-left: 0; }
195 div
.imageblock img
{ border: 1px solid silver
; }
196 span
.image img
{ border-style: none
; }
200 margin-bottom: 0.8em;
212 list-style-position: outside
;
215 list-style-type: lower-alpha
;
218 div
.tableblock
> table
{
219 border: 3px solid
#527bbd;
222 font-family: sans-serif
;
231 margin-bottom: 0.8em;
239 padding-right: 0.8em;
246 div#footer-badges
{ display: none
; }
251 font-family: sans-serif
;
255 margin-bottom: 0.1em;
258 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
274 include1::./stylesheets
/xhtml11-manpage
.css
[]
275 /* Workarounds for IE6's broken and incomplete CSS2. */
277 div
.sidebar-content
{
279 border: 1px solid silver
;
282 div
.sidebar-title
, div
.image-title
{
283 font-family: sans-serif
;
286 margin-bottom: 0.5em;
289 div
.listingblock div
.content
{
290 border: 1px solid silver
;
295 div
.quoteblock-content
{
299 div
.exampleblock-content
{
300 border-left: 2px solid silver
;
304 /* IE6 sets dynamically generated links as visited. */
305 div#toc
a:visited
{ color: blue
; }
307 <title>git-bisect(
1)
</title>
312 git-bisect(
1) Manual Page
315 <div class=
"sectionbody">
317 Find by binary search the change that introduced a bug
322 <div class=
"sectionbody">
323 <div class=
"para"><p><em>git bisect
</em> <subcommand
> <options
></p></div>
325 <h2 id=
"_description">DESCRIPTION
</h2>
326 <div class=
"sectionbody">
327 <div class=
"para"><p>The command takes various subcommands, and different options depending
328 on the subcommand:
</p></div>
329 <div class=
"literalblock">
330 <div class=
"content">
331 <pre><tt>git bisect help
332 git bisect start [
<bad
> [
<good
>...]] [--] [
<paths
>...]
333 git bisect bad [
<rev
>]
334 git bisect good [
<rev
>...]
335 git bisect skip [(
<rev
>|
<range
>)...]
336 git bisect reset [
<branch
>]
338 git bisect replay
<logfile
>
340 git bisect run
<cmd
>...
</tt></pre>
342 <div class=
"para"><p>This command uses
<em>git rev-list --bisect
</em> to help drive the
343 binary search process to find which change introduced a bug, given an
344 old
"good" commit object name and a later
"bad" commit object name.
</p></div>
345 <h3 id=
"_getting_help">Getting help
</h3><div style=
"clear:left"></div>
346 <div class=
"para"><p>Use
"git bisect" to get a short usage description, and
"git bisect
347 help" or
"git bisect -h" to get a long usage description.
</p></div>
348 <h3 id=
"_basic_bisect_commands_start_bad_good">Basic bisect commands: start, bad, good
</h3><div style=
"clear:left"></div>
349 <div class=
"para"><p>Using the Linux kernel tree as an example, basic use of the bisect
350 command is as follows:
</p></div>
351 <div class=
"listingblock">
352 <div class=
"content">
353 <pre><tt>$ git bisect start
354 $ git bisect bad # Current version is bad
355 $ git bisect good v2.6
.13-rc2 # v2.6
.13-rc2 was the last version
356 # tested that was good
</tt></pre>
358 <div class=
"para"><p>When you have specified at least one bad and one good version, the
359 command bisects the revision tree and outputs something similar to
360 the following:
</p></div>
361 <div class=
"listingblock">
362 <div class=
"content">
363 <pre><tt>Bisecting:
675 revisions left to test after this
</tt></pre>
365 <div class=
"para"><p>The state in the middle of the set of revisions is then checked out.
366 You would now compile that kernel and boot it. If the booted kernel
367 works correctly, you would then issue the following command:
</p></div>
368 <div class=
"listingblock">
369 <div class=
"content">
370 <pre><tt>$ git bisect good # this one is good
</tt></pre>
372 <div class=
"para"><p>The output of this command would be something similar to the following:
</p></div>
373 <div class=
"listingblock">
374 <div class=
"content">
375 <pre><tt>Bisecting:
337 revisions left to test after this
</tt></pre>
377 <div class=
"para"><p>You keep repeating this process, compiling the tree, testing it, and
378 depending on whether it is good or bad issuing the command
"git bisect good"
379 or
"git bisect bad" to ask for the next bisection.
</p></div>
380 <div class=
"para"><p>Eventually there will be no more revisions left to bisect, and you
381 will have been left with the first bad kernel revision in
"refs/bisect/bad".
</p></div>
382 <h3 id=
"_bisect_reset">Bisect reset
</h3><div style=
"clear:left"></div>
383 <div class=
"para"><p>To return to the original head after a bisect session, issue the
384 following command:
</p></div>
385 <div class=
"listingblock">
386 <div class=
"content">
387 <pre><tt>$ git bisect reset
</tt></pre>
389 <div class=
"para"><p>This resets the tree to the original branch instead of being on the
390 bisection commit (
"git bisect start" will also do that, as it resets
391 the bisection state).
</p></div>
392 <h3 id=
"_bisect_visualize">Bisect visualize
</h3><div style=
"clear:left"></div>
393 <div class=
"para"><p>To see the currently remaining suspects in
<em>gitk
</em>, issue the following
394 command during the bisection process:
</p></div>
395 <div class=
"listingblock">
396 <div class=
"content">
397 <pre><tt>$ git bisect visualize
</tt></pre>
399 <div class=
"para"><p><tt>view
</tt> may also be used as a synonym for
<tt>visualize
</tt>.
</p></div>
400 <div class=
"para"><p>If the
<em>DISPLAY
</em> environment variable is not set,
<em>git log
</em> is used
401 instead. You can also give command line options such as
<tt>-p
</tt> and
402 <tt>--stat
</tt>.
</p></div>
403 <div class=
"listingblock">
404 <div class=
"content">
405 <pre><tt>$ git bisect view --stat
</tt></pre>
407 <h3 id=
"_bisect_log_and_bisect_replay">Bisect log and bisect replay
</h3><div style=
"clear:left"></div>
408 <div class=
"para"><p>After having marked revisions as good or bad, issue the following
409 command to show what has been done so far:
</p></div>
410 <div class=
"listingblock">
411 <div class=
"content">
412 <pre><tt>$ git bisect log
</tt></pre>
414 <div class=
"para"><p>If you discover that you made a mistake in specifying the status of a
415 revision, you can save the output of this command to a file, edit it to
416 remove the incorrect entries, and then issue the following commands to
417 return to a corrected state:
</p></div>
418 <div class=
"listingblock">
419 <div class=
"content">
420 <pre><tt>$ git bisect reset
421 $ git bisect replay that-file
</tt></pre>
423 <h3 id=
"_avoiding_testing_a_commit">Avoiding testing a commit
</h3><div style=
"clear:left"></div>
424 <div class=
"para"><p>If, in the middle of a bisect session, you know that the next suggested
425 revision is not a good one to test (e.g. the change the commit
426 introduces is known not to work in your environment and you know it
427 does not have anything to do with the bug you are chasing), you may
428 want to find a nearby commit and try that instead.
</p></div>
429 <div class=
"para"><p>For example:
</p></div>
430 <div class=
"listingblock">
431 <div class=
"content">
432 <pre><tt>$ git bisect good/bad # previous round was good or bad.
433 Bisecting:
337 revisions left to test after this
434 $ git bisect visualize # oops, that is uninteresting.
435 $ git reset --hard HEAD~
3 # try
3 revisions before what
436 # was suggested
</tt></pre>
438 <div class=
"para"><p>Then compile and test the chosen revision, and afterwards mark
439 the revision as good or bad in the usual manner.
</p></div>
440 <h3 id=
"_bisect_skip">Bisect skip
</h3><div style=
"clear:left"></div>
441 <div class=
"para"><p>Instead of choosing by yourself a nearby commit, you can ask git
442 to do it for you by issuing the command:
</p></div>
443 <div class=
"listingblock">
444 <div class=
"content">
445 <pre><tt>$ git bisect skip # Current version cannot be tested
</tt></pre>
447 <div class=
"para"><p>But computing the commit to test may be slower afterwards and git may
448 eventually not be able to tell the first bad commit among a bad commit
449 and one or more skipped commits.
</p></div>
450 <div class=
"para"><p>You can even skip a range of commits, instead of just one commit,
451 using the
"<em><commit1></em>..<em><commit2></em>" notation. For example:
</p></div>
452 <div class=
"listingblock">
453 <div class=
"content">
454 <pre><tt>$ git bisect skip v2.5..v2.6
</tt></pre>
456 <div class=
"para"><p>This tells the bisect process that no commit after
<tt>v2.5
</tt>, up to and
457 including
<tt>v2.6
</tt>, should be tested.
</p></div>
458 <div class=
"para"><p>Note that if you also want to skip the first commit of the range you
459 would issue the command:
</p></div>
460 <div class=
"listingblock">
461 <div class=
"content">
462 <pre><tt>$ git bisect skip v2.5 v2.5..v2.6
</tt></pre>
464 <div class=
"para"><p>This tells the bisect process that the commits between
<tt>v2.5
</tt> included
465 and
<tt>v2.6
</tt> included should be skipped.
</p></div>
466 <h3 id=
"_cutting_down_bisection_by_giving_more_parameters_to_bisect_start">Cutting down bisection by giving more parameters to bisect start
</h3><div style=
"clear:left"></div>
467 <div class=
"para"><p>You can further cut down the number of trials, if you know what part of
468 the tree is involved in the problem you are tracking down, by specifying
469 path parameters when issuing the
<tt>bisect start
</tt> command:
</p></div>
470 <div class=
"listingblock">
471 <div class=
"content">
472 <pre><tt>$ git bisect start -- arch/i386 include/asm-i386
</tt></pre>
474 <div class=
"para"><p>If you know beforehand more than one good commit, you can narrow the
475 bisect space down by specifying all of the good commits immediately after
476 the bad commit when issuing the
<tt>bisect start
</tt> command:
</p></div>
477 <div class=
"listingblock">
478 <div class=
"content">
479 <pre><tt>$ git bisect start v2.6
.20-rc6 v2.6
.20-rc4 v2.6
.20-rc1 --
481 # v2.6
.20-rc4 and v2.6
.20-rc1 are good
</tt></pre>
483 <h3 id=
"_bisect_run">Bisect run
</h3><div style=
"clear:left"></div>
484 <div class=
"para"><p>If you have a script that can tell if the current source code is good
485 or bad, you can bisect by issuing the command:
</p></div>
486 <div class=
"listingblock">
487 <div class=
"content">
488 <pre><tt>$ git bisect run my_script arguments
</tt></pre>
490 <div class=
"para"><p>Note that the script (
<tt>my_script
</tt> in the above example) should
491 exit with code
0 if the current source code is good, and exit with a
492 code between
1 and
127 (inclusive), except
125, if the current
493 source code is bad.
</p></div>
494 <div class=
"para"><p>Any other exit code will abort the bisect process. It should be noted
495 that a program that terminates via
"exit(-1)" leaves $? =
255, (see the
496 exit(
3) manual page), as the value is chopped with
"& 0377".
</p></div>
497 <div class=
"para"><p>The special exit code
125 should be used when the current source code
498 cannot be tested. If the script exits with this code, the current
499 revision will be skipped (see
<tt>git bisect skip
</tt> above).
</p></div>
500 <div class=
"para"><p>You may often find that during a bisect session you want to have
501 temporary modifications (e.g. s/#define DEBUG
0/#define DEBUG
1/ in a
502 header file, or
"revision that does not have this commit needs this
503 patch applied to work around another problem this bisection is not
504 interested in") applied to the revision being tested.
</p></div>
505 <div class=
"para"><p>To cope with such a situation, after the inner
<em>git bisect
</em> finds the
506 next revision to test, the script can apply the patch
507 before compiling, run the real test, and afterwards decide if the
508 revision (possibly with the needed patch) passed the test and then
509 rewind the tree to the pristine state. Finally the script should exit
510 with the status of the real test to let the
"git bisect run" command loop
511 determine the eventual outcome of the bisect session.
</p></div>
513 <h2 id=
"_examples">EXAMPLES
</h2>
514 <div class=
"sectionbody">
515 <div class=
"ilist"><ul>
518 Automatically bisect a broken build between v1.2 and HEAD:
520 <div class=
"listingblock">
521 <div class=
"content">
522 <pre><tt>$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
523 $ git bisect run make #
"make" builds the app
</tt></pre>
528 Automatically bisect a test failure between origin and HEAD:
530 <div class=
"listingblock">
531 <div class=
"content">
532 <pre><tt>$ git bisect start HEAD origin -- # HEAD is bad, origin is good
533 $ git bisect run make test #
"make test" builds and tests
</tt></pre>
538 Automatically bisect a broken test suite:
540 <div class=
"listingblock">
541 <div class=
"content">
542 <pre><tt>$ cat ~/test.sh
544 make || exit
125 # this skips broken builds
545 make test #
"make test" runs the test suite
546 $ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good
547 $ git bisect run ~/test.sh
</tt></pre>
549 <div class=
"para"><p>Here we use a
"test.sh" custom script. In this script, if
"make"
550 fails, we skip the current commit.
</p></div>
551 <div class=
"para"><p>It is safer to use a custom script outside the repository to prevent
552 interactions between the bisect, make and test processes and the
554 <div class=
"para"><p>"make test" should
"exit 0", if the test suite passes, and
555 "exit 1" otherwise.
</p></div>
559 Automatically bisect a broken test case:
561 <div class=
"listingblock">
562 <div class=
"content">
563 <pre><tt>$ cat ~/test.sh
565 make || exit
125 # this skips broken builds
566 ~/check_test_case.sh # does the test case passes ?
567 $ git bisect start HEAD HEAD~
10 -- # culprit is among the last
10
568 $ git bisect run ~/test.sh
</tt></pre>
570 <div class=
"para"><p>Here
"check_test_case.sh" should
"exit 0" if the test case passes,
571 and
"exit 1" otherwise.
</p></div>
572 <div class=
"para"><p>It is safer if both
"test.sh" and
"check_test_case.sh" scripts are
573 outside the repository to prevent interactions between the bisect,
574 make and test processes and the scripts.
</p></div>
578 Automatically bisect a broken test suite:
580 <div class=
"listingblock">
581 <div class=
"content">
582 <pre><tt>$ git bisect start HEAD HEAD~
10 -- # culprit is among the last
10
583 $ git bisect run sh -c
"make || exit 125; ~/check_test_case.sh"</tt></pre>
585 <div class=
"para"><p>Does the same as the previous example, but on a single line.
</p></div>
589 <h2 id=
"_author">Author
</h2>
590 <div class=
"sectionbody">
591 <div class=
"para"><p>Written by Linus Torvalds
<torvalds@osdl.org
></p></div>
593 <h2 id=
"_documentation">Documentation
</h2>
594 <div class=
"sectionbody">
595 <div class=
"para"><p>Documentation by Junio C Hamano and the git-list
<git@vger.kernel.org
>.
</p></div>
597 <h2 id=
"_git">GIT
</h2>
598 <div class=
"sectionbody">
599 <div class=
"para"><p>Part of the
<a href=
"git.html">git(
1)
</a> suite
</p></div>
602 <div id=
"footer-text">
603 Last updated
2009-
04-
02 06:
49:
45 UTC