git-bisect.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
   7 <meta name="generator" content="AsciiDoc 10.2.0" />
   8 <title>git-bisect(1)</title>
   9 <style type="text/css">
  10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
  11
  12 /* Default font. */
  13 body {
  14   font-family: Georgia,serif;
  15 }
  16
  17 /* Title font. */
  18 h1, h2, h3, h4, h5, h6,
  19 div.title, caption.title,
  20 thead, p.table.header,
  21 #toctitle,
  22 #author, #revnumber, #revdate, #revremark,
  23 #footer {
  24   font-family: Arial,Helvetica,sans-serif;
  25 }
  26
  27 body {
  28   margin: 1em 5% 1em 5%;
  29 }
  30
  31 a {
  32   color: blue;
  33   text-decoration: underline;
  34 }
  35 a:visited {
  36   color: fuchsia;
  37 }
  38
  39 em {
  40   font-style: italic;
  41   color: navy;
  42 }
  43
  44 strong {
  45   font-weight: bold;
  46   color: #083194;
  47 }
  48
  49 h1, h2, h3, h4, h5, h6 {
  50   color: #527bbd;
  51   margin-top: 1.2em;
  52   margin-bottom: 0.5em;
  53   line-height: 1.3;
  54 }
  55
  56 h1, h2, h3 {
  57   border-bottom: 2px solid silver;
  58 }
  59 h2 {
  60   padding-top: 0.5em;
  61 }
  62 h3 {
  63   float: left;
  64 }
  65 h3 + * {
  66   clear: left;
  67 }
  68 h5 {
  69   font-size: 1.0em;
  70 }
  71
  72 div.sectionbody {
  73   margin-left: 0;
  74 }
  75
  76 hr {
  77   border: 1px solid silver;
  78 }
  79
  80 p {
  81   margin-top: 0.5em;
  82   margin-bottom: 0.5em;
  83 }
  84
  85 ul, ol, li > p {
  86   margin-top: 0;
  87 }
  88 ul > li     { color: #aaa; }
  89 ul > li > * { color: black; }
  90
  91 .monospaced, code, pre {
  92   font-family: "Courier New", Courier, monospace;
  93   font-size: inherit;
  94   color: navy;
  95   padding: 0;
  96   margin: 0;
  97 }
  98 pre {
  99   white-space: pre-wrap;
 100 }
 101
 102 #author {
 103   color: #527bbd;
 104   font-weight: bold;
 105   font-size: 1.1em;
 106 }
 107 #email {
 108 }
 109 #revnumber, #revdate, #revremark {
 110 }
 111
 112 #footer {
 113   font-size: small;
 114   border-top: 2px solid silver;
 115   padding-top: 0.5em;
 116   margin-top: 4.0em;
 117 }
 118 #footer-text {
 119   float: left;
 120   padding-bottom: 0.5em;
 121 }
 122 #footer-badges {
 123   float: right;
 124   padding-bottom: 0.5em;
 125 }
 126
 127 #preamble {
 128   margin-top: 1.5em;
 129   margin-bottom: 1.5em;
 130 }
 131 div.imageblock, div.exampleblock, div.verseblock,
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 133 div.admonitionblock {
 134   margin-top: 1.0em;
 135   margin-bottom: 1.5em;
 136 }
 137 div.admonitionblock {
 138   margin-top: 2.0em;
 139   margin-bottom: 2.0em;
 140   margin-right: 10%;
 141   color: #606060;
 142 }
 143
 144 div.content { /* Block element content. */
 145   padding: 0;
 146 }
 147
 148 /* Block element titles. */
 149 div.title, caption.title {
 150   color: #527bbd;
 151   font-weight: bold;
 152   text-align: left;
 153   margin-top: 1.0em;
 154   margin-bottom: 0.5em;
 155 }
 156 div.title + * {
 157   margin-top: 0;
 158 }
 159
 160 td div.title:first-child {
 161   margin-top: 0.0em;
 162 }
 163 div.content div.title:first-child {
 164   margin-top: 0.0em;
 165 }
 166 div.content + div.title {
 167   margin-top: 0.0em;
 168 }
 169
 170 div.sidebarblock > div.content {
 171   background: #ffffee;
 172   border: 1px solid #dddddd;
 173   border-left: 4px solid #f0f0f0;
 174   padding: 0.5em;
 175 }
 176
 177 div.listingblock > div.content {
 178   border: 1px solid #dddddd;
 179   border-left: 5px solid #f0f0f0;
 180   background: #f8f8f8;
 181   padding: 0.5em;
 182 }
 183
 184 div.quoteblock, div.verseblock {
 185   padding-left: 1.0em;
 186   margin-left: 1.0em;
 187   margin-right: 10%;
 188   border-left: 5px solid #f0f0f0;
 189   color: #888;
 190 }
 191
 192 div.quoteblock > div.attribution {
 193   padding-top: 0.5em;
 194   text-align: right;
 195 }
 196
 197 div.verseblock > pre.content {
 198   font-family: inherit;
 199   font-size: inherit;
 200 }
 201 div.verseblock > div.attribution {
 202   padding-top: 0.75em;
 203   text-align: left;
 204 }
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 206 div.verseblock + div.attribution {
 207   text-align: left;
 208 }
 209
 210 div.admonitionblock .icon {
 211   vertical-align: top;
 212   font-size: 1.1em;
 213   font-weight: bold;
 214   text-decoration: underline;
 215   color: #527bbd;
 216   padding-right: 0.5em;
 217 }
 218 div.admonitionblock td.content {
 219   padding-left: 0.5em;
 220   border-left: 3px solid #dddddd;
 221 }
 222
 223 div.exampleblock > div.content {
 224   border-left: 3px solid #dddddd;
 225   padding-left: 0.5em;
 226 }
 227
 228 div.imageblock div.content { padding-left: 0; }
 229 span.image img { border-style: none; vertical-align: text-bottom; }
 230 a.image:visited { color: white; }
 231
 232 dl {
 233   margin-top: 0.8em;
 234   margin-bottom: 0.8em;
 235 }
 236 dt {
 237   margin-top: 0.5em;
 238   margin-bottom: 0;
 239   font-style: normal;
 240   color: navy;
 241 }
 242 dd > *:first-child {
 243   margin-top: 0.1em;
 244 }
 245
 246 ul, ol {
 247     list-style-position: outside;
 248 }
 249 ol.arabic {
 250   list-style-type: decimal;
 251 }
 252 ol.loweralpha {
 253   list-style-type: lower-alpha;
 254 }
 255 ol.upperalpha {
 256   list-style-type: upper-alpha;
 257 }
 258 ol.lowerroman {
 259   list-style-type: lower-roman;
 260 }
 261 ol.upperroman {
 262   list-style-type: upper-roman;
 263 }
 264
 265 div.compact ul, div.compact ol,
 266 div.compact p, div.compact p,
 267 div.compact div, div.compact div {
 268   margin-top: 0.1em;
 269   margin-bottom: 0.1em;
 270 }
 271
 272 tfoot {
 273   font-weight: bold;
 274 }
 275 td > div.verse {
 276   white-space: pre;
 277 }
 278
 279 div.hdlist {
 280   margin-top: 0.8em;
 281   margin-bottom: 0.8em;
 282 }
 283 div.hdlist tr {
 284   padding-bottom: 15px;
 285 }
 286 dt.hdlist1.strong, td.hdlist1.strong {
 287   font-weight: bold;
 288 }
 289 td.hdlist1 {
 290   vertical-align: top;
 291   font-style: normal;
 292   padding-right: 0.8em;
 293   color: navy;
 294 }
 295 td.hdlist2 {
 296   vertical-align: top;
 297 }
 298 div.hdlist.compact tr {
 299   margin: 0;
 300   padding-bottom: 0;
 301 }
 302
 303 .comment {
 304   background: yellow;
 305 }
 306
 307 .footnote, .footnoteref {
 308   font-size: 0.8em;
 309 }
 310
 311 span.footnote, span.footnoteref {
 312   vertical-align: super;
 313 }
 314
 315 #footnotes {
 316   margin: 20px 0 20px 0;
 317   padding: 7px 0 0 0;
 318 }
 319
 320 #footnotes div.footnote {
 321   margin: 0 0 5px 0;
 322 }
 323
 324 #footnotes hr {
 325   border: none;
 326   border-top: 1px solid silver;
 327   height: 1px;
 328   text-align: left;
 329   margin-left: 0;
 330   width: 20%;
 331   min-width: 100px;
 332 }
 333
 334 div.colist td {
 335   padding-right: 0.5em;
 336   padding-bottom: 0.3em;
 337   vertical-align: top;
 338 }
 339 div.colist td img {
 340   margin-top: 0.3em;
 341 }
 342
 343 @media print {
 344   #footer-badges { display: none; }
 345 }
 346
 347 #toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 #toctitle {
 352   color: #527bbd;
 353   font-size: 1.1em;
 354   font-weight: bold;
 355   margin-top: 1.0em;
 356   margin-bottom: 0.1em;
 357 }
 358
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 360   margin-top: 0;
 361   margin-bottom: 0;
 362 }
 363 div.toclevel2 {
 364   margin-left: 2em;
 365   font-size: 0.9em;
 366 }
 367 div.toclevel3 {
 368   margin-left: 4em;
 369   font-size: 0.9em;
 370 }
 371 div.toclevel4 {
 372   margin-left: 6em;
 373   font-size: 0.9em;
 374 }
 375
 376 span.aqua { color: aqua; }
 377 span.black { color: black; }
 378 span.blue { color: blue; }
 379 span.fuchsia { color: fuchsia; }
 380 span.gray { color: gray; }
 381 span.green { color: green; }
 382 span.lime { color: lime; }
 383 span.maroon { color: maroon; }
 384 span.navy { color: navy; }
 385 span.olive { color: olive; }
 386 span.purple { color: purple; }
 387 span.red { color: red; }
 388 span.silver { color: silver; }
 389 span.teal { color: teal; }
 390 span.white { color: white; }
 391 span.yellow { color: yellow; }
 392
 393 span.aqua-background { background: aqua; }
 394 span.black-background { background: black; }
 395 span.blue-background { background: blue; }
 396 span.fuchsia-background { background: fuchsia; }
 397 span.gray-background { background: gray; }
 398 span.green-background { background: green; }
 399 span.lime-background { background: lime; }
 400 span.maroon-background { background: maroon; }
 401 span.navy-background { background: navy; }
 402 span.olive-background { background: olive; }
 403 span.purple-background { background: purple; }
 404 span.red-background { background: red; }
 405 span.silver-background { background: silver; }
 406 span.teal-background { background: teal; }
 407 span.white-background { background: white; }
 408 span.yellow-background { background: yellow; }
 409
 410 span.big { font-size: 2em; }
 411 span.small { font-size: 0.6em; }
 412
 413 span.underline { text-decoration: underline; }
 414 span.overline { text-decoration: overline; }
 415 span.line-through { text-decoration: line-through; }
 416
 417 div.unbreakable { page-break-inside: avoid; }
 418
 419
 420 /*
 421  * xhtml11 specific
 422  *
 423  * */
 424
 425 div.tableblock {
 426   margin-top: 1.0em;
 427   margin-bottom: 1.5em;
 428 }
 429 div.tableblock > table {
 430   border: 3px solid #527bbd;
 431 }
 432 thead, p.table.header {
 433   font-weight: bold;
 434   color: #527bbd;
 435 }
 436 p.table {
 437   margin-top: 0;
 438 }
 439 /* Because the table frame attribute is overridden by CSS in most browsers. */
 440 div.tableblock > table[frame="void"] {
 441   border-style: none;
 442 }
 443 div.tableblock > table[frame="hsides"] {
 444   border-left-style: none;
 445   border-right-style: none;
 446 }
 447 div.tableblock > table[frame="vsides"] {
 448   border-top-style: none;
 449   border-bottom-style: none;
 450 }
 451
 452
 453 /*
 454  * html5 specific
 455  *
 456  * */
 457
 458 table.tableblock {
 459   margin-top: 1.0em;
 460   margin-bottom: 1.5em;
 461 }
 462 thead, p.tableblock.header {
 463   font-weight: bold;
 464   color: #527bbd;
 465 }
 466 p.tableblock {
 467   margin-top: 0;
 468 }
 469 table.tableblock {
 470   border-width: 3px;
 471   border-spacing: 0px;
 472   border-style: solid;
 473   border-color: #527bbd;
 474   border-collapse: collapse;
 475 }
 476 th.tableblock, td.tableblock {
 477   border-width: 1px;
 478   padding: 4px;
 479   border-style: solid;
 480   border-color: #527bbd;
 481 }
 482
 483 table.tableblock.frame-topbot {
 484   border-left-style: hidden;
 485   border-right-style: hidden;
 486 }
 487 table.tableblock.frame-sides {
 488   border-top-style: hidden;
 489   border-bottom-style: hidden;
 490 }
 491 table.tableblock.frame-none {
 492   border-style: hidden;
 493 }
 494
 495 th.tableblock.halign-left, td.tableblock.halign-left {
 496   text-align: left;
 497 }
 498 th.tableblock.halign-center, td.tableblock.halign-center {
 499   text-align: center;
 500 }
 501 th.tableblock.halign-right, td.tableblock.halign-right {
 502   text-align: right;
 503 }
 504
 505 th.tableblock.valign-top, td.tableblock.valign-top {
 506   vertical-align: top;
 507 }
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {
 509   vertical-align: middle;
 510 }
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 512   vertical-align: bottom;
 513 }
 514
 515
 516 /*
 517  * manpage specific
 518  *
 519  * */
 520
 521 body.manpage h1 {
 522   padding-top: 0.5em;
 523   padding-bottom: 0.5em;
 524   border-top: 2px solid silver;
 525   border-bottom: 2px solid silver;
 526 }
 527 body.manpage h2 {
 528   border-style: none;
 529 }
 530 body.manpage div.sectionbody {
 531   margin-left: 3em;
 532 }
 533
 534 @media print {
 535   body.manpage div#toc { display: none; }
 536 }
 537
 538
 539 </style>
 540 <script type="text/javascript">
 541 /*<![CDATA[*/
 542 var asciidoc = {  // Namespace.
 543
 544 /////////////////////////////////////////////////////////////////////
 545 // Table Of Contents generator
 546 /////////////////////////////////////////////////////////////////////
 547
 548 /* Author: Mihai Bazon, September 2002
 549  * http://students.infoiasi.ro/~mishoo
 550  *
 551  * Table Of Content generator
 552  * Version: 0.4
 553  *
 554  * Feel free to use this script under the terms of the GNU General Public
 555  * License, as long as you do not remove or alter this notice.
 556  */
 557
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 560
 561 // toclevels = 1..4.
 562 toc: function (toclevels) {
 563
 564   function getText(el) {
 565     var text = "";
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 568         text += i.data;
 569       else if (i.firstChild != null)
 570         text += getText(i);
 571     }
 572     return text;
 573   }
 574
 575   function TocEntry(el, text, toclevel) {
 576     this.element = el;
 577     this.text = text;
 578     this.toclevel = toclevel;
 579   }
 580
 581   function tocEntries(el, toclevels) {
 582     var result = new Array;
 583     var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
 584     // Function that scans the DOM tree for header elements (the DOM2
 585     // nodeIterator API would be a better technique but not supported by all
 586     // browsers).
 587     var iterate = function (el) {
 588       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 589         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 590           var mo = re.exec(i.tagName);
 591           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 592             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 593           }
 594           iterate(i);
 595         }
 596       }
 597     }
 598     iterate(el);
 599     return result;
 600   }
 601
 602   var toc = document.getElementById("toc");
 603   if (!toc) {
 604     return;
 605   }
 606
 607   // Delete existing TOC entries in case we're reloading the TOC.
 608   var tocEntriesToRemove = [];
 609   var i;
 610   for (i = 0; i < toc.childNodes.length; i++) {
 611     var entry = toc.childNodes[i];
 612     if (entry.nodeName.toLowerCase() == 'div'
 613      && entry.getAttribute("class")
 614      && entry.getAttribute("class").match(/^toclevel/))
 615       tocEntriesToRemove.push(entry);
 616   }
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {
 618     toc.removeChild(tocEntriesToRemove[i]);
 619   }
 620
 621   // Rebuild TOC entries.
 622   var entries = tocEntries(document.getElementById("content"), toclevels);
 623   for (var i = 0; i < entries.length; ++i) {
 624     var entry = entries[i];
 625     if (entry.element.id == "")
 626       entry.element.id = "_toc_" + i;
 627     var a = document.createElement("a");
 628     a.href = "#" + entry.element.id;
 629     a.appendChild(document.createTextNode(entry.text));
 630     var div = document.createElement("div");
 631     div.appendChild(a);
 632     div.className = "toclevel" + entry.toclevel;
 633     toc.appendChild(div);
 634   }
 635   if (entries.length == 0)
 636     toc.parentNode.removeChild(toc);
 637 },
 638
 639
 640 /////////////////////////////////////////////////////////////////////
 641 // Footnotes generator
 642 /////////////////////////////////////////////////////////////////////
 643
 644 /* Based on footnote generation code from:
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 646  */
 647
 648 footnotes: function () {
 649   // Delete existing footnote entries in case we're reloading the footnodes.
 650   var i;
 651   var noteholder = document.getElementById("footnotes");
 652   if (!noteholder) {
 653     return;
 654   }
 655   var entriesToRemove = [];
 656   for (i = 0; i < noteholder.childNodes.length; i++) {
 657     var entry = noteholder.childNodes[i];
 658     if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
 659       entriesToRemove.push(entry);
 660   }
 661   for (i = 0; i < entriesToRemove.length; i++) {
 662     noteholder.removeChild(entriesToRemove[i]);
 663   }
 664
 665   // Rebuild footnote entries.
 666   var cont = document.getElementById("content");
 667   var spans = cont.getElementsByTagName("span");
 668   var refs = {};
 669   var n = 0;
 670   for (i=0; i<spans.length; i++) {
 671     if (spans[i].className == "footnote") {
 672       n++;
 673       var note = spans[i].getAttribute("data-note");
 674       if (!note) {
 675         // Use [\s\S] in place of . so multi-line matches work.
 676         // Because JavaScript has no s (dotall) regex flag.
 677         note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 678         spans[i].innerHTML =
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";
 681         spans[i].setAttribute("data-note", note);
 682       }
 683       noteholder.innerHTML +=
 684         "<div class='footnote' id='_footnote_" + n + "'>" +
 685         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 686         n + "</a>. " + note + "</div>";
 687       var id =spans[i].getAttribute("id");
 688       if (id != null) refs["#"+id] = n;
 689     }
 690   }
 691   if (n == 0)
 692     noteholder.parentNode.removeChild(noteholder);
 693   else {
 694     // Process footnoterefs.
 695     for (i=0; i<spans.length; i++) {
 696       if (spans[i].className == "footnoteref") {
 697         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 698         href = href.match(/#.*/)[0];  // Because IE return full URL.
 699         n = refs[href];
 700         spans[i].innerHTML =
 701           "[<a href='#_footnote_" + n +
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";
 703       }
 704     }
 705   }
 706 },
 707
 708 install: function(toclevels) {
 709   var timerId;
 710
 711   function reinstall() {
 712     asciidoc.footnotes();
 713     if (toclevels) {
 714       asciidoc.toc(toclevels);
 715     }
 716   }
 717
 718   function reinstallAndRemoveTimer() {
 719     clearInterval(timerId);
 720     reinstall();
 721   }
 722
 723   timerId = setInterval(reinstall, 500);
 724   if (document.addEventListener)
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
 726   else
 727     window.onload = reinstallAndRemoveTimer;
 728 }
 729
 730 }
 731 asciidoc.install();
 732 /*]]>*/
 733 </script>
 734 </head>
 735 <body class="manpage">
 736 <div id="header">
 737 <h1>
 738 git-bisect(1) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>git-bisect -
 743    Use binary search to find the commit that introduced a bug
 744 </p>
 745 </div>
 746 </div>
 747 <div id="content">
 748 <div class="sect1">
 749 <h2 id="_synopsis">SYNOPSIS</h2>
 750 <div class="sectionbody">
 751 <div class="verseblock">
 752 <pre class="content"><em>git bisect</em> &lt;subcommand&gt; &lt;options&gt;</pre>
 753 <div class="attribution">
 754 </div></div>
 755 </div>
 756 </div>
 757 <div class="sect1">
 758 <h2 id="_description">DESCRIPTION</h2>
 759 <div class="sectionbody">
 760 <div class="paragraph"><p>The command takes various subcommands, and different options depending
 761 on the subcommand:</p></div>
 762 <div class="literalblock">
 763 <div class="content">
 764 <pre><code>git bisect start [--term-(new|bad)=&lt;term-new&gt; --term-(old|good)=&lt;term-old&gt;]
 765                  [--no-checkout] [--first-parent] [&lt;bad&gt; [&lt;good&gt;...]] [--] [&lt;pathspec&gt;...]
 766 git bisect (bad|new|&lt;term-new&gt;) [&lt;rev&gt;]
 767 git bisect (good|old|&lt;term-old&gt;) [&lt;rev&gt;...]
 768 git bisect terms [--term-good | --term-bad]
 769 git bisect skip [(&lt;rev&gt;|&lt;range&gt;)...]
 770 git bisect reset [&lt;commit&gt;]
 771 git bisect (visualize|view)
 772 git bisect replay &lt;logfile&gt;
 773 git bisect log
 774 git bisect run &lt;cmd&gt; [&lt;arg&gt;...]
 775 git bisect help</code></pre>
 776 </div></div>
 777 <div class="paragraph"><p>This command uses a binary search algorithm to find which commit in
 778 your project&#8217;s history introduced a bug. You use it by first telling
 779 it a "bad" commit that is known to contain the bug, and a "good"
 780 commit that is known to be before the bug was introduced. Then <code>git
 781 bisect</code> picks a commit between those two endpoints and asks you
 782 whether the selected commit is "good" or "bad". It continues narrowing
 783 down the range until it finds the exact commit that introduced the
 784 change.</p></div>
 785 <div class="paragraph"><p>In fact, <code>git bisect</code> can be used to find the commit that changed
 786 <strong>any</strong> property of your project; e.g., the commit that fixed a bug, or
 787 the commit that caused a benchmark&#8217;s performance to improve. To
 788 support this more general usage, the terms "old" and "new" can be used
 789 in place of "good" and "bad", or you can choose your own terms. See
 790 section "Alternate terms" below for more information.</p></div>
 791 <div class="sect2">
 792 <h3 id="_basic_bisect_commands_start_bad_good">Basic bisect commands: start, bad, good</h3>
 793 <div class="paragraph"><p>As an example, suppose you are trying to find the commit that broke a
 794 feature that was known to work in version <code>v2.6.13-rc2</code> of your
 795 project. You start a bisect session as follows:</p></div>
 796 <div class="listingblock">
 797 <div class="content">
 798 <pre><code>$ git bisect start
 799 $ git bisect bad                 # Current version is bad
 800 $ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good</code></pre>
 801 </div></div>
 802 <div class="paragraph"><p>Once you have specified at least one bad and one good commit, <code>git
 803 bisect</code> selects a commit in the middle of that range of history,
 804 checks it out, and outputs something similar to the following:</p></div>
 805 <div class="listingblock">
 806 <div class="content">
 807 <pre><code>Bisecting: 675 revisions left to test after this (roughly 10 steps)</code></pre>
 808 </div></div>
 809 <div class="paragraph"><p>You should now compile the checked-out version and test it. If that
 810 version works correctly, type</p></div>
 811 <div class="listingblock">
 812 <div class="content">
 813 <pre><code>$ git bisect good</code></pre>
 814 </div></div>
 815 <div class="paragraph"><p>If that version is broken, type</p></div>
 816 <div class="listingblock">
 817 <div class="content">
 818 <pre><code>$ git bisect bad</code></pre>
 819 </div></div>
 820 <div class="paragraph"><p>Then <code>git bisect</code> will respond with something like</p></div>
 821 <div class="listingblock">
 822 <div class="content">
 823 <pre><code>Bisecting: 337 revisions left to test after this (roughly 9 steps)</code></pre>
 824 </div></div>
 825 <div class="paragraph"><p>Keep repeating the process: compile the tree, test it, and depending
 826 on whether it is good or bad run <code>git bisect good</code> or <code>git bisect bad</code>
 827 to ask for the next commit that needs testing.</p></div>
 828 <div class="paragraph"><p>Eventually there will be no more revisions left to inspect, and the
 829 command will print out a description of the first bad commit. The
 830 reference <code>refs/bisect/bad</code> will be left pointing at that commit.</p></div>
 831 </div>
 832 <div class="sect2">
 833 <h3 id="_bisect_reset">Bisect reset</h3>
 834 <div class="paragraph"><p>After a bisect session, to clean up the bisection state and return to
 835 the original HEAD, issue the following command:</p></div>
 836 <div class="listingblock">
 837 <div class="content">
 838 <pre><code>$ git bisect reset</code></pre>
 839 </div></div>
 840 <div class="paragraph"><p>By default, this will return your tree to the commit that was checked
 841 out before <code>git bisect start</code>.  (A new <code>git bisect start</code> will also do
 842 that, as it cleans up the old bisection state.)</p></div>
 843 <div class="paragraph"><p>With an optional argument, you can return to a different commit
 844 instead:</p></div>
 845 <div class="listingblock">
 846 <div class="content">
 847 <pre><code>$ git bisect reset &lt;commit&gt;</code></pre>
 848 </div></div>
 849 <div class="paragraph"><p>For example, <code>git bisect reset bisect/bad</code> will check out the first
 850 bad revision, while <code>git bisect reset HEAD</code> will leave you on the
 851 current bisection commit and avoid switching commits at all.</p></div>
 852 </div>
 853 <div class="sect2">
 854 <h3 id="_alternate_terms">Alternate terms</h3>
 855 <div class="paragraph"><p>Sometimes you are not looking for the commit that introduced a
 856 breakage, but rather for a commit that caused a change between some
 857 other "old" state and "new" state. For example, you might be looking
 858 for the commit that introduced a particular fix. Or you might be
 859 looking for the first commit in which the source-code filenames were
 860 finally all converted to your company&#8217;s naming standard. Or whatever.</p></div>
 861 <div class="paragraph"><p>In such cases it can be very confusing to use the terms "good" and
 862 "bad" to refer to "the state before the change" and "the state after
 863 the change". So instead, you can use the terms "old" and "new",
 864 respectively, in place of "good" and "bad". (But note that you cannot
 865 mix "good" and "bad" with "old" and "new" in a single session.)</p></div>
 866 <div class="paragraph"><p>In this more general usage, you provide <code>git bisect</code> with a "new"
 867 commit that has some property and an "old" commit that doesn&#8217;t have that
 868 property. Each time <code>git bisect</code> checks out a commit, you test if that
 869 commit has the property. If it does, mark the commit as "new";
 870 otherwise, mark it as "old". When the bisection is done, <code>git bisect</code>
 871 will report which commit introduced the property.</p></div>
 872 <div class="paragraph"><p>To use "old" and "new" instead of "good" and bad, you must run <code>git
 873 bisect start</code> without commits as argument and then run the following
 874 commands to add the commits:</p></div>
 875 <div class="listingblock">
 876 <div class="content">
 877 <pre><code>git bisect old [&lt;rev&gt;]</code></pre>
 878 </div></div>
 879 <div class="paragraph"><p>to indicate that a commit was before the sought change, or</p></div>
 880 <div class="listingblock">
 881 <div class="content">
 882 <pre><code>git bisect new [&lt;rev&gt;...]</code></pre>
 883 </div></div>
 884 <div class="paragraph"><p>to indicate that it was after.</p></div>
 885 <div class="paragraph"><p>To get a reminder of the currently used terms, use</p></div>
 886 <div class="listingblock">
 887 <div class="content">
 888 <pre><code>git bisect terms</code></pre>
 889 </div></div>
 890 <div class="paragraph"><p>You can get just the old (respectively new) term with <code>git bisect terms
 891 --term-old</code> or <code>git bisect terms --term-good</code>.</p></div>
 892 <div class="paragraph"><p>If you would like to use your own terms instead of "bad"/"good" or
 893 "new"/"old", you can choose any names you like (except existing bisect
 894 subcommands like <code>reset</code>, <code>start</code>, &#8230;) by starting the
 895 bisection using</p></div>
 896 <div class="listingblock">
 897 <div class="content">
 898 <pre><code>git bisect start --term-old &lt;term-old&gt; --term-new &lt;term-new&gt;</code></pre>
 899 </div></div>
 900 <div class="paragraph"><p>For example, if you are looking for a commit that introduced a
 901 performance regression, you might use</p></div>
 902 <div class="listingblock">
 903 <div class="content">
 904 <pre><code>git bisect start --term-old fast --term-new slow</code></pre>
 905 </div></div>
 906 <div class="paragraph"><p>Or if you are looking for the commit that fixed a bug, you might use</p></div>
 907 <div class="listingblock">
 908 <div class="content">
 909 <pre><code>git bisect start --term-new fixed --term-old broken</code></pre>
 910 </div></div>
 911 <div class="paragraph"><p>Then, use <code>git bisect &lt;term-old&gt;</code> and <code>git bisect &lt;term-new&gt;</code> instead
 912 of <code>git bisect good</code> and <code>git bisect bad</code> to mark commits.</p></div>
 913 </div>
 914 <div class="sect2">
 915 <h3 id="_bisect_visualize_view">Bisect visualize/view</h3>
 916 <div class="paragraph"><p>To see the currently remaining suspects in <em>gitk</em>, issue the following
 917 command during the bisection process (the subcommand <code>view</code> can be used
 918 as an alternative to <code>visualize</code>):</p></div>
 919 <div class="listingblock">
 920 <div class="content">
 921 <pre><code>$ git bisect visualize</code></pre>
 922 </div></div>
 923 <div class="paragraph"><p>Git detects a graphical environment through various environment variables:
 924 <code>DISPLAY</code>, which is set in X Window System environments on Unix systems.
 925 <code>SESSIONNAME</code>, which is set under Cygwin in interactive desktop sessions.
 926 <code>MSYSTEM</code>, which is set under Msys2 and Git for Windows.
 927 <code>SECURITYSESSIONID</code>, which may be set on macOS in interactive desktop sessions.</p></div>
 928 <div class="paragraph"><p>If none of these environment variables is set, <em>git log</em> is used instead.
 929 You can also give command-line options such as <code>-p</code> and <code>--stat</code>.</p></div>
 930 <div class="listingblock">
 931 <div class="content">
 932 <pre><code>$ git bisect visualize --stat</code></pre>
 933 </div></div>
 934 </div>
 935 <div class="sect2">
 936 <h3 id="_bisect_log_and_bisect_replay">Bisect log and bisect replay</h3>
 937 <div class="paragraph"><p>After having marked revisions as good or bad, issue the following
 938 command to show what has been done so far:</p></div>
 939 <div class="listingblock">
 940 <div class="content">
 941 <pre><code>$ git bisect log</code></pre>
 942 </div></div>
 943 <div class="paragraph"><p>If you discover that you made a mistake in specifying the status of a
 944 revision, you can save the output of this command to a file, edit it to
 945 remove the incorrect entries, and then issue the following commands to
 946 return to a corrected state:</p></div>
 947 <div class="listingblock">
 948 <div class="content">
 949 <pre><code>$ git bisect reset
 950 $ git bisect replay that-file</code></pre>
 951 </div></div>
 952 </div>
 953 <div class="sect2">
 954 <h3 id="_avoiding_testing_a_commit">Avoiding testing a commit</h3>
 955 <div class="paragraph"><p>If, in the middle of a bisect session, you know that the suggested
 956 revision is not a good one to test (e.g. it fails to build and you
 957 know that the failure does not have anything to do with the bug you
 958 are chasing), you can manually select a nearby commit and test that
 959 one instead.</p></div>
 960 <div class="paragraph"><p>For example:</p></div>
 961 <div class="listingblock">
 962 <div class="content">
 963 <pre><code>$ git bisect good/bad                   # previous round was good or bad.
 964 Bisecting: 337 revisions left to test after this (roughly 9 steps)
 965 $ git bisect visualize                  # oops, that is uninteresting.
 966 $ git reset --hard HEAD~3               # try 3 revisions before what
 967                                         # was suggested</code></pre>
 968 </div></div>
 969 <div class="paragraph"><p>Then compile and test the chosen revision, and afterwards mark
 970 the revision as good or bad in the usual manner.</p></div>
 971 </div>
 972 <div class="sect2">
 973 <h3 id="_bisect_skip">Bisect skip</h3>
 974 <div class="paragraph"><p>Instead of choosing a nearby commit by yourself, you can ask Git to do
 975 it for you by issuing the command:</p></div>
 976 <div class="listingblock">
 977 <div class="content">
 978 <pre><code>$ git bisect skip                 # Current version cannot be tested</code></pre>
 979 </div></div>
 980 <div class="paragraph"><p>However, if you skip a commit adjacent to the one you are looking for,
 981 Git will be unable to tell exactly which of those commits was the
 982 first bad one.</p></div>
 983 <div class="paragraph"><p>You can also skip a range of commits, instead of just one commit,
 984 using range notation. For example:</p></div>
 985 <div class="listingblock">
 986 <div class="content">
 987 <pre><code>$ git bisect skip v2.5..v2.6</code></pre>
 988 </div></div>
 989 <div class="paragraph"><p>This tells the bisect process that no commit after <code>v2.5</code>, up to and
 990 including <code>v2.6</code>, should be tested.</p></div>
 991 <div class="paragraph"><p>Note that if you also want to skip the first commit of the range you
 992 would issue the command:</p></div>
 993 <div class="listingblock">
 994 <div class="content">
 995 <pre><code>$ git bisect skip v2.5 v2.5..v2.6</code></pre>
 996 </div></div>
 997 <div class="paragraph"><p>This tells the bisect process that the commits between <code>v2.5</code> and
 998 <code>v2.6</code> (inclusive) should be skipped.</p></div>
 999 </div>
1000 <div class="sect2">
1001 <h3 id="_cutting_down_bisection_by_giving_more_parameters_to_bisect_start">Cutting down bisection by giving more parameters to bisect start</h3>
1002 <div class="paragraph"><p>You can further cut down the number of trials, if you know what part of
1003 the tree is involved in the problem you are tracking down, by specifying
1004 pathspec parameters when issuing the <code>bisect start</code> command:</p></div>
1005 <div class="listingblock">
1006 <div class="content">
1007 <pre><code>$ git bisect start -- arch/i386 include/asm-i386</code></pre>
1008 </div></div>
1009 <div class="paragraph"><p>If you know beforehand more than one good commit, you can narrow the
1010 bisect space down by specifying all of the good commits immediately after
1011 the bad commit when issuing the <code>bisect start</code> command:</p></div>
1012 <div class="listingblock">
1013 <div class="content">
1014 <pre><code>$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
1015                    # v2.6.20-rc6 is bad
1016                    # v2.6.20-rc4 and v2.6.20-rc1 are good</code></pre>
1017 </div></div>
1018 </div>
1019 <div class="sect2">
1020 <h3 id="_bisect_run">Bisect run</h3>
1021 <div class="paragraph"><p>If you have a script that can tell if the current source code is good
1022 or bad, you can bisect by issuing the command:</p></div>
1023 <div class="listingblock">
1024 <div class="content">
1025 <pre><code>$ git bisect run my_script arguments</code></pre>
1026 </div></div>
1027 <div class="paragraph"><p>Note that the script (<code>my_script</code> in the above example) should exit
1028 with code 0 if the current source code is good/old, and exit with a
1029 code between 1 and 127 (inclusive), except 125, if the current source
1030 code is bad/new.</p></div>
1031 <div class="paragraph"><p>Any other exit code will abort the bisect process. It should be noted
1032 that a program that terminates via <code>exit(-1)</code> leaves $? = 255, (see the
1033 exit(3) manual page), as the value is chopped with <code>&amp; 0377</code>.</p></div>
1034 <div class="paragraph"><p>The special exit code 125 should be used when the current source code
1035 cannot be tested. If the script exits with this code, the current
1036 revision will be skipped (see <code>git bisect skip</code> above). 125 was chosen
1037 as the highest sensible value to use for this purpose, because 126 and 127
1038 are used by POSIX shells to signal specific error status (127 is for
1039 command not found, 126 is for command found but not executable&#8212;these
1040 details do not matter, as they are normal errors in the script, as far as
1041 <code>bisect run</code> is concerned).</p></div>
1042 <div class="paragraph"><p>You may often find that during a bisect session you want to have
1043 temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
1044 header file, or "revision that does not have this commit needs this
1045 patch applied to work around another problem this bisection is not
1046 interested in") applied to the revision being tested.</p></div>
1047 <div class="paragraph"><p>To cope with such a situation, after the inner <em>git bisect</em> finds the
1048 next revision to test, the script can apply the patch
1049 before compiling, run the real test, and afterwards decide if the
1050 revision (possibly with the needed patch) passed the test and then
1051 rewind the tree to the pristine state.  Finally the script should exit
1052 with the status of the real test to let the <code>git bisect run</code> command loop
1053 determine the eventual outcome of the bisect session.</p></div>
1054 </div>
1055 </div>
1056 </div>
1057 <div class="sect1">
1058 <h2 id="_options">OPTIONS</h2>
1059 <div class="sectionbody">
1060 <div class="dlist"><dl>
1061 <dt class="hdlist1">
1062 --no-checkout
1063 </dt>
1064 <dd>
1065 <div class="paragraph"><p>Do not checkout the new working tree at each iteration of the bisection
1066 process. Instead just update the reference named <code>BISECT_HEAD</code> to make
1067 it point to the commit that should be tested.</p></div>
1068 <div class="paragraph"><p>This option may be useful when the test you would perform in each step
1069 does not require a checked out tree.</p></div>
1070 <div class="paragraph"><p>If the repository is bare, <code>--no-checkout</code> is assumed.</p></div>
1071 </dd>
1072 <dt class="hdlist1">
1073 --first-parent
1074 </dt>
1075 <dd>
1076 <div class="paragraph"><p>Follow only the first parent commit upon seeing a merge commit.</p></div>
1077 <div class="paragraph"><p>In detecting regressions introduced through the merging of a branch, the merge
1078 commit will be identified as introduction of the bug and its ancestors will be
1079 ignored.</p></div>
1080 <div class="paragraph"><p>This option is particularly useful in avoiding false positives when a merged
1081 branch contained broken or non-buildable commits, but the merge itself was OK.</p></div>
1082 </dd>
1083 </dl></div>
1084 </div>
1085 </div>
1086 <div class="sect1">
1087 <h2 id="_examples">EXAMPLES</h2>
1088 <div class="sectionbody">
1089 <div class="ulist"><ul>
1090 <li>
1091 <p>
1092 Automatically bisect a broken build between v1.2 and HEAD:
1093 </p>
1094 <div class="listingblock">
1095 <div class="content">
1096 <pre><code>$ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
1097 $ git bisect run make                # "make" builds the app
1098 $ git bisect reset                   # quit the bisect session</code></pre>
1099 </div></div>
1100 </li>
1101 <li>
1102 <p>
1103 Automatically bisect a test failure between origin and HEAD:
1104 </p>
1105 <div class="listingblock">
1106 <div class="content">
1107 <pre><code>$ git bisect start HEAD origin --    # HEAD is bad, origin is good
1108 $ git bisect run make test           # "make test" builds and tests
1109 $ git bisect reset                   # quit the bisect session</code></pre>
1110 </div></div>
1111 </li>
1112 <li>
1113 <p>
1114 Automatically bisect a broken test case:
1115 </p>
1116 <div class="listingblock">
1117 <div class="content">
1118 <pre><code>$ cat ~/test.sh
1119 #!/bin/sh
1120 make || exit 125                     # this skips broken builds
1121 ~/check_test_case.sh                 # does the test case pass?
1122 $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
1123 $ git bisect run ~/test.sh
1124 $ git bisect reset                   # quit the bisect session</code></pre>
1125 </div></div>
1126 <div class="paragraph"><p>Here we use a <code>test.sh</code> custom script. In this script, if <code>make</code>
1127 fails, we skip the current commit.
1128 <code>check_test_case.sh</code> should <code>exit 0</code> if the test case passes,
1129 and <code>exit 1</code> otherwise.</p></div>
1130 <div class="paragraph"><p>It is safer if both <code>test.sh</code> and <code>check_test_case.sh</code> are
1131 outside the repository to prevent interactions between the bisect,
1132 make and test processes and the scripts.</p></div>
1133 </li>
1134 <li>
1135 <p>
1136 Automatically bisect with temporary modifications (hot-fix):
1137 </p>
1138 <div class="listingblock">
1139 <div class="content">
1140 <pre><code>$ cat ~/test.sh
1141 #!/bin/sh
1142
1143 # tweak the working tree by merging the hot-fix branch
1144 # and then attempt a build
1145 if      git merge --no-commit --no-ff hot-fix &amp;&amp;
1146         make
1147 then
1148         # run project specific test and report its status
1149         ~/check_test_case.sh
1150         status=$?
1151 else
1152         # tell the caller this is untestable
1153         status=125
1154 fi
1155
1156 # undo the tweak to allow clean flipping to the next commit
1157 git reset --hard
1158
1159 # return control
1160 exit $status</code></pre>
1161 </div></div>
1162 <div class="paragraph"><p>This applies modifications from a hot-fix branch before each test run,
1163 e.g. in case your build or test environment changed so that older
1164 revisions may need a fix which newer ones have already. (Make sure the
1165 hot-fix branch is based off a commit which is contained in all revisions
1166 which you are bisecting, so that the merge does not pull in too much, or
1167 use <code>git cherry-pick</code> instead of <code>git merge</code>.)</p></div>
1168 </li>
1169 <li>
1170 <p>
1171 Automatically bisect a broken test case:
1172 </p>
1173 <div class="listingblock">
1174 <div class="content">
1175 <pre><code>$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
1176 $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
1177 $ git bisect reset                   # quit the bisect session</code></pre>
1178 </div></div>
1179 <div class="paragraph"><p>This shows that you can do without a run script if you write the test
1180 on a single line.</p></div>
1181 </li>
1182 <li>
1183 <p>
1184 Locate a good region of the object graph in a damaged repository
1185 </p>
1186 <div class="listingblock">
1187 <div class="content">
1188 <pre><code>$ git bisect start HEAD &lt;known-good-commit&gt; [ &lt;boundary-commit&gt; ... ] --no-checkout
1189 $ git bisect run sh -c '
1190         GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &amp;&amp;
1191         git rev-list --objects BISECT_HEAD --not $GOOD &gt;tmp.$$ &amp;&amp;
1192         git pack-objects --stdout &gt;/dev/null &lt;tmp.$$
1193         rc=$?
1194         rm -f tmp.$$
1195         test $rc = 0'
1196
1197 $ git bisect reset                   # quit the bisect session</code></pre>
1198 </div></div>
1199 <div class="paragraph"><p>In this case, when <em>git bisect run</em> finishes, bisect/bad will refer to a commit that
1200 has at least one parent whose reachable graph is fully traversable in the sense
1201 required by <em>git pack objects</em>.</p></div>
1202 </li>
1203 <li>
1204 <p>
1205 Look for a fix instead of a regression in the code
1206 </p>
1207 <div class="listingblock">
1208 <div class="content">
1209 <pre><code>$ git bisect start
1210 $ git bisect new HEAD    # current commit is marked as new
1211 $ git bisect old HEAD~10 # the tenth commit from now is marked as old</code></pre>
1212 </div></div>
1213 <div class="paragraph"><p>or:</p></div>
1214 </li>
1215 </ul></div>
1216 <div class="listingblock">
1217 <div class="content">
1218 <pre><code>$ git bisect start --term-old broken --term-new fixed
1219 $ git bisect fixed
1220 $ git bisect broken HEAD~10</code></pre>
1221 </div></div>
1222 <div class="sect2">
1223 <h3 id="_getting_help">Getting help</h3>
1224 <div class="paragraph"><p>Use <code>git bisect</code> to get a short usage description, and <code>git bisect
1225 help</code> or <code>git bisect -h</code> to get a long usage description.</p></div>
1226 </div>
1227 </div>
1228 </div>
1229 <div class="sect1">
1230 <h2 id="_see_also">SEE ALSO</h2>
1231 <div class="sectionbody">
1232 <div class="paragraph"><p><a href="git-bisect-lk2009.html">Fighting regressions with git bisect</a>,
1233 <a href="git-blame.html">git-blame(1)</a>.</p></div>
1234 </div>
1235 </div>
1236 <div class="sect1">
1237 <h2 id="_git">GIT</h2>
1238 <div class="sectionbody">
1239 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1240 </div>
1241 </div>
1242 </div>
1243 <div id="footnotes"><hr /></div>
1244 <div id="footer">
1245 <div id="footer-text">
1246 Last updated
1247  2024-01-19 16:47:36 PST
1248 </div>
1249 </div>
1250 </body>
1251 </html>