| blob | 1bc92153dc18ab6f95c8840ff6ca5a019c44e94e |
4 <head>
9 /* Debug borders */
11 /*
12 border: 1px solid red;
13 */
14 }
16 body {
18 }
20 a {
23 }
26 }
28 em {
31 }
33 strong {
36 }
38 tt {
40 }
48 }
52 }
53 h2 {
55 }
56 h3 {
58 }
59 h3 + * {
61 }
66 }
68 hr {
70 }
72 p {
75 }
79 }
81 pre {
84 }
86 span#author {
91 }
92 span#email {
93 }
96 }
98 div#footer {
104 }
105 div#footer-text {
108 }
109 div#footer-badges {
112 }
114 div#preamble {
117 }
123 }
127 }
131 }
133 /* Block element titles. */
141 }
144 }
148 }
151 }
154 }
160 }
166 }
171 }
175 }
180 }
183 }
187 }
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 }
200 }
204 }
209 }
215 dl {
218 }
219 dt {
224 }
227 }
231 }
234 }
237 }
240 }
243 }
246 }
253 }
257 }
258 thead {
261 }
262 tfoot {
264 }
267 }
270 }
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 }
278 }
282 }
288 }
291 }
294 }
300 }
303 }
307 }
311 }
315 }
317 div#toctitle {
324 }
329 }
333 }
337 }
341 }
342 /* Overrides for manpage documents */
343 h1 {
348 }
349 h2 {
351 }
354 }
358 }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
366 }
373 }
379 }
384 }
388 }
392 }
397 }
399 /* IE6 sets dynamically generated links as visited. */
401 </style>
402 </head>
403 <body>
405 <h1>
406 git-bisect(1) Manual Page
407 </h1>
410 <p>git-bisect -
411 Find by binary search the change that introduced a bug
412 </p>
413 </div>
414 </div>
420 </div></div>
421 </div>
424 <div class="paragraph"><p>The command takes various subcommands, and different options depending
425 on the subcommand:</p></div>
428 <pre><tt>git bisect help
434 git bisect visualize
436 git bisect log
438 </div></div>
440 binary search process to find which change introduced a bug, given an
445 <h3 id="_basic_bisect_commands_start_bad_good">Basic bisect commands: start, bad, good</h3><div style="clear:left"></div>
447 command is as follows:</p></div>
450 <pre><tt>$ git bisect start
451 $ git bisect bad # Current version is bad
453 # tested that was good</tt></pre>
454 </div></div>
456 command bisects the revision tree and outputs something similar to
457 the following:</p></div>
461 </div></div>
463 You would now compile that kernel and boot it. If the booted kernel
464 works correctly, you would then issue the following command:</p></div>
468 </div></div>
469 <div class="paragraph"><p>The output of this command would be something similar to the following:</p></div>
473 </div></div>
475 depending on whether it is good or bad issuing the command "git bisect good"
481 the original HEAD, issue the following command:</p></div>
485 </div></div>
488 that, as it cleans up the old bisection state.)</p></div>
490 instead:</p></div>
494 </div></div>
495 <div class="paragraph"><p>For example, <tt>git bisect reset HEAD</tt> will leave you on the current
496 bisection commit and avoid switching commits at all, while <tt>git bisect
499 <div class="paragraph"><p>To see the currently remaining suspects in <em>gitk</em>, issue the following
500 command during the bisection process:</p></div>
504 </div></div>
505 <div class="paragraph"><p><tt>view</tt> may also be used as a synonym for <tt>visualize</tt>.</p></div>
506 <div class="paragraph"><p>If the <em>DISPLAY</em> environment variable is not set, <em>git log</em> is used
512 </div></div>
513 <h3 id="_bisect_log_and_bisect_replay">Bisect log and bisect replay</h3><div style="clear:left"></div>
515 command to show what has been done so far:</p></div>
519 </div></div>
521 revision, you can save the output of this command to a file, edit it to
522 remove the incorrect entries, and then issue the following commands to
523 return to a corrected state:</p></div>
526 <pre><tt>$ git bisect reset
527 $ git bisect replay that-file</tt></pre>
528 </div></div>
529 <h3 id="_avoiding_testing_a_commit">Avoiding testing a commit</h3><div style="clear:left"></div>
530 <div class="paragraph"><p>If, in the middle of a bisect session, you know that the next suggested
531 revision is not a good one to test (e.g. the change the commit
532 introduces is known not to work in your environment and you know it
533 does not have anything to do with the bug you are chasing), you may
534 want to find a nearby commit and try that instead.</p></div>
538 <pre><tt>$ git bisect good/bad # previous round was good or bad.
539 Bisecting: 337 revisions left to test after this
540 $ git bisect visualize # oops, that is uninteresting.
542 # was suggested</tt></pre>
543 </div></div>
545 the revision as good or bad in the usual manner.</p></div>
548 to do it for you by issuing the command:</p></div>
552 </div></div>
554 a bad commit and one or more skipped commits.</p></div>
560 </div></div>
561 <div class="paragraph"><p>This tells the bisect process that no commit after <tt>v2.5</tt>, up to and
564 would issue the command:</p></div>
568 </div></div>
569 <div class="paragraph"><p>This tells the bisect process that the commits between <tt>v2.5</tt> included
571 <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>
572 <div class="paragraph"><p>You can further cut down the number of trials, if you know what part of
573 the tree is involved in the problem you are tracking down, by specifying
578 </div></div>
580 bisect space down by specifying all of the good commits immediately after
585 # v2.6.20-rc6 is bad
587 </div></div>
590 or bad, you can bisect by issuing the command:</p></div>
594 </div></div>
596 exit with code 0 if the current source code is good, and exit with a
598 source code is bad.</p></div>
603 cannot be tested. If the script exits with this code, the current
606 are used by POSIX shells to signal specific error status (127 is for
607 command not found, 126 is for command found but not executable---these
608 details do not matter, as they are normal errors in the script, as far as
612 header file, or "revision that does not have this commit needs this
613 patch applied to work around another problem this bisection is not
615 <div class="paragraph"><p>To cope with such a situation, after the inner <em>git bisect</em> finds the
616 next revision to test, the script can apply the patch
617 before compiling, run the real test, and afterwards decide if the
618 revision (possibly with the needed patch) passed the test and then
619 rewind the tree to the pristine state. Finally the script should exit
620 with the status of the real test to let the "git bisect run" command loop
621 determine the eventual outcome of the bisect session.</p></div>
622 </div>
627 --no-checkout
628 </dt>
629 <dd>
630 <div class="paragraph"><p>Do not checkout the new working tree at each iteration of the bisection
632 it point to the commit that should be tested.</p></div>
633 <div class="paragraph"><p>This option may be useful when the test you would perform in each step
634 does not require a checked out tree.</p></div>
635 <div class="paragraph"><p>If the repository is bare, <tt>--no-checkout</tt> is assumed.</p></div>
636 </dd>
637 </dl></div>
638 </div>
642 <li>
643 <p>
644 Automatically bisect a broken build between v1.2 and HEAD:
645 </p>
648 <pre><tt>$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
650 </div></div>
651 </li>
652 <li>
653 <p>
654 Automatically bisect a test failure between origin and HEAD:
655 </p>
658 <pre><tt>$ git bisect start HEAD origin -- # HEAD is bad, origin is good
660 </div></div>
661 </li>
662 <li>
663 <p>
664 Automatically bisect a broken test case:
665 </p>
668 <pre><tt>$ cat ~/test.sh
669 #!/bin/sh
670 make || exit 125 # this skips broken builds
671 ~/check_test_case.sh # does the test case pass?
673 $ git bisect run ~/test.sh</tt></pre>
674 </div></div>
676 fails, we skip the current commit.
680 outside the repository to prevent interactions between the bisect,
681 make and test processes and the scripts.</p></div>
682 </li>
683 <li>
684 <p>
685 Automatically bisect with temporary modifications (hot-fix):
686 </p>
689 <pre><tt>$ cat ~/test.sh
690 #!/bin/sh
692 # tweak the working tree by merging the hot-fix branch
693 # and then attempt a build
694 if git merge --no-commit hot-fix &&
695 make
696 then
697 # run project specific test and report its status
698 ~/check_test_case.sh
699 status=$?
700 else
701 # tell the caller this is untestable
702 status=125
703 fi
705 # undo the tweak to allow clean flipping to the next commit
706 git reset --hard
708 # return control
709 exit $status</tt></pre>
710 </div></div>
711 <div class="paragraph"><p>This applies modifications from a hot-fix branch before each test run,
712 e.g. in case your build or test environment changed so that older
713 revisions may need a fix which newer ones have already. (Make sure the
714 hot-fix branch is based off a commit which is contained in all revisions
715 which you are bisecting, so that the merge does not pull in too much, or
717 </li>
718 <li>
719 <p>
720 Automatically bisect a broken test case:
721 </p>
726 </div></div>
728 on a single line.</p></div>
729 </li>
730 <li>
731 <p>
732 Locate a good region of the object graph in a damaged repository
733 </p>
736 <pre><tt>$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
737 $ git bisect run sh -c '
741 rc=$?
742 rm -f tmp.$$
744 </div></div>
745 <div class="paragraph"><p>In this case, when <em>git bisect run</em> finishes, bisect/bad will refer to a commit that
746 has at least one parent whose reachable graph is fully traversable in the sense
748 </li>
749 </ul></div>
750 </div>
753 <div class="paragraph"><p><a href="git-bisect-lk2009.html">Fighting regressions with git bisect</a>,
755 </div>
759 </div>
763 </div>
764 </div>
765 </body>
766 </html>