git-replay.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-replay(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-replay(1) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>git-replay -
 743    EXPERIMENTAL: Replay commits on a new base, works with bare repos too
 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">(EXPERIMENTAL!) <em>git replay</em> ([--contained] --onto &lt;newbase&gt; | --advance &lt;branch&gt;) &lt;revision-range&gt;&#8230;</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>Takes ranges of commits and replays them onto a new location. Leaves
 761 the working tree and the index untouched, and updates no references.
 762 The output of this command is meant to be used as input to
 763 <code>git update-ref --stdin</code>, which would update the relevant branches
 764 (see the OUTPUT section below).</p></div>
 765 <div class="paragraph"><p>THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.</p></div>
 766 </div>
 767 </div>
 768 <div class="sect1">
 769 <h2 id="_options">OPTIONS</h2>
 770 <div class="sectionbody">
 771 <div class="dlist"><dl>
 772 <dt class="hdlist1">
 773 --onto &lt;newbase&gt;
 774 </dt>
 775 <dd>
 776 <p>
 777         Starting point at which to create the new commits.  May be any
 778         valid commit, and not just an existing branch name.
 779 </p>
 780 <div class="paragraph"><p>When <code>--onto</code> is specified, the update-ref command(s) in the output will
 781 update the branch(es) in the revision range to point at the new
 782 commits, similar to the way how <code>git rebase --update-refs</code> updates
 783 multiple branches in the affected range.</p></div>
 784 </dd>
 785 <dt class="hdlist1">
 786 --advance &lt;branch&gt;
 787 </dt>
 788 <dd>
 789 <p>
 790         Starting point at which to create the new commits; must be a
 791         branch name.
 792 </p>
 793 <div class="paragraph"><p>When <code>--advance</code> is specified, the update-ref command(s) in the output
 794 will update the branch passed as an argument to <code>--advance</code> to point at
 795 the new commits (in other words, this mimics a cherry-pick operation).</p></div>
 796 </dd>
 797 <dt class="hdlist1">
 798 &lt;revision-range&gt;
 799 </dt>
 800 <dd>
 801 <p>
 802         Range of commits to replay. More than one &lt;revision-range&gt; can
 803         be passed, but in <code>--advance &lt;branch&gt;</code> mode, they should have
 804         a single tip, so that it&#8217;s clear where &lt;branch&gt; should point
 805         to. See "Specifying Ranges" in <a href="git-rev-parse.html">git-rev-parse(1)</a> and the
 806         "Commit Limiting" options below.
 807 </p>
 808 </dd>
 809 </dl></div>
 810 <div class="sect2">
 811 <h3 id="_commit_limiting">Commit Limiting</h3>
 812 <div class="paragraph"><p>Besides specifying a range of commits that should be listed using the
 813 special notations explained in the description, additional commit
 814 limiting may be applied.</p></div>
 815 <div class="paragraph"><p>Using more options generally further limits the output (e.g.
 816 <code>--since=&lt;date1&gt;</code> limits to commits newer than <code>&lt;date1&gt;</code>, and using it
 817 with <code>--grep=&lt;pattern&gt;</code> further limits to commits whose log message
 818 has a line that matches <code>&lt;pattern&gt;</code>), unless otherwise noted.</p></div>
 819 <div class="paragraph"><p>Note that these are applied before commit
 820 ordering and formatting options, such as <code>--reverse</code>.</p></div>
 821 <div class="dlist"><dl>
 822 <dt class="hdlist1">
 823 -&lt;number&gt;
 824 </dt>
 825 <dt class="hdlist1">
 826 -n &lt;number&gt;
 827 </dt>
 828 <dt class="hdlist1">
 829 --max-count=&lt;number&gt;
 830 </dt>
 831 <dd>
 832 <p>
 833         Limit the number of commits to output.
 834 </p>
 835 </dd>
 836 <dt class="hdlist1">
 837 --skip=&lt;number&gt;
 838 </dt>
 839 <dd>
 840 <p>
 841         Skip <em>number</em> commits before starting to show the commit output.
 842 </p>
 843 </dd>
 844 <dt class="hdlist1">
 845 --since=&lt;date&gt;
 846 </dt>
 847 <dt class="hdlist1">
 848 --after=&lt;date&gt;
 849 </dt>
 850 <dd>
 851 <p>
 852         Show commits more recent than a specific date.
 853 </p>
 854 </dd>
 855 <dt class="hdlist1">
 856 --since-as-filter=&lt;date&gt;
 857 </dt>
 858 <dd>
 859 <p>
 860         Show all commits more recent than a specific date. This visits
 861         all commits in the range, rather than stopping at the first commit which
 862         is older than a specific date.
 863 </p>
 864 </dd>
 865 <dt class="hdlist1">
 866 --until=&lt;date&gt;
 867 </dt>
 868 <dt class="hdlist1">
 869 --before=&lt;date&gt;
 870 </dt>
 871 <dd>
 872 <p>
 873         Show commits older than a specific date.
 874 </p>
 875 </dd>
 876 <dt class="hdlist1">
 877 --author=&lt;pattern&gt;
 878 </dt>
 879 <dt class="hdlist1">
 880 --committer=&lt;pattern&gt;
 881 </dt>
 882 <dd>
 883 <p>
 884         Limit the commits output to ones with author/committer
 885         header lines that match the specified pattern (regular
 886         expression).  With more than one <code>--author=&lt;pattern&gt;</code>,
 887         commits whose author matches any of the given patterns are
 888         chosen (similarly for multiple <code>--committer=&lt;pattern&gt;</code>).
 889 </p>
 890 </dd>
 891 <dt class="hdlist1">
 892 --grep-reflog=&lt;pattern&gt;
 893 </dt>
 894 <dd>
 895 <p>
 896         Limit the commits output to ones with reflog entries that
 897         match the specified pattern (regular expression). With
 898         more than one <code>--grep-reflog</code>, commits whose reflog message
 899         matches any of the given patterns are chosen.  It is an
 900         error to use this option unless <code>--walk-reflogs</code> is in use.
 901 </p>
 902 </dd>
 903 <dt class="hdlist1">
 904 --grep=&lt;pattern&gt;
 905 </dt>
 906 <dd>
 907 <p>
 908         Limit the commits output to ones with a log message that
 909         matches the specified pattern (regular expression).  With
 910         more than one <code>--grep=&lt;pattern&gt;</code>, commits whose message
 911         matches any of the given patterns are chosen (but see
 912         <code>--all-match</code>).
 913 </p>
 914 <div class="paragraph"><p>When <code>--notes</code> is in effect, the message from the notes is
 915 matched as if it were part of the log message.</p></div>
 916 </dd>
 917 <dt class="hdlist1">
 918 --all-match
 919 </dt>
 920 <dd>
 921 <p>
 922         Limit the commits output to ones that match all given <code>--grep</code>,
 923         instead of ones that match at least one.
 924 </p>
 925 </dd>
 926 <dt class="hdlist1">
 927 --invert-grep
 928 </dt>
 929 <dd>
 930 <p>
 931         Limit the commits output to ones with a log message that do not
 932         match the pattern specified with <code>--grep=&lt;pattern&gt;</code>.
 933 </p>
 934 </dd>
 935 <dt class="hdlist1">
 936 -i
 937 </dt>
 938 <dt class="hdlist1">
 939 --regexp-ignore-case
 940 </dt>
 941 <dd>
 942 <p>
 943         Match the regular expression limiting patterns without regard to letter
 944         case.
 945 </p>
 946 </dd>
 947 <dt class="hdlist1">
 948 --basic-regexp
 949 </dt>
 950 <dd>
 951 <p>
 952         Consider the limiting patterns to be basic regular expressions;
 953         this is the default.
 954 </p>
 955 </dd>
 956 <dt class="hdlist1">
 957 -E
 958 </dt>
 959 <dt class="hdlist1">
 960 --extended-regexp
 961 </dt>
 962 <dd>
 963 <p>
 964         Consider the limiting patterns to be extended regular expressions
 965         instead of the default basic regular expressions.
 966 </p>
 967 </dd>
 968 <dt class="hdlist1">
 969 -F
 970 </dt>
 971 <dt class="hdlist1">
 972 --fixed-strings
 973 </dt>
 974 <dd>
 975 <p>
 976         Consider the limiting patterns to be fixed strings (don&#8217;t interpret
 977         pattern as a regular expression).
 978 </p>
 979 </dd>
 980 <dt class="hdlist1">
 981 -P
 982 </dt>
 983 <dt class="hdlist1">
 984 --perl-regexp
 985 </dt>
 986 <dd>
 987 <p>
 988         Consider the limiting patterns to be Perl-compatible regular
 989         expressions.
 990 </p>
 991 <div class="paragraph"><p>Support for these types of regular expressions is an optional
 992 compile-time dependency. If Git wasn&#8217;t compiled with support for them
 993 providing this option will cause it to die.</p></div>
 994 </dd>
 995 <dt class="hdlist1">
 996 --remove-empty
 997 </dt>
 998 <dd>
 999 <p>
1000         Stop when a given path disappears from the tree.
1001 </p>
1002 </dd>
1003 <dt class="hdlist1">
1004 --merges
1005 </dt>
1006 <dd>
1007 <p>
1008         Print only merge commits. This is exactly the same as <code>--min-parents=2</code>.
1009 </p>
1010 </dd>
1011 <dt class="hdlist1">
1012 --no-merges
1013 </dt>
1014 <dd>
1015 <p>
1016         Do not print commits with more than one parent. This is
1017         exactly the same as <code>--max-parents=1</code>.
1018 </p>
1019 </dd>
1020 <dt class="hdlist1">
1021 --min-parents=&lt;number&gt;
1022 </dt>
1023 <dt class="hdlist1">
1024 --max-parents=&lt;number&gt;
1025 </dt>
1026 <dt class="hdlist1">
1027 --no-min-parents
1028 </dt>
1029 <dt class="hdlist1">
1030 --no-max-parents
1031 </dt>
1032 <dd>
1033 <p>
1034         Show only commits which have at least (or at most) that many parent
1035         commits. In particular, <code>--max-parents=1</code> is the same as <code>--no-merges</code>,
1036         <code>--min-parents=2</code> is the same as <code>--merges</code>.  <code>--max-parents=0</code>
1037         gives all root commits and <code>--min-parents=3</code> all octopus merges.
1038 </p>
1039 <div class="paragraph"><p><code>--no-min-parents</code> and <code>--no-max-parents</code> reset these limits (to no limit)
1040 again.  Equivalent forms are <code>--min-parents=0</code> (any commit has 0 or more
1041 parents) and <code>--max-parents=-1</code> (negative numbers denote no upper limit).</p></div>
1042 </dd>
1043 <dt class="hdlist1">
1044 --first-parent
1045 </dt>
1046 <dd>
1047 <p>
1048         When finding commits to include, follow only the first
1049         parent commit upon seeing a merge commit.  This option
1050         can give a better overview when viewing the evolution of
1051         a particular topic branch, because merges into a topic
1052         branch tend to be only about adjusting to updated upstream
1053         from time to time, and this option allows you to ignore
1054         the individual commits brought in to your history by such
1055         a merge.
1056 </p>
1057 </dd>
1058 <dt class="hdlist1">
1059 --exclude-first-parent-only
1060 </dt>
1061 <dd>
1062 <p>
1063         When finding commits to exclude (with a <em>&#94;</em>), follow only
1064         the first parent commit upon seeing a merge commit.
1065         This can be used to find the set of changes in a topic branch
1066         from the point where it diverged from the remote branch, given
1067         that arbitrary merges can be valid topic branch changes.
1068 </p>
1069 </dd>
1070 <dt class="hdlist1">
1071 --not
1072 </dt>
1073 <dd>
1074 <p>
1075         Reverses the meaning of the <em>&#94;</em> prefix (or lack thereof)
1076         for all following revision specifiers, up to the next <code>--not</code>.
1077         When used on the command line before --stdin, the revisions passed
1078         through stdin will not be affected by it. Conversely, when passed
1079         via standard input, the revisions passed on the command line will
1080         not be affected by it.
1081 </p>
1082 </dd>
1083 <dt class="hdlist1">
1084 --all
1085 </dt>
1086 <dd>
1087 <p>
1088         Pretend as if all the refs in <code>refs/</code>, along with <code>HEAD</code>, are
1089         listed on the command line as <em>&lt;commit&gt;</em>.
1090 </p>
1091 </dd>
1092 <dt class="hdlist1">
1093 --branches[=&lt;pattern&gt;]
1094 </dt>
1095 <dd>
1096 <p>
1097         Pretend as if all the refs in <code>refs/heads</code> are listed
1098         on the command line as <em>&lt;commit&gt;</em>. If <em>&lt;pattern&gt;</em> is given, limit
1099         branches to ones matching given shell glob. If pattern lacks <em>?</em>,
1100         <em>&#42;</em>, or <em>[</em>, <em>/&#42;</em> at the end is implied.
1101 </p>
1102 </dd>
1103 <dt class="hdlist1">
1104 --tags[=&lt;pattern&gt;]
1105 </dt>
1106 <dd>
1107 <p>
1108         Pretend as if all the refs in <code>refs/tags</code> are listed
1109         on the command line as <em>&lt;commit&gt;</em>. If <em>&lt;pattern&gt;</em> is given, limit
1110         tags to ones matching given shell glob. If pattern lacks <em>?</em>, <em>&#42;</em>,
1111         or <em>[</em>, <em>/&#42;</em> at the end is implied.
1112 </p>
1113 </dd>
1114 <dt class="hdlist1">
1115 --remotes[=&lt;pattern&gt;]
1116 </dt>
1117 <dd>
1118 <p>
1119         Pretend as if all the refs in <code>refs/remotes</code> are listed
1120         on the command line as <em>&lt;commit&gt;</em>. If <em>&lt;pattern&gt;</em> is given, limit
1121         remote-tracking branches to ones matching given shell glob.
1122         If pattern lacks <em>?</em>, <em>&#42;</em>, or <em>[</em>, <em>/&#42;</em> at the end is implied.
1123 </p>
1124 </dd>
1125 <dt class="hdlist1">
1126 --glob=&lt;glob-pattern&gt;
1127 </dt>
1128 <dd>
1129 <p>
1130         Pretend as if all the refs matching shell glob <em>&lt;glob-pattern&gt;</em>
1131         are listed on the command line as <em>&lt;commit&gt;</em>. Leading <em>refs/</em>,
1132         is automatically prepended if missing. If pattern lacks <em>?</em>, <em>&#42;</em>,
1133         or <em>[</em>, <em>/&#42;</em> at the end is implied.
1134 </p>
1135 </dd>
1136 <dt class="hdlist1">
1137 --exclude=&lt;glob-pattern&gt;
1138 </dt>
1139 <dd>
1140 <p>
1141         Do not include refs matching <em>&lt;glob-pattern&gt;</em> that the next <code>--all</code>,
1142         <code>--branches</code>, <code>--tags</code>, <code>--remotes</code>, or <code>--glob</code> would otherwise
1143         consider. Repetitions of this option accumulate exclusion patterns
1144         up to the next <code>--all</code>, <code>--branches</code>, <code>--tags</code>, <code>--remotes</code>, or
1145         <code>--glob</code> option (other options or arguments do not clear
1146         accumulated patterns).
1147 </p>
1148 <div class="paragraph"><p>The patterns given should not begin with <code>refs/heads</code>, <code>refs/tags</code>, or
1149 <code>refs/remotes</code> when applied to <code>--branches</code>, <code>--tags</code>, or <code>--remotes</code>,
1150 respectively, and they must begin with <code>refs/</code> when applied to <code>--glob</code>
1151 or <code>--all</code>. If a trailing <em>/&#42;</em> is intended, it must be given
1152 explicitly.</p></div>
1153 </dd>
1154 <dt class="hdlist1">
1155 --exclude-hidden=[fetch|receive|uploadpack]
1156 </dt>
1157 <dd>
1158 <p>
1159         Do not include refs that would be hidden by <code>git-fetch</code>,
1160         <code>git-receive-pack</code> or <code>git-upload-pack</code> by consulting the appropriate
1161         <code>fetch.hideRefs</code>, <code>receive.hideRefs</code> or <code>uploadpack.hideRefs</code>
1162         configuration along with <code>transfer.hideRefs</code> (see
1163         <a href="git-config.html">git-config(1)</a>). This option affects the next pseudo-ref option
1164         <code>--all</code> or <code>--glob</code> and is cleared after processing them.
1165 </p>
1166 </dd>
1167 <dt class="hdlist1">
1168 --reflog
1169 </dt>
1170 <dd>
1171 <p>
1172         Pretend as if all objects mentioned by reflogs are listed on the
1173         command line as <code>&lt;commit&gt;</code>.
1174 </p>
1175 </dd>
1176 <dt class="hdlist1">
1177 --alternate-refs
1178 </dt>
1179 <dd>
1180 <p>
1181         Pretend as if all objects mentioned as ref tips of alternate
1182         repositories were listed on the command line. An alternate
1183         repository is any repository whose object directory is specified
1184         in <code>objects/info/alternates</code>.  The set of included objects may
1185         be modified by <code>core.alternateRefsCommand</code>, etc. See
1186         <a href="git-config.html">git-config(1)</a>.
1187 </p>
1188 </dd>
1189 <dt class="hdlist1">
1190 --single-worktree
1191 </dt>
1192 <dd>
1193 <p>
1194         By default, all working trees will be examined by the
1195         following options when there are more than one (see
1196         <a href="git-worktree.html">git-worktree(1)</a>): <code>--all</code>, <code>--reflog</code> and
1197         <code>--indexed-objects</code>.
1198         This option forces them to examine the current working tree
1199         only.
1200 </p>
1201 </dd>
1202 <dt class="hdlist1">
1203 --ignore-missing
1204 </dt>
1205 <dd>
1206 <p>
1207         Upon seeing an invalid object name in the input, pretend as if
1208         the bad input was not given.
1209 </p>
1210 </dd>
1211 <dt class="hdlist1">
1212 --bisect
1213 </dt>
1214 <dd>
1215 <p>
1216         Pretend as if the bad bisection ref <code>refs/bisect/bad</code>
1217         was listed and as if it was followed by <code>--not</code> and the good
1218         bisection refs <code>refs/bisect/good-*</code> on the command
1219         line.
1220 </p>
1221 </dd>
1222 <dt class="hdlist1">
1223 --stdin
1224 </dt>
1225 <dd>
1226 <p>
1227         In addition to getting arguments from the command line, read
1228         them from standard input as well. This accepts commits and
1229         pseudo-options like <code>--all</code> and <code>--glob=</code>. When a <code>--</code> separator
1230         is seen, the following input is treated as paths and used to
1231         limit the result. Flags like <code>--not</code> which are read via standard input
1232         are only respected for arguments passed in the same way and will not
1233         influence any subsequent command line arguments.
1234 </p>
1235 </dd>
1236 <dt class="hdlist1">
1237 --cherry-mark
1238 </dt>
1239 <dd>
1240 <p>
1241         Like <code>--cherry-pick</code> (see below) but mark equivalent commits
1242         with <code>=</code> rather than omitting them, and inequivalent ones with <code>+</code>.
1243 </p>
1244 </dd>
1245 <dt class="hdlist1">
1246 --cherry-pick
1247 </dt>
1248 <dd>
1249 <p>
1250         Omit any commit that introduces the same change as
1251         another commit on the &#8220;other side&#8221; when the set of
1252         commits are limited with symmetric difference.
1253 </p>
1254 <div class="paragraph"><p>For example, if you have two branches, <code>A</code> and <code>B</code>, a usual way
1255 to list all commits on only one side of them is with
1256 <code>--left-right</code> (see the example below in the description of
1257 the <code>--left-right</code> option). However, it shows the commits that were
1258 cherry-picked from the other branch (for example, &#8220;3rd on b&#8221; may be
1259 cherry-picked from branch A). With this option, such pairs of commits are
1260 excluded from the output.</p></div>
1261 </dd>
1262 <dt class="hdlist1">
1263 --left-only
1264 </dt>
1265 <dt class="hdlist1">
1266 --right-only
1267 </dt>
1268 <dd>
1269 <p>
1270         List only commits on the respective side of a symmetric difference,
1271         i.e. only those which would be marked <code>&lt;</code> resp. <code>&gt;</code> by
1272         <code>--left-right</code>.
1273 </p>
1274 <div class="paragraph"><p>For example, <code>--cherry-pick --right-only A...B</code> omits those
1275 commits from <code>B</code> which are in <code>A</code> or are patch-equivalent to a commit in
1276 <code>A</code>. In other words, this lists the <code>+</code> commits from <code>git cherry A B</code>.
1277 More precisely, <code>--cherry-pick --right-only --no-merges</code> gives the exact
1278 list.</p></div>
1279 </dd>
1280 <dt class="hdlist1">
1281 --cherry
1282 </dt>
1283 <dd>
1284 <p>
1285         A synonym for <code>--right-only --cherry-mark --no-merges</code>; useful to
1286         limit the output to the commits on our side and mark those that
1287         have been applied to the other side of a forked history with
1288         <code>git log --cherry upstream...mybranch</code>, similar to
1289         <code>git cherry upstream mybranch</code>.
1290 </p>
1291 </dd>
1292 <dt class="hdlist1">
1293 -g
1294 </dt>
1295 <dt class="hdlist1">
1296 --walk-reflogs
1297 </dt>
1298 <dd>
1299 <p>
1300         Instead of walking the commit ancestry chain, walk
1301         reflog entries from the most recent one to older ones.
1302         When this option is used you cannot specify commits to
1303         exclude (that is, <em>&#94;commit</em>, <em>commit1..commit2</em>,
1304         and <em>commit1...commit2</em> notations cannot be used).
1305 </p>
1306 <div class="paragraph"><p>With <code>--pretty</code> format other than <code>oneline</code> and <code>reference</code> (for obvious reasons),
1307 this causes the output to have two extra lines of information
1308 taken from the reflog.  The reflog designator in the output may be shown
1309 as <code>ref@{&lt;Nth&gt;}</code> (where <em>&lt;Nth&gt;</em> is the reverse-chronological index in the
1310 reflog) or as <code>ref@{&lt;timestamp&gt;}</code> (with the <em>&lt;timestamp&gt;</em> for that entry),
1311 depending on a few rules:</p></div>
1312 <div class="openblock">
1313 <div class="content">
1314 <div class="olist arabic"><ol class="arabic">
1315 <li>
1316 <p>
1317 If the starting point is specified as <code>ref@{&lt;Nth&gt;}</code>, show the index
1318    format.
1319 </p>
1320 </li>
1321 <li>
1322 <p>
1323 If the starting point was specified as <code>ref@{now}</code>, show the
1324    timestamp format.
1325 </p>
1326 </li>
1327 <li>
1328 <p>
1329 If neither was used, but <code>--date</code> was given on the command line, show
1330    the timestamp in the format requested by <code>--date</code>.
1331 </p>
1332 </li>
1333 <li>
1334 <p>
1335 Otherwise, show the index format.
1336 </p>
1337 </li>
1338 </ol></div>
1339 </div></div>
1340 <div class="paragraph"><p>Under <code>--pretty=oneline</code>, the commit message is
1341 prefixed with this information on the same line.
1342 This option cannot be combined with <code>--reverse</code>.
1343 See also <a href="git-reflog.html">git-reflog(1)</a>.</p></div>
1344 <div class="paragraph"><p>Under <code>--pretty=reference</code>, this information will not be shown at all.</p></div>
1345 </dd>
1346 <dt class="hdlist1">
1347 --merge
1348 </dt>
1349 <dd>
1350 <p>
1351         Show commits touching conflicted paths in the range <code>HEAD...&lt;other&gt;</code>,
1352         where <code>&lt;other&gt;</code> is the first existing pseudoref in <code>MERGE_HEAD</code>,
1353         <code>CHERRY_PICK_HEAD</code>, <code>REVERT_HEAD</code> or <code>REBASE_HEAD</code>. Only works
1354         when the index has unmerged entries. This option can be used to show
1355         relevant commits when resolving conflicts from a 3-way merge.
1356 </p>
1357 </dd>
1358 <dt class="hdlist1">
1359 --boundary
1360 </dt>
1361 <dd>
1362 <p>
1363         Output excluded boundary commits. Boundary commits are
1364         prefixed with <code>-</code>.
1365 </p>
1366 </dd>
1367 </dl></div>
1368 </div>
1369 <div class="sect2">
1370 <h3 id="_history_simplification">History Simplification</h3>
1371 <div class="paragraph"><p>Sometimes you are only interested in parts of the history, for example the
1372 commits modifying a particular &lt;path&gt;. But there are two parts of
1373 <em>History Simplification</em>, one part is selecting the commits and the other
1374 is how to do it, as there are various strategies to simplify the history.</p></div>
1375 <div class="paragraph"><p>The following options select the commits to be shown:</p></div>
1376 <div class="dlist"><dl>
1377 <dt class="hdlist1">
1378 &lt;paths&gt;
1379 </dt>
1380 <dd>
1381 <p>
1382         Commits modifying the given &lt;paths&gt; are selected.
1383 </p>
1384 </dd>
1385 <dt class="hdlist1">
1386 --simplify-by-decoration
1387 </dt>
1388 <dd>
1389 <p>
1390         Commits that are referred by some branch or tag are selected.
1391 </p>
1392 </dd>
1393 </dl></div>
1394 <div class="paragraph"><p>Note that extra commits can be shown to give a meaningful history.</p></div>
1395 <div class="paragraph"><p>The following options affect the way the simplification is performed:</p></div>
1396 <div class="dlist"><dl>
1397 <dt class="hdlist1">
1398 Default mode
1399 </dt>
1400 <dd>
1401 <p>
1402         Simplifies the history to the simplest history explaining the
1403         final state of the tree. Simplest because it prunes some side
1404         branches if the end result is the same (i.e. merging branches
1405         with the same content)
1406 </p>
1407 </dd>
1408 <dt class="hdlist1">
1409 --show-pulls
1410 </dt>
1411 <dd>
1412 <p>
1413         Include all commits from the default mode, but also any merge
1414         commits that are not TREESAME to the first parent but are
1415         TREESAME to a later parent. This mode is helpful for showing
1416         the merge commits that "first introduced" a change to a branch.
1417 </p>
1418 </dd>
1419 <dt class="hdlist1">
1420 --full-history
1421 </dt>
1422 <dd>
1423 <p>
1424         Same as the default mode, but does not prune some history.
1425 </p>
1426 </dd>
1427 <dt class="hdlist1">
1428 --dense
1429 </dt>
1430 <dd>
1431 <p>
1432         Only the selected commits are shown, plus some to have a
1433         meaningful history.
1434 </p>
1435 </dd>
1436 <dt class="hdlist1">
1437 --sparse
1438 </dt>
1439 <dd>
1440 <p>
1441         All commits in the simplified history are shown.
1442 </p>
1443 </dd>
1444 <dt class="hdlist1">
1445 --simplify-merges
1446 </dt>
1447 <dd>
1448 <p>
1449         Additional option to <code>--full-history</code> to remove some needless
1450         merges from the resulting history, as there are no selected
1451         commits contributing to this merge.
1452 </p>
1453 </dd>
1454 <dt class="hdlist1">
1455 --ancestry-path[=&lt;commit&gt;]
1456 </dt>
1457 <dd>
1458 <p>
1459         When given a range of commits to display (e.g. <em>commit1..commit2</em>
1460         or <em>commit2 &#94;commit1</em>), only display commits in that range
1461         that are ancestors of &lt;commit&gt;, descendants of &lt;commit&gt;, or
1462         &lt;commit&gt; itself.  If no commit is specified, use <em>commit1</em> (the
1463         excluded part of the range) as &lt;commit&gt;.  Can be passed multiple
1464         times; if so, a commit is included if it is any of the commits
1465         given or if it is an ancestor or descendant of one of them.
1466 </p>
1467 </dd>
1468 </dl></div>
1469 <div class="paragraph"><p>A more detailed explanation follows.</p></div>
1470 <div class="paragraph"><p>Suppose you specified <code>foo</code> as the &lt;paths&gt;.  We shall call commits
1471 that modify <code>foo</code> !TREESAME, and the rest TREESAME.  (In a diff
1472 filtered for <code>foo</code>, they look different and equal, respectively.)</p></div>
1473 <div class="paragraph"><p>In the following, we will always refer to the same example history to
1474 illustrate the differences between simplification settings.  We assume
1475 that you are filtering for a file <code>foo</code> in this commit graph:</p></div>
1476 <div class="listingblock">
1477 <div class="content">
1478 <pre><code>          .-A---M---N---O---P---Q
1479          /     /   /   /   /   /
1480         I     B   C   D   E   Y
1481          \   /   /   /   /   /
1482           `-------------'   X</code></pre>
1483 </div></div>
1484 <div class="paragraph"><p>The horizontal line of history A---Q is taken to be the first parent of
1485 each merge.  The commits are:</p></div>
1486 <div class="ulist"><ul>
1487 <li>
1488 <p>
1489 <code>I</code> is the initial commit, in which <code>foo</code> exists with contents
1490   &#8220;asdf&#8221;, and a file <code>quux</code> exists with contents &#8220;quux&#8221;. Initial
1491   commits are compared to an empty tree, so <code>I</code> is !TREESAME.
1492 </p>
1493 </li>
1494 <li>
1495 <p>
1496 In <code>A</code>, <code>foo</code> contains just &#8220;foo&#8221;.
1497 </p>
1498 </li>
1499 <li>
1500 <p>
1501 <code>B</code> contains the same change as <code>A</code>.  Its merge <code>M</code> is trivial and
1502   hence TREESAME to all parents.
1503 </p>
1504 </li>
1505 <li>
1506 <p>
1507 <code>C</code> does not change <code>foo</code>, but its merge <code>N</code> changes it to &#8220;foobar&#8221;,
1508   so it is not TREESAME to any parent.
1509 </p>
1510 </li>
1511 <li>
1512 <p>
1513 <code>D</code> sets <code>foo</code> to &#8220;baz&#8221;. Its merge <code>O</code> combines the strings from
1514   <code>N</code> and <code>D</code> to &#8220;foobarbaz&#8221;; i.e., it is not TREESAME to any parent.
1515 </p>
1516 </li>
1517 <li>
1518 <p>
1519 <code>E</code> changes <code>quux</code> to &#8220;xyzzy&#8221;, and its merge <code>P</code> combines the
1520   strings to &#8220;quux xyzzy&#8221;. <code>P</code> is TREESAME to <code>O</code>, but not to <code>E</code>.
1521 </p>
1522 </li>
1523 <li>
1524 <p>
1525 <code>X</code> is an independent root commit that added a new file <code>side</code>, and <code>Y</code>
1526   modified it. <code>Y</code> is TREESAME to <code>X</code>. Its merge <code>Q</code> added <code>side</code> to <code>P</code>, and
1527   <code>Q</code> is TREESAME to <code>P</code>, but not to <code>Y</code>.
1528 </p>
1529 </li>
1530 </ul></div>
1531 <div class="paragraph"><p><code>rev-list</code> walks backwards through history, including or excluding
1532 commits based on whether <code>--full-history</code> and/or parent rewriting
1533 (via <code>--parents</code> or <code>--children</code>) are used. The following settings
1534 are available.</p></div>
1535 <div class="dlist"><dl>
1536 <dt class="hdlist1">
1537 Default mode
1538 </dt>
1539 <dd>
1540 <p>
1541         Commits are included if they are not TREESAME to any parent
1542         (though this can be changed, see <code>--sparse</code> below).  If the
1543         commit was a merge, and it was TREESAME to one parent, follow
1544         only that parent.  (Even if there are several TREESAME
1545         parents, follow only one of them.)  Otherwise, follow all
1546         parents.
1547 </p>
1548 <div class="paragraph"><p>This results in:</p></div>
1549 <div class="listingblock">
1550 <div class="content">
1551 <pre><code>          .-A---N---O
1552          /     /   /
1553         I---------D</code></pre>
1554 </div></div>
1555 <div class="paragraph"><p>Note how the rule to only follow the TREESAME parent, if one is
1556 available, removed <code>B</code> from consideration entirely.  <code>C</code> was
1557 considered via <code>N</code>, but is TREESAME.  Root commits are compared to an
1558 empty tree, so <code>I</code> is !TREESAME.</p></div>
1559 <div class="paragraph"><p>Parent/child relations are only visible with <code>--parents</code>, but that does
1560 not affect the commits selected in default mode, so we have shown the
1561 parent lines.</p></div>
1562 </dd>
1563 <dt class="hdlist1">
1564 --full-history without parent rewriting
1565 </dt>
1566 <dd>
1567 <p>
1568         This mode differs from the default in one point: always follow
1569         all parents of a merge, even if it is TREESAME to one of them.
1570         Even if more than one side of the merge has commits that are
1571         included, this does not imply that the merge itself is!  In
1572         the example, we get
1573 </p>
1574 <div class="listingblock">
1575 <div class="content">
1576 <pre><code>        I  A  B  N  D  O  P  Q</code></pre>
1577 </div></div>
1578 <div class="paragraph"><p><code>M</code> was excluded because it is TREESAME to both parents.  <code>E</code>,
1579 <code>C</code> and <code>B</code> were all walked, but only <code>B</code> was !TREESAME, so the others
1580 do not appear.</p></div>
1581 <div class="paragraph"><p>Note that without parent rewriting, it is not really possible to talk
1582 about the parent/child relationships between the commits, so we show
1583 them disconnected.</p></div>
1584 </dd>
1585 <dt class="hdlist1">
1586 --full-history with parent rewriting
1587 </dt>
1588 <dd>
1589 <p>
1590         Ordinary commits are only included if they are !TREESAME
1591         (though this can be changed, see <code>--sparse</code> below).
1592 </p>
1593 <div class="paragraph"><p>Merges are always included.  However, their parent list is rewritten:
1594 Along each parent, prune away commits that are not included
1595 themselves.  This results in</p></div>
1596 <div class="listingblock">
1597 <div class="content">
1598 <pre><code>          .-A---M---N---O---P---Q
1599          /     /   /   /   /
1600         I     B   /   D   /
1601          \   /   /   /   /
1602           `-------------'</code></pre>
1603 </div></div>
1604 <div class="paragraph"><p>Compare to <code>--full-history</code> without rewriting above.  Note that <code>E</code>
1605 was pruned away because it is TREESAME, but the parent list of P was
1606 rewritten to contain <code>E</code>'s parent <code>I</code>.  The same happened for <code>C</code> and
1607 <code>N</code>, and <code>X</code>, <code>Y</code> and <code>Q</code>.</p></div>
1608 </dd>
1609 </dl></div>
1610 <div class="paragraph"><p>In addition to the above settings, you can change whether TREESAME
1611 affects inclusion:</p></div>
1612 <div class="dlist"><dl>
1613 <dt class="hdlist1">
1614 --dense
1615 </dt>
1616 <dd>
1617 <p>
1618         Commits that are walked are included if they are not TREESAME
1619         to any parent.
1620 </p>
1621 </dd>
1622 <dt class="hdlist1">
1623 --sparse
1624 </dt>
1625 <dd>
1626 <p>
1627         All commits that are walked are included.
1628 </p>
1629 <div class="paragraph"><p>Note that without <code>--full-history</code>, this still simplifies merges: if
1630 one of the parents is TREESAME, we follow only that one, so the other
1631 sides of the merge are never walked.</p></div>
1632 </dd>
1633 <dt class="hdlist1">
1634 --simplify-merges
1635 </dt>
1636 <dd>
1637 <p>
1638         First, build a history graph in the same way that
1639         <code>--full-history</code> with parent rewriting does (see above).
1640 </p>
1641 <div class="paragraph"><p>Then simplify each commit <code>C</code> to its replacement <code>C'</code> in the final
1642 history according to the following rules:</p></div>
1643 <div class="openblock">
1644 <div class="content">
1645 <div class="ulist"><ul>
1646 <li>
1647 <p>
1648 Set <code>C'</code> to <code>C</code>.
1649 </p>
1650 </li>
1651 <li>
1652 <p>
1653 Replace each parent <code>P</code> of <code>C'</code> with its simplification <code>P'</code>.  In
1654   the process, drop parents that are ancestors of other parents or that are
1655   root commits TREESAME to an empty tree, and remove duplicates, but take care
1656   to never drop all parents that we are TREESAME to.
1657 </p>
1658 </li>
1659 <li>
1660 <p>
1661 If after this parent rewriting, <code>C'</code> is a root or merge commit (has
1662   zero or &gt;1 parents), a boundary commit, or !TREESAME, it remains.
1663   Otherwise, it is replaced with its only parent.
1664 </p>
1665 </li>
1666 </ul></div>
1667 </div></div>
1668 <div class="paragraph"><p>The effect of this is best shown by way of comparing to
1669 <code>--full-history</code> with parent rewriting.  The example turns into:</p></div>
1670 <div class="listingblock">
1671 <div class="content">
1672 <pre><code>          .-A---M---N---O
1673          /     /       /
1674         I     B       D
1675          \   /       /
1676           `---------'</code></pre>
1677 </div></div>
1678 <div class="paragraph"><p>Note the major differences in <code>N</code>, <code>P</code>, and <code>Q</code> over <code>--full-history</code>:</p></div>
1679 <div class="openblock">
1680 <div class="content">
1681 <div class="ulist"><ul>
1682 <li>
1683 <p>
1684 <code>N</code>'s parent list had <code>I</code> removed, because it is an ancestor of the
1685   other parent <code>M</code>.  Still, <code>N</code> remained because it is !TREESAME.
1686 </p>
1687 </li>
1688 <li>
1689 <p>
1690 <code>P</code>'s parent list similarly had <code>I</code> removed.  <code>P</code> was then
1691   removed completely, because it had one parent and is TREESAME.
1692 </p>
1693 </li>
1694 <li>
1695 <p>
1696 <code>Q</code>'s parent list had <code>Y</code> simplified to <code>X</code>. <code>X</code> was then removed, because it
1697   was a TREESAME root. <code>Q</code> was then removed completely, because it had one
1698   parent and is TREESAME.
1699 </p>
1700 </li>
1701 </ul></div>
1702 </div></div>
1703 </dd>
1704 </dl></div>
1705 <div class="paragraph"><p>There is another simplification mode available:</p></div>
1706 <div class="dlist"><dl>
1707 <dt class="hdlist1">
1708 --ancestry-path[=&lt;commit&gt;]
1709 </dt>
1710 <dd>
1711 <p>
1712         Limit the displayed commits to those which are an ancestor of
1713         &lt;commit&gt;, or which are a descendant of &lt;commit&gt;, or are &lt;commit&gt;
1714         itself.
1715 </p>
1716 <div class="paragraph"><p>As an example use case, consider the following commit history:</p></div>
1717 <div class="listingblock">
1718 <div class="content">
1719 <pre><code>            D---E-------F
1720            /     \       \
1721           B---C---G---H---I---J
1722          /                     \
1723         A-------K---------------L--M</code></pre>
1724 </div></div>
1725 <div class="paragraph"><p>A regular <em>D..M</em> computes the set of commits that are ancestors of <code>M</code>,
1726 but excludes the ones that are ancestors of <code>D</code>. This is useful to see
1727 what happened to the history leading to <code>M</code> since <code>D</code>, in the sense
1728 that &#8220;what does <code>M</code> have that did not exist in <code>D</code>&#8221;. The result in this
1729 example would be all the commits, except <code>A</code> and <code>B</code> (and <code>D</code> itself,
1730 of course).</p></div>
1731 <div class="paragraph"><p>When we want to find out what commits in <code>M</code> are contaminated with the
1732 bug introduced by <code>D</code> and need fixing, however, we might want to view
1733 only the subset of <em>D..M</em> that are actually descendants of <code>D</code>, i.e.
1734 excluding <code>C</code> and <code>K</code>. This is exactly what the <code>--ancestry-path</code>
1735 option does. Applied to the <em>D..M</em> range, it results in:</p></div>
1736 <div class="listingblock">
1737 <div class="content">
1738 <pre><code>                E-------F
1739                  \       \
1740                   G---H---I---J
1741                                \
1742                                 L--M</code></pre>
1743 </div></div>
1744 <div class="paragraph"><p>We can also use <code>--ancestry-path=D</code> instead of <code>--ancestry-path</code> which
1745 means the same thing when applied to the <em>D..M</em> range but is just more
1746 explicit.</p></div>
1747 <div class="paragraph"><p>If we instead are interested in a given topic within this range, and all
1748 commits affected by that topic, we may only want to view the subset of
1749 <code>D..M</code> which contain that topic in their ancestry path.  So, using
1750 <code>--ancestry-path=H D..M</code> for example would result in:</p></div>
1751 <div class="listingblock">
1752 <div class="content">
1753 <pre><code>                E
1754                  \
1755                   G---H---I---J
1756                                \
1757                                 L--M</code></pre>
1758 </div></div>
1759 <div class="paragraph"><p>Whereas <code>--ancestry-path=K D..M</code> would result in</p></div>
1760 <div class="listingblock">
1761 <div class="content">
1762 <pre><code>                K---------------L--M</code></pre>
1763 </div></div>
1764 </dd>
1765 </dl></div>
1766 <div class="paragraph"><p>Before discussing another option, <code>--show-pulls</code>, we need to
1767 create a new example history.</p></div>
1768 <div class="paragraph"><p>A common problem users face when looking at simplified history is that a
1769 commit they know changed a file somehow does not appear in the file&#8217;s
1770 simplified history. Let&#8217;s demonstrate a new example and show how options
1771 such as <code>--full-history</code> and <code>--simplify-merges</code> works in that case:</p></div>
1772 <div class="listingblock">
1773 <div class="content">
1774 <pre><code>          .-A---M-----C--N---O---P
1775          /     / \  \  \/   /   /
1776         I     B   \  R-'`-Z'   /
1777          \   /     \/         /
1778           \ /      /\        /
1779            `---X--'  `---Y--'</code></pre>
1780 </div></div>
1781 <div class="paragraph"><p>For this example, suppose <code>I</code> created <code>file.txt</code> which was modified by
1782 <code>A</code>, <code>B</code>, and <code>X</code> in different ways. The single-parent commits <code>C</code>, <code>Z</code>,
1783 and <code>Y</code> do not change <code>file.txt</code>. The merge commit <code>M</code> was created by
1784 resolving the merge conflict to include both changes from <code>A</code> and <code>B</code>
1785 and hence is not TREESAME to either. The merge commit <code>R</code>, however, was
1786 created by ignoring the contents of <code>file.txt</code> at <code>M</code> and taking only
1787 the contents of <code>file.txt</code> at <code>X</code>. Hence, <code>R</code> is TREESAME to <code>X</code> but not
1788 <code>M</code>. Finally, the natural merge resolution to create <code>N</code> is to take the
1789 contents of <code>file.txt</code> at <code>R</code>, so <code>N</code> is TREESAME to <code>R</code> but not <code>C</code>.
1790 The merge commits <code>O</code> and <code>P</code> are TREESAME to their first parents, but
1791 not to their second parents, <code>Z</code> and <code>Y</code> respectively.</p></div>
1792 <div class="paragraph"><p>When using the default mode, <code>N</code> and <code>R</code> both have a TREESAME parent, so
1793 those edges are walked and the others are ignored. The resulting history
1794 graph is:</p></div>
1795 <div class="listingblock">
1796 <div class="content">
1797 <pre><code>        I---X</code></pre>
1798 </div></div>
1799 <div class="paragraph"><p>When using <code>--full-history</code>, Git walks every edge. This will discover
1800 the commits <code>A</code> and <code>B</code> and the merge <code>M</code>, but also will reveal the
1801 merge commits <code>O</code> and <code>P</code>. With parent rewriting, the resulting graph is:</p></div>
1802 <div class="listingblock">
1803 <div class="content">
1804 <pre><code>          .-A---M--------N---O---P
1805          /     / \  \  \/   /   /
1806         I     B   \  R-'`--'   /
1807          \   /     \/         /
1808           \ /      /\        /
1809            `---X--'  `------'</code></pre>
1810 </div></div>
1811 <div class="paragraph"><p>Here, the merge commits <code>O</code> and <code>P</code> contribute extra noise, as they did
1812 not actually contribute a change to <code>file.txt</code>. They only merged a topic
1813 that was based on an older version of <code>file.txt</code>. This is a common
1814 issue in repositories using a workflow where many contributors work in
1815 parallel and merge their topic branches along a single trunk: many
1816 unrelated merges appear in the <code>--full-history</code> results.</p></div>
1817 <div class="paragraph"><p>When using the <code>--simplify-merges</code> option, the commits <code>O</code> and <code>P</code>
1818 disappear from the results. This is because the rewritten second parents
1819 of <code>O</code> and <code>P</code> are reachable from their first parents. Those edges are
1820 removed and then the commits look like single-parent commits that are
1821 TREESAME to their parent. This also happens to the commit <code>N</code>, resulting
1822 in a history view as follows:</p></div>
1823 <div class="listingblock">
1824 <div class="content">
1825 <pre><code>          .-A---M--.
1826          /     /    \
1827         I     B      R
1828          \   /      /
1829           \ /      /
1830            `---X--'</code></pre>
1831 </div></div>
1832 <div class="paragraph"><p>In this view, we see all of the important single-parent changes from
1833 <code>A</code>, <code>B</code>, and <code>X</code>. We also see the carefully-resolved merge <code>M</code> and the
1834 not-so-carefully-resolved merge <code>R</code>. This is usually enough information
1835 to determine why the commits <code>A</code> and <code>B</code> "disappeared" from history in
1836 the default view. However, there are a few issues with this approach.</p></div>
1837 <div class="paragraph"><p>The first issue is performance. Unlike any previous option, the
1838 <code>--simplify-merges</code> option requires walking the entire commit history
1839 before returning a single result. This can make the option difficult to
1840 use for very large repositories.</p></div>
1841 <div class="paragraph"><p>The second issue is one of auditing. When many contributors are working
1842 on the same repository, it is important which merge commits introduced
1843 a change into an important branch. The problematic merge <code>R</code> above is
1844 not likely to be the merge commit that was used to merge into an
1845 important branch. Instead, the merge <code>N</code> was used to merge <code>R</code> and <code>X</code>
1846 into the important branch. This commit may have information about why
1847 the change <code>X</code> came to override the changes from <code>A</code> and <code>B</code> in its
1848 commit message.</p></div>
1849 <div class="dlist"><dl>
1850 <dt class="hdlist1">
1851 --show-pulls
1852 </dt>
1853 <dd>
1854 <p>
1855         In addition to the commits shown in the default history, show
1856         each merge commit that is not TREESAME to its first parent but
1857         is TREESAME to a later parent.
1858 </p>
1859 <div class="paragraph"><p>When a merge commit is included by <code>--show-pulls</code>, the merge is
1860 treated as if it "pulled" the change from another branch. When using
1861 <code>--show-pulls</code> on this example (and no other options) the resulting
1862 graph is:</p></div>
1863 <div class="listingblock">
1864 <div class="content">
1865 <pre><code>        I---X---R---N</code></pre>
1866 </div></div>
1867 <div class="paragraph"><p>Here, the merge commits <code>R</code> and <code>N</code> are included because they pulled
1868 the commits <code>X</code> and <code>R</code> into the base branch, respectively. These
1869 merges are the reason the commits <code>A</code> and <code>B</code> do not appear in the
1870 default history.</p></div>
1871 <div class="paragraph"><p>When <code>--show-pulls</code> is paired with <code>--simplify-merges</code>, the
1872 graph includes all of the necessary information:</p></div>
1873 <div class="listingblock">
1874 <div class="content">
1875 <pre><code>          .-A---M--.   N
1876          /     /    \ /
1877         I     B      R
1878          \   /      /
1879           \ /      /
1880            `---X--'</code></pre>
1881 </div></div>
1882 <div class="paragraph"><p>Notice that since <code>M</code> is reachable from <code>R</code>, the edge from <code>N</code> to <code>M</code>
1883 was simplified away. However, <code>N</code> still appears in the history as an
1884 important commit because it "pulled" the change <code>R</code> into the main
1885 branch.</p></div>
1886 </dd>
1887 </dl></div>
1888 <div class="paragraph"><p>The <code>--simplify-by-decoration</code> option allows you to view only the
1889 big picture of the topology of the history, by omitting commits
1890 that are not referenced by tags.  Commits are marked as !TREESAME
1891 (in other words, kept after history simplification rules described
1892 above) if (1) they are referenced by tags, or (2) they change the
1893 contents of the paths given on the command line.  All other
1894 commits are marked as TREESAME (subject to be simplified away).</p></div>
1895 </div>
1896 <div class="sect2">
1897 <h3 id="_commit_ordering">Commit Ordering</h3>
1898 <div class="paragraph"><p>By default, the commits are shown in reverse chronological order.</p></div>
1899 <div class="dlist"><dl>
1900 <dt class="hdlist1">
1901 --date-order
1902 </dt>
1903 <dd>
1904 <p>
1905         Show no parents before all of its children are shown, but
1906         otherwise show commits in the commit timestamp order.
1907 </p>
1908 </dd>
1909 <dt class="hdlist1">
1910 --author-date-order
1911 </dt>
1912 <dd>
1913 <p>
1914         Show no parents before all of its children are shown, but
1915         otherwise show commits in the author timestamp order.
1916 </p>
1917 </dd>
1918 <dt class="hdlist1">
1919 --topo-order
1920 </dt>
1921 <dd>
1922 <p>
1923         Show no parents before all of its children are shown, and
1924         avoid showing commits on multiple lines of history
1925         intermixed.
1926 </p>
1927 <div class="paragraph"><p>For example, in a commit history like this:</p></div>
1928 <div class="listingblock">
1929 <div class="content">
1930 <pre><code>    ---1----2----4----7
1931         \              \
1932          3----5----6----8---</code></pre>
1933 </div></div>
1934 <div class="paragraph"><p>where the numbers denote the order of commit timestamps, <code>git
1935 rev-list</code> and friends with <code>--date-order</code> show the commits in the
1936 timestamp order: 8 7 6 5 4 3 2 1.</p></div>
1937 <div class="paragraph"><p>With <code>--topo-order</code>, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
1938 3 1); some older commits are shown before newer ones in order to
1939 avoid showing the commits from two parallel development track mixed
1940 together.</p></div>
1941 </dd>
1942 <dt class="hdlist1">
1943 --reverse
1944 </dt>
1945 <dd>
1946 <p>
1947         Output the commits chosen to be shown (see Commit Limiting
1948         section above) in reverse order. Cannot be combined with
1949         <code>--walk-reflogs</code>.
1950 </p>
1951 </dd>
1952 </dl></div>
1953 </div>
1954 <div class="sect2">
1955 <h3 id="_object_traversal">Object Traversal</h3>
1956 <div class="paragraph"><p>These options are mostly targeted for packing of Git repositories.</p></div>
1957 <div class="dlist"><dl>
1958 <dt class="hdlist1">
1959 --no-walk[=(sorted|unsorted)]
1960 </dt>
1961 <dd>
1962 <p>
1963         Only show the given commits, but do not traverse their ancestors.
1964         This has no effect if a range is specified. If the argument
1965         <code>unsorted</code> is given, the commits are shown in the order they were
1966         given on the command line. Otherwise (if <code>sorted</code> or no argument
1967         was given), the commits are shown in reverse chronological order
1968         by commit time.
1969         Cannot be combined with <code>--graph</code>.
1970 </p>
1971 </dd>
1972 <dt class="hdlist1">
1973 --do-walk
1974 </dt>
1975 <dd>
1976 <p>
1977         Overrides a previous <code>--no-walk</code>.
1978 </p>
1979 </dd>
1980 </dl></div>
1981 </div>
1982 <div class="sect2">
1983 <h3 id="_commit_formatting">Commit Formatting</h3>
1984 <div class="dlist"><dl>
1985 <dt class="hdlist1">
1986 --pretty[=&lt;format&gt;]
1987 </dt>
1988 <dt class="hdlist1">
1989 --format=&lt;format&gt;
1990 </dt>
1991 <dd>
1992 <p>
1993         Pretty-print the contents of the commit logs in a given format,
1994         where <em>&lt;format&gt;</em> can be one of <em>oneline</em>, <em>short</em>, <em>medium</em>,
1995         <em>full</em>, <em>fuller</em>, <em>reference</em>, <em>email</em>, <em>raw</em>, <em>format:&lt;string&gt;</em>
1996         and <em>tformat:&lt;string&gt;</em>.  When <em>&lt;format&gt;</em> is none of the above,
1997         and has <em>%placeholder</em> in it, it acts as if
1998         <em>--pretty=tformat:&lt;format&gt;</em> were given.
1999 </p>
2000 <div class="paragraph"><p>See the "PRETTY FORMATS" section for some additional details for each
2001 format.  When <em>=&lt;format&gt;</em> part is omitted, it defaults to <em>medium</em>.</p></div>
2002 <div class="paragraph"><p>Note: you can specify the default pretty format in the repository
2003 configuration (see <a href="git-config.html">git-config(1)</a>).</p></div>
2004 </dd>
2005 <dt class="hdlist1">
2006 --abbrev-commit
2007 </dt>
2008 <dd>
2009 <p>
2010         Instead of showing the full 40-byte hexadecimal commit object
2011         name, show a prefix that names the object uniquely.
2012         "--abbrev=&lt;n&gt;" (which also modifies diff output, if it is displayed)
2013         option can be used to specify the minimum length of the prefix.
2014 </p>
2015 <div class="paragraph"><p>This should make "--pretty=oneline" a whole lot more readable for
2016 people using 80-column terminals.</p></div>
2017 </dd>
2018 <dt class="hdlist1">
2019 --no-abbrev-commit
2020 </dt>
2021 <dd>
2022 <p>
2023         Show the full 40-byte hexadecimal commit object name. This negates
2024         <code>--abbrev-commit</code>, either explicit or implied by other options such
2025         as "--oneline". It also overrides the <code>log.abbrevCommit</code> variable.
2026 </p>
2027 </dd>
2028 <dt class="hdlist1">
2029 --oneline
2030 </dt>
2031 <dd>
2032 <p>
2033         This is a shorthand for "--pretty=oneline --abbrev-commit"
2034         used together.
2035 </p>
2036 </dd>
2037 <dt class="hdlist1">
2038 --encoding=&lt;encoding&gt;
2039 </dt>
2040 <dd>
2041 <p>
2042         Commit objects record the character encoding used for the log message
2043         in their encoding header; this option can be used to tell the
2044         command to re-code the commit log message in the encoding
2045         preferred by the user.  For non plumbing commands this
2046         defaults to UTF-8. Note that if an object claims to be encoded
2047         in <code>X</code> and we are outputting in <code>X</code>, we will output the object
2048         verbatim; this means that invalid sequences in the original
2049         commit may be copied to the output. Likewise, if iconv(3) fails
2050         to convert the commit, we will quietly output the original
2051         object verbatim.
2052 </p>
2053 </dd>
2054 <dt class="hdlist1">
2055 --expand-tabs=&lt;n&gt;
2056 </dt>
2057 <dt class="hdlist1">
2058 --expand-tabs
2059 </dt>
2060 <dt class="hdlist1">
2061 --no-expand-tabs
2062 </dt>
2063 <dd>
2064 <p>
2065         Perform a tab expansion (replace each tab with enough spaces
2066         to fill to the next display column that is a multiple of <em>&lt;n&gt;</em>)
2067         in the log message before showing it in the output.
2068         <code>--expand-tabs</code> is a short-hand for <code>--expand-tabs=8</code>, and
2069         <code>--no-expand-tabs</code> is a short-hand for <code>--expand-tabs=0</code>,
2070         which disables tab expansion.
2071 </p>
2072 <div class="paragraph"><p>By default, tabs are expanded in pretty formats that indent the log
2073 message by 4 spaces (i.e.  <em>medium</em>, which is the default, <em>full</em>,
2074 and <em>fuller</em>).</p></div>
2075 </dd>
2076 <dt class="hdlist1">
2077 --notes[=&lt;ref&gt;]
2078 </dt>
2079 <dd>
2080 <p>
2081         Show the notes (see <a href="git-notes.html">git-notes(1)</a>) that annotate the
2082         commit, when showing the commit log message.  This is the default
2083         for <code>git log</code>, <code>git show</code> and <code>git whatchanged</code> commands when
2084         there is no <code>--pretty</code>, <code>--format</code>, or <code>--oneline</code> option given
2085         on the command line.
2086 </p>
2087 <div class="paragraph"><p>By default, the notes shown are from the notes refs listed in the
2088 <code>core.notesRef</code> and <code>notes.displayRef</code> variables (or corresponding
2089 environment overrides). See <a href="git-config.html">git-config(1)</a> for more details.</p></div>
2090 <div class="paragraph"><p>With an optional <em>&lt;ref&gt;</em> argument, use the ref to find the notes
2091 to display.  The ref can specify the full refname when it begins
2092 with <code>refs/notes/</code>; when it begins with <code>notes/</code>, <code>refs/</code> and otherwise
2093 <code>refs/notes/</code> is prefixed to form the full name of the ref.</p></div>
2094 <div class="paragraph"><p>Multiple --notes options can be combined to control which notes are
2095 being displayed. Examples: "--notes=foo" will show only notes from
2096 "refs/notes/foo"; "--notes=foo --notes" will show both notes from
2097 "refs/notes/foo" and from the default notes ref(s).</p></div>
2098 </dd>
2099 <dt class="hdlist1">
2100 --no-notes
2101 </dt>
2102 <dd>
2103 <p>
2104         Do not show notes. This negates the above <code>--notes</code> option, by
2105         resetting the list of notes refs from which notes are shown.
2106         Options are parsed in the order given on the command line, so e.g.
2107         "--notes --notes=foo --no-notes --notes=bar" will only show notes
2108         from "refs/notes/bar".
2109 </p>
2110 </dd>
2111 <dt class="hdlist1">
2112 --show-notes-by-default
2113 </dt>
2114 <dd>
2115 <p>
2116         Show the default notes unless options for displaying specific
2117         notes are given.
2118 </p>
2119 </dd>
2120 <dt class="hdlist1">
2121 --show-notes[=&lt;ref&gt;]
2122 </dt>
2123 <dt class="hdlist1">
2124 --[no-]standard-notes
2125 </dt>
2126 <dd>
2127 <p>
2128         These options are deprecated. Use the above --notes/--no-notes
2129         options instead.
2130 </p>
2131 </dd>
2132 <dt class="hdlist1">
2133 --show-signature
2134 </dt>
2135 <dd>
2136 <p>
2137         Check the validity of a signed commit object by passing the signature
2138         to <code>gpg --verify</code> and show the output.
2139 </p>
2140 </dd>
2141 <dt class="hdlist1">
2142 --relative-date
2143 </dt>
2144 <dd>
2145 <p>
2146         Synonym for <code>--date=relative</code>.
2147 </p>
2148 </dd>
2149 <dt class="hdlist1">
2150 --date=&lt;format&gt;
2151 </dt>
2152 <dd>
2153 <p>
2154         Only takes effect for dates shown in human-readable format, such
2155         as when using <code>--pretty</code>. <code>log.date</code> config variable sets a default
2156         value for the log command&#8217;s <code>--date</code> option. By default, dates
2157         are shown in the original time zone (either committer&#8217;s or
2158         author&#8217;s). If <code>-local</code> is appended to the format (e.g.,
2159         <code>iso-local</code>), the user&#8217;s local time zone is used instead.
2160 </p>
2161 <div class="openblock">
2162 <div class="content">
2163 <div class="paragraph"><p><code>--date=relative</code> shows dates relative to the current time,
2164 e.g. &#8220;2 hours ago&#8221;. The <code>-local</code> option has no effect for
2165 <code>--date=relative</code>.</p></div>
2166 <div class="paragraph"><p><code>--date=local</code> is an alias for <code>--date=default-local</code>.</p></div>
2167 <div class="paragraph"><p><code>--date=iso</code> (or <code>--date=iso8601</code>) shows timestamps in a ISO 8601-like format.
2168 The differences to the strict ISO 8601 format are:</p></div>
2169 <div class="ulist"><ul>
2170 <li>
2171 <p>
2172 a space instead of the <code>T</code> date/time delimiter
2173 </p>
2174 </li>
2175 <li>
2176 <p>
2177 a space between time and time zone
2178 </p>
2179 </li>
2180 <li>
2181 <p>
2182 no colon between hours and minutes of the time zone
2183 </p>
2184 </li>
2185 </ul></div>
2186 <div class="paragraph"><p><code>--date=iso-strict</code> (or <code>--date=iso8601-strict</code>) shows timestamps in strict
2187 ISO 8601 format.</p></div>
2188 <div class="paragraph"><p><code>--date=rfc</code> (or <code>--date=rfc2822</code>) shows timestamps in RFC 2822
2189 format, often found in email messages.</p></div>
2190 <div class="paragraph"><p><code>--date=short</code> shows only the date, but not the time, in <code>YYYY-MM-DD</code> format.</p></div>
2191 <div class="paragraph"><p><code>--date=raw</code> shows the date as seconds since the epoch (1970-01-01
2192 00:00:00 UTC), followed by a space, and then the timezone as an offset
2193 from UTC (a <code>+</code> or <code>-</code> with four digits; the first two are hours, and
2194 the second two are minutes). I.e., as if the timestamp were formatted
2195 with <code>strftime("%s %z")</code>).
2196 Note that the <code>-local</code> option does not affect the seconds-since-epoch
2197 value (which is always measured in UTC), but does switch the accompanying
2198 timezone value.</p></div>
2199 <div class="paragraph"><p><code>--date=human</code> shows the timezone if the timezone does not match the
2200 current time-zone, and doesn&#8217;t print the whole date if that matches
2201 (ie skip printing year for dates that are "this year", but also skip
2202 the whole date itself if it&#8217;s in the last few days and we can just say
2203 what weekday it was).  For older dates the hour and minute is also
2204 omitted.</p></div>
2205 <div class="paragraph"><p><code>--date=unix</code> shows the date as a Unix epoch timestamp (seconds since
2206 1970).  As with <code>--raw</code>, this is always in UTC and therefore <code>-local</code>
2207 has no effect.</p></div>
2208 <div class="paragraph"><p><code>--date=format:...</code> feeds the format <code>...</code> to your system <code>strftime</code>,
2209 except for %s, %z, and %Z, which are handled internally.
2210 Use <code>--date=format:%c</code> to show the date in your system locale&#8217;s
2211 preferred format.  See the <code>strftime</code> manual for a complete list of
2212 format placeholders. When using <code>-local</code>, the correct syntax is
2213 <code>--date=format-local:...</code>.</p></div>
2214 <div class="paragraph"><p><code>--date=default</code> is the default format, and is based on ctime(3)
2215 output.  It shows a single line with three-letter day of the week,
2216 three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS"
2217 format, followed by 4-digit year, plus timezone information, unless
2218 the local time zone is used, e.g. <code>Thu Jan 1 00:00:00 1970 +0000</code>.</p></div>
2219 </div></div>
2220 </dd>
2221 <dt class="hdlist1">
2222 --parents
2223 </dt>
2224 <dd>
2225 <p>
2226         Print also the parents of the commit (in the form "commit parent&#8230;").
2227         Also enables parent rewriting, see <em>History Simplification</em> above.
2228 </p>
2229 </dd>
2230 <dt class="hdlist1">
2231 --children
2232 </dt>
2233 <dd>
2234 <p>
2235         Print also the children of the commit (in the form "commit child&#8230;").
2236         Also enables parent rewriting, see <em>History Simplification</em> above.
2237 </p>
2238 </dd>
2239 <dt class="hdlist1">
2240 --left-right
2241 </dt>
2242 <dd>
2243 <p>
2244         Mark which side of a symmetric difference a commit is reachable from.
2245         Commits from the left side are prefixed with <code>&lt;</code> and those from
2246         the right with <code>&gt;</code>.  If combined with <code>--boundary</code>, those
2247         commits are prefixed with <code>-</code>.
2248 </p>
2249 <div class="paragraph"><p>For example, if you have this topology:</p></div>
2250 <div class="listingblock">
2251 <div class="content">
2252 <pre><code>             y---b---b  branch B
2253             / \ /
2254            /   .
2255           /   / \
2256          o---x---a---a  branch A</code></pre>
2257 </div></div>
2258 <div class="paragraph"><p>you would get an output like this:</p></div>
2259 <div class="listingblock">
2260 <div class="content">
2261 <pre><code>        $ git rev-list --left-right --boundary --pretty=oneline A...B
2262
2263         &gt;bbbbbbb... 3rd on b
2264         &gt;bbbbbbb... 2nd on b
2265         &lt;aaaaaaa... 3rd on a
2266         &lt;aaaaaaa... 2nd on a
2267         -yyyyyyy... 1st on b
2268         -xxxxxxx... 1st on a</code></pre>
2269 </div></div>
2270 </dd>
2271 <dt class="hdlist1">
2272 --graph
2273 </dt>
2274 <dd>
2275 <p>
2276         Draw a text-based graphical representation of the commit history
2277         on the left hand side of the output.  This may cause extra lines
2278         to be printed in between commits, in order for the graph history
2279         to be drawn properly.
2280         Cannot be combined with <code>--no-walk</code>.
2281 </p>
2282 <div class="paragraph"><p>This enables parent rewriting, see <em>History Simplification</em> above.</p></div>
2283 <div class="paragraph"><p>This implies the <code>--topo-order</code> option by default, but the
2284 <code>--date-order</code> option may also be specified.</p></div>
2285 </dd>
2286 <dt class="hdlist1">
2287 --show-linear-break[=&lt;barrier&gt;]
2288 </dt>
2289 <dd>
2290 <p>
2291         When --graph is not used, all history branches are flattened
2292         which can make it hard to see that the two consecutive commits
2293         do not belong to a linear branch. This option puts a barrier
2294         in between them in that case. If <code>&lt;barrier&gt;</code> is specified, it
2295         is the string that will be shown instead of the default one.
2296 </p>
2297 </dd>
2298 </dl></div>
2299 </div>
2300 </div>
2301 </div>
2302 <div class="sect1">
2303 <h2 id="_output">OUTPUT</h2>
2304 <div class="sectionbody">
2305 <div class="paragraph"><p>When there are no conflicts, the output of this command is usable as
2306 input to <code>git update-ref --stdin</code>.  It is of the form:</p></div>
2307 <div class="literalblock">
2308 <div class="content">
2309 <pre><code>update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
2310 update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
2311 update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}</code></pre>
2312 </div></div>
2313 <div class="paragraph"><p>where the number of refs updated depends on the arguments passed and
2314 the shape of the history being replayed.  When using <code>--advance</code>, the
2315 number of refs updated is always one, but for <code>--onto</code>, it can be one
2316 or more (rebasing multiple branches simultaneously is supported).</p></div>
2317 </div>
2318 </div>
2319 <div class="sect1">
2320 <h2 id="_exit_status">EXIT STATUS</h2>
2321 <div class="sectionbody">
2322 <div class="paragraph"><p>For a successful, non-conflicted replay, the exit status is 0.  When
2323 the replay has conflicts, the exit status is 1.  If the replay is not
2324 able to complete (or start) due to some kind of error, the exit status
2325 is something other than 0 or 1.</p></div>
2326 </div>
2327 </div>
2328 <div class="sect1">
2329 <h2 id="_examples">EXAMPLES</h2>
2330 <div class="sectionbody">
2331 <div class="paragraph"><p>To simply rebase <code>mybranch</code> onto <code>target</code>:</p></div>
2332 <div class="listingblock">
2333 <div class="content">
2334 <pre><code>$ git replay --onto target origin/main..mybranch
2335 update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}</code></pre>
2336 </div></div>
2337 <div class="paragraph"><p>To cherry-pick the commits from mybranch onto target:</p></div>
2338 <div class="listingblock">
2339 <div class="content">
2340 <pre><code>$ git replay --advance target origin/main..mybranch
2341 update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}</code></pre>
2342 </div></div>
2343 <div class="paragraph"><p>Note that the first two examples replay the exact same commits and on
2344 top of the exact same new base, they only differ in that the first
2345 provides instructions to make mybranch point at the new commits and
2346 the second provides instructions to make target point at them.</p></div>
2347 <div class="paragraph"><p>What if you have a stack of branches, one depending upon another, and
2348 you&#8217;d really like to rebase the whole set?</p></div>
2349 <div class="listingblock">
2350 <div class="content">
2351 <pre><code>$ git replay --contained --onto origin/main origin/main..tipbranch
2352 update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
2353 update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
2354 update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH}</code></pre>
2355 </div></div>
2356 <div class="paragraph"><p>When calling <code>git replay</code>, one does not need to specify a range of
2357 commits to replay using the syntax <code>A..B</code>; any range expression will
2358 do:</p></div>
2359 <div class="listingblock">
2360 <div class="content">
2361 <pre><code>$ git replay --onto origin/main ^base branch1 branch2 branch3
2362 update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
2363 update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
2364 update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}</code></pre>
2365 </div></div>
2366 <div class="paragraph"><p>This will simultaneously rebase <code>branch1</code>, <code>branch2</code>, and <code>branch3</code>,
2367 all commits they have since <code>base</code>, playing them on top of
2368 <code>origin/main</code>. These three branches may have commits on top of <code>base</code>
2369 that they have in common, but that does not need to be the case.</p></div>
2370 </div>
2371 </div>
2372 <div class="sect1">
2373 <h2 id="_git">GIT</h2>
2374 <div class="sectionbody">
2375 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
2376 </div>
2377 </div>
2378 </div>
2379 <div id="footnotes"><hr /></div>
2380 <div id="footer">
2381 <div id="footer-text">
2382 Last updated
2383  2024-04-23 14:40:04 PDT
2384 </div>
2385 </div>
2386 </body>
2387 </html>