git-format-patch.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-format-patch(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-format-patch(1) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>git-format-patch -
 743    Prepare patches for e-mail submission
 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 format-patch</em> [-k] [(-o|--output-directory) &lt;dir&gt; | --stdout]
 753                    [--no-thread | --thread[=&lt;style&gt;]]
 754                    [(--attach|--inline)[=&lt;boundary&gt;] | --no-attach]
 755                    [-s | --signoff]
 756                    [--signature=&lt;signature&gt; | --no-signature]
 757                    [--signature-file=&lt;file&gt;]
 758                    [-n | --numbered | -N | --no-numbered]
 759                    [--start-number &lt;n&gt;] [--numbered-files]
 760                    [--in-reply-to=&lt;message id&gt;] [--suffix=.&lt;sfx&gt;]
 761                    [--ignore-if-in-upstream] [--always]
 762                    [--cover-from-description=&lt;mode&gt;]
 763                    [--rfc] [--subject-prefix=&lt;subject prefix&gt;]
 764                    [(--reroll-count|-v) &lt;n&gt;]
 765                    [--to=&lt;email&gt;] [--cc=&lt;email&gt;]
 766                    [--[no-]cover-letter] [--quiet]
 767                    [--[no-]encode-email-headers]
 768                    [--no-notes | --notes[=&lt;ref&gt;]]
 769                    [--interdiff=&lt;previous&gt;]
 770                    [--range-diff=&lt;previous&gt; [--creation-factor=&lt;percent&gt;]]
 771                    [--filename-max-length=&lt;n&gt;]
 772                    [--progress]
 773                    [&lt;common diff options&gt;]
 774                    [ &lt;since&gt; | &lt;revision range&gt; ]</pre>
 775 <div class="attribution">
 776 </div></div>
 777 </div>
 778 </div>
 779 <div class="sect1">
 780 <h2 id="_description">DESCRIPTION</h2>
 781 <div class="sectionbody">
 782 <div class="paragraph"><p>Prepare each non-merge commit with its "patch" in
 783 one "message" per commit, formatted to resemble a UNIX mailbox.
 784 The output of this command is convenient for e-mail submission or
 785 for use with <em>git am</em>.</p></div>
 786 <div class="paragraph"><p>A "message" generated by the command consists of three parts:</p></div>
 787 <div class="ulist"><ul>
 788 <li>
 789 <p>
 790 A brief metadata header that begins with <code>From &lt;commit&gt;</code>
 791   with a fixed <code>Mon Sep 17 00:00:00 2001</code> datestamp to help programs
 792   like "file(1)" to recognize that the file is an output from this
 793   command, fields that record the author identity, the author date,
 794   and the title of the change (taken from the first paragraph of the
 795   commit log message).
 796 </p>
 797 </li>
 798 <li>
 799 <p>
 800 The second and subsequent paragraphs of the commit log message.
 801 </p>
 802 </li>
 803 <li>
 804 <p>
 805 The "patch", which is the "diff -p --stat" output (see
 806   <a href="git-diff.html">git-diff(1)</a>) between the commit and its parent.
 807 </p>
 808 </li>
 809 </ul></div>
 810 <div class="paragraph"><p>The log message and the patch is separated by a line with a
 811 three-dash line.</p></div>
 812 <div class="paragraph"><p>There are two ways to specify which commits to operate on.</p></div>
 813 <div class="olist arabic"><ol class="arabic">
 814 <li>
 815 <p>
 816 A single commit, &lt;since&gt;, specifies that the commits leading
 817    to the tip of the current branch that are not in the history
 818    that leads to the &lt;since&gt; to be output.
 819 </p>
 820 </li>
 821 <li>
 822 <p>
 823 Generic &lt;revision range&gt; expression (see "SPECIFYING
 824    REVISIONS" section in <a href="gitrevisions.html">gitrevisions(7)</a>) means the
 825    commits in the specified range.
 826 </p>
 827 </li>
 828 </ol></div>
 829 <div class="paragraph"><p>The first rule takes precedence in the case of a single &lt;commit&gt;.  To
 830 apply the second rule, i.e., format everything since the beginning of
 831 history up until &lt;commit&gt;, use the <code>--root</code> option: <code>git format-patch
 832 --root &lt;commit&gt;</code>.  If you want to format only &lt;commit&gt; itself, you
 833 can do this with <code>git format-patch -1 &lt;commit&gt;</code>.</p></div>
 834 <div class="paragraph"><p>By default, each output file is numbered sequentially from 1, and uses the
 835 first line of the commit message (massaged for pathname safety) as
 836 the filename. With the <code>--numbered-files</code> option, the output file names
 837 will only be numbers, without the first line of the commit appended.
 838 The names of the output files are printed to standard
 839 output, unless the <code>--stdout</code> option is specified.</p></div>
 840 <div class="paragraph"><p>If <code>-o</code> is specified, output files are created in &lt;dir&gt;.  Otherwise
 841 they are created in the current working directory. The default path
 842 can be set with the <code>format.outputDirectory</code> configuration option.
 843 The <code>-o</code> option takes precedence over <code>format.outputDirectory</code>.
 844 To store patches in the current working directory even when
 845 <code>format.outputDirectory</code> points elsewhere, use <code>-o .</code>. All directory
 846 components will be created.</p></div>
 847 <div class="paragraph"><p>By default, the subject of a single patch is "[PATCH] " followed by
 848 the concatenation of lines from the commit message up to the first blank
 849 line (see the DISCUSSION section of <a href="git-commit.html">git-commit(1)</a>).</p></div>
 850 <div class="paragraph"><p>When multiple patches are output, the subject prefix will instead be
 851 "[PATCH n/m] ".  To force 1/1 to be added for a single patch, use <code>-n</code>.
 852 To omit patch numbers from the subject, use <code>-N</code>.</p></div>
 853 <div class="paragraph"><p>If given <code>--thread</code>, <code>git-format-patch</code> will generate <code>In-Reply-To</code> and
 854 <code>References</code> headers to make the second and subsequent patch mails appear
 855 as replies to the first mail; this also generates a <code>Message-ID</code> header to
 856 reference.</p></div>
 857 </div>
 858 </div>
 859 <div class="sect1">
 860 <h2 id="_options">OPTIONS</h2>
 861 <div class="sectionbody">
 862 <div class="dlist"><dl>
 863 <dt class="hdlist1">
 864 -p
 865 </dt>
 866 <dt class="hdlist1">
 867 --no-stat
 868 </dt>
 869 <dd>
 870 <p>
 871         Generate plain patches without any diffstats.
 872 </p>
 873 </dd>
 874 <dt class="hdlist1">
 875 -U&lt;n&gt;
 876 </dt>
 877 <dt class="hdlist1">
 878 --unified=&lt;n&gt;
 879 </dt>
 880 <dd>
 881 <p>
 882         Generate diffs with &lt;n&gt; lines of context instead of
 883         the usual three.
 884 </p>
 885 </dd>
 886 <dt class="hdlist1">
 887 --output=&lt;file&gt;
 888 </dt>
 889 <dd>
 890 <p>
 891         Output to a specific file instead of stdout.
 892 </p>
 893 </dd>
 894 <dt class="hdlist1">
 895 --output-indicator-new=&lt;char&gt;
 896 </dt>
 897 <dt class="hdlist1">
 898 --output-indicator-old=&lt;char&gt;
 899 </dt>
 900 <dt class="hdlist1">
 901 --output-indicator-context=&lt;char&gt;
 902 </dt>
 903 <dd>
 904 <p>
 905         Specify the character used to indicate new, old or context
 906         lines in the generated patch. Normally they are <em>+</em>, <em>-</em> and
 907         ' ' respectively.
 908 </p>
 909 </dd>
 910 <dt class="hdlist1">
 911 --indent-heuristic
 912 </dt>
 913 <dd>
 914 <p>
 915         Enable the heuristic that shifts diff hunk boundaries to make patches
 916         easier to read. This is the default.
 917 </p>
 918 </dd>
 919 <dt class="hdlist1">
 920 --no-indent-heuristic
 921 </dt>
 922 <dd>
 923 <p>
 924         Disable the indent heuristic.
 925 </p>
 926 </dd>
 927 <dt class="hdlist1">
 928 --minimal
 929 </dt>
 930 <dd>
 931 <p>
 932         Spend extra time to make sure the smallest possible
 933         diff is produced.
 934 </p>
 935 </dd>
 936 <dt class="hdlist1">
 937 --patience
 938 </dt>
 939 <dd>
 940 <p>
 941         Generate a diff using the "patience diff" algorithm.
 942 </p>
 943 </dd>
 944 <dt class="hdlist1">
 945 --histogram
 946 </dt>
 947 <dd>
 948 <p>
 949         Generate a diff using the "histogram diff" algorithm.
 950 </p>
 951 </dd>
 952 <dt class="hdlist1">
 953 --anchored=&lt;text&gt;
 954 </dt>
 955 <dd>
 956 <p>
 957         Generate a diff using the "anchored diff" algorithm.
 958 </p>
 959 <div class="paragraph"><p>This option may be specified more than once.</p></div>
 960 <div class="paragraph"><p>If a line exists in both the source and destination, exists only once,
 961 and starts with this text, this algorithm attempts to prevent it from
 962 appearing as a deletion or addition in the output. It uses the "patience
 963 diff" algorithm internally.</p></div>
 964 </dd>
 965 <dt class="hdlist1">
 966 --diff-algorithm={patience|minimal|histogram|myers}
 967 </dt>
 968 <dd>
 969 <p>
 970         Choose a diff algorithm. The variants are as follows:
 971 </p>
 972 <div class="openblock">
 973 <div class="content">
 974 <div class="dlist"><dl>
 975 <dt class="hdlist1">
 976 <code>default</code>, <code>myers</code>
 977 </dt>
 978 <dd>
 979 <p>
 980         The basic greedy diff algorithm. Currently, this is the default.
 981 </p>
 982 </dd>
 983 <dt class="hdlist1">
 984 <code>minimal</code>
 985 </dt>
 986 <dd>
 987 <p>
 988         Spend extra time to make sure the smallest possible diff is
 989         produced.
 990 </p>
 991 </dd>
 992 <dt class="hdlist1">
 993 <code>patience</code>
 994 </dt>
 995 <dd>
 996 <p>
 997         Use "patience diff" algorithm when generating patches.
 998 </p>
 999 </dd>
1000 <dt class="hdlist1">
1001 <code>histogram</code>
1002 </dt>
1003 <dd>
1004 <p>
1005         This algorithm extends the patience algorithm to "support
1006         low-occurrence common elements".
1007 </p>
1008 </dd>
1009 </dl></div>
1010 </div></div>
1011 <div class="paragraph"><p>For instance, if you configured the <code>diff.algorithm</code> variable to a
1012 non-default value and want to use the default one, then you
1013 have to use <code>--diff-algorithm=default</code> option.</p></div>
1014 </dd>
1015 <dt class="hdlist1">
1016 --stat[=&lt;width&gt;[,&lt;name-width&gt;[,&lt;count&gt;]]]
1017 </dt>
1018 <dd>
1019 <p>
1020         Generate a diffstat. By default, as much space as necessary
1021         will be used for the filename part, and the rest for the graph
1022         part. Maximum width defaults to terminal width, or 80 columns
1023         if not connected to a terminal, and can be overridden by
1024         <code>&lt;width&gt;</code>. The width of the filename part can be limited by
1025         giving another width <code>&lt;name-width&gt;</code> after a comma. The width
1026         of the graph part can be limited by using
1027         <code>--stat-graph-width=&lt;width&gt;</code> (affects all commands generating
1028         a stat graph) or by setting <code>diff.statGraphWidth=&lt;width&gt;</code>
1029         (does not affect <code>git format-patch</code>).
1030         By giving a third parameter <code>&lt;count&gt;</code>, you can limit the
1031         output to the first <code>&lt;count&gt;</code> lines, followed by <code>...</code> if
1032         there are more.
1033 </p>
1034 <div class="paragraph"><p>These parameters can also be set individually with <code>--stat-width=&lt;width&gt;</code>,
1035 <code>--stat-name-width=&lt;name-width&gt;</code> and <code>--stat-count=&lt;count&gt;</code>.</p></div>
1036 </dd>
1037 <dt class="hdlist1">
1038 --compact-summary
1039 </dt>
1040 <dd>
1041 <p>
1042         Output a condensed summary of extended header information such
1043         as file creations or deletions ("new" or "gone", optionally "+l"
1044         if it&#8217;s a symlink) and mode changes ("+x" or "-x" for adding
1045         or removing executable bit respectively) in diffstat. The
1046         information is put between the filename part and the graph
1047         part. Implies <code>--stat</code>.
1048 </p>
1049 </dd>
1050 <dt class="hdlist1">
1051 --numstat
1052 </dt>
1053 <dd>
1054 <p>
1055         Similar to <code>--stat</code>, but shows number of added and
1056         deleted lines in decimal notation and pathname without
1057         abbreviation, to make it more machine friendly.  For
1058         binary files, outputs two <code>-</code> instead of saying
1059         <code>0 0</code>.
1060 </p>
1061 </dd>
1062 <dt class="hdlist1">
1063 --shortstat
1064 </dt>
1065 <dd>
1066 <p>
1067         Output only the last line of the <code>--stat</code> format containing total
1068         number of modified files, as well as number of added and deleted
1069         lines.
1070 </p>
1071 </dd>
1072 <dt class="hdlist1">
1073 -X[&lt;param1,param2,&#8230;&gt;]
1074 </dt>
1075 <dt class="hdlist1">
1076 --dirstat[=&lt;param1,param2,&#8230;&gt;]
1077 </dt>
1078 <dd>
1079 <p>
1080         Output the distribution of relative amount of changes for each
1081         sub-directory. The behavior of <code>--dirstat</code> can be customized by
1082         passing it a comma separated list of parameters.
1083         The defaults are controlled by the <code>diff.dirstat</code> configuration
1084         variable (see <a href="git-config.html">git-config(1)</a>).
1085         The following parameters are available:
1086 </p>
1087 <div class="openblock">
1088 <div class="content">
1089 <div class="dlist"><dl>
1090 <dt class="hdlist1">
1091 <code>changes</code>
1092 </dt>
1093 <dd>
1094 <p>
1095         Compute the dirstat numbers by counting the lines that have been
1096         removed from the source, or added to the destination. This ignores
1097         the amount of pure code movements within a file.  In other words,
1098         rearranging lines in a file is not counted as much as other changes.
1099         This is the default behavior when no parameter is given.
1100 </p>
1101 </dd>
1102 <dt class="hdlist1">
1103 <code>lines</code>
1104 </dt>
1105 <dd>
1106 <p>
1107         Compute the dirstat numbers by doing the regular line-based diff
1108         analysis, and summing the removed/added line counts. (For binary
1109         files, count 64-byte chunks instead, since binary files have no
1110         natural concept of lines). This is a more expensive <code>--dirstat</code>
1111         behavior than the <code>changes</code> behavior, but it does count rearranged
1112         lines within a file as much as other changes. The resulting output
1113         is consistent with what you get from the other <code>--*stat</code> options.
1114 </p>
1115 </dd>
1116 <dt class="hdlist1">
1117 <code>files</code>
1118 </dt>
1119 <dd>
1120 <p>
1121         Compute the dirstat numbers by counting the number of files changed.
1122         Each changed file counts equally in the dirstat analysis. This is
1123         the computationally cheapest <code>--dirstat</code> behavior, since it does
1124         not have to look at the file contents at all.
1125 </p>
1126 </dd>
1127 <dt class="hdlist1">
1128 <code>cumulative</code>
1129 </dt>
1130 <dd>
1131 <p>
1132         Count changes in a child directory for the parent directory as well.
1133         Note that when using <code>cumulative</code>, the sum of the percentages
1134         reported may exceed 100%. The default (non-cumulative) behavior can
1135         be specified with the <code>noncumulative</code> parameter.
1136 </p>
1137 </dd>
1138 <dt class="hdlist1">
1139 &lt;limit&gt;
1140 </dt>
1141 <dd>
1142 <p>
1143         An integer parameter specifies a cut-off percent (3% by default).
1144         Directories contributing less than this percentage of the changes
1145         are not shown in the output.
1146 </p>
1147 </dd>
1148 </dl></div>
1149 </div></div>
1150 <div class="paragraph"><p>Example: The following will count changed files, while ignoring
1151 directories with less than 10% of the total amount of changed files,
1152 and accumulating child directory counts in the parent directories:
1153 <code>--dirstat=files,10,cumulative</code>.</p></div>
1154 </dd>
1155 <dt class="hdlist1">
1156 --cumulative
1157 </dt>
1158 <dd>
1159 <p>
1160         Synonym for --dirstat=cumulative
1161 </p>
1162 </dd>
1163 <dt class="hdlist1">
1164 --dirstat-by-file[=&lt;param1,param2&gt;&#8230;]
1165 </dt>
1166 <dd>
1167 <p>
1168         Synonym for --dirstat=files,param1,param2&#8230;
1169 </p>
1170 </dd>
1171 <dt class="hdlist1">
1172 --summary
1173 </dt>
1174 <dd>
1175 <p>
1176         Output a condensed summary of extended header information
1177         such as creations, renames and mode changes.
1178 </p>
1179 </dd>
1180 <dt class="hdlist1">
1181 --no-renames
1182 </dt>
1183 <dd>
1184 <p>
1185         Turn off rename detection, even when the configuration
1186         file gives the default to do so.
1187 </p>
1188 </dd>
1189 <dt class="hdlist1">
1190 --[no-]rename-empty
1191 </dt>
1192 <dd>
1193 <p>
1194         Whether to use empty blobs as rename source.
1195 </p>
1196 </dd>
1197 <dt class="hdlist1">
1198 --full-index
1199 </dt>
1200 <dd>
1201 <p>
1202         Instead of the first handful of characters, show the full
1203         pre- and post-image blob object names on the "index"
1204         line when generating patch format output.
1205 </p>
1206 </dd>
1207 <dt class="hdlist1">
1208 --binary
1209 </dt>
1210 <dd>
1211 <p>
1212         In addition to <code>--full-index</code>, output a binary diff that
1213         can be applied with <code>git-apply</code>.
1214 </p>
1215 </dd>
1216 <dt class="hdlist1">
1217 --abbrev[=&lt;n&gt;]
1218 </dt>
1219 <dd>
1220 <p>
1221         Instead of showing the full 40-byte hexadecimal object
1222         name in diff-raw format output and diff-tree header
1223         lines, show the shortest prefix that is at least <em>&lt;n&gt;</em>
1224         hexdigits long that uniquely refers the object.
1225         In diff-patch output format, <code>--full-index</code> takes higher
1226         precedence, i.e. if <code>--full-index</code> is specified, full blob
1227         names will be shown regardless of <code>--abbrev</code>.
1228         Non default number of digits can be specified with <code>--abbrev=&lt;n&gt;</code>.
1229 </p>
1230 </dd>
1231 <dt class="hdlist1">
1232 -B[&lt;n&gt;][/&lt;m&gt;]
1233 </dt>
1234 <dt class="hdlist1">
1235 --break-rewrites[=[&lt;n&gt;][/&lt;m&gt;]]
1236 </dt>
1237 <dd>
1238 <p>
1239         Break complete rewrite changes into pairs of delete and
1240         create. This serves two purposes:
1241 </p>
1242 <div class="paragraph"><p>It affects the way a change that amounts to a total rewrite of a file
1243 not as a series of deletion and insertion mixed together with a very
1244 few lines that happen to match textually as the context, but as a
1245 single deletion of everything old followed by a single insertion of
1246 everything new, and the number <code>m</code> controls this aspect of the -B
1247 option (defaults to 60%). <code>-B/70%</code> specifies that less than 30% of the
1248 original should remain in the result for Git to consider it a total
1249 rewrite (i.e. otherwise the resulting patch will be a series of
1250 deletion and insertion mixed together with context lines).</p></div>
1251 <div class="paragraph"><p>When used with -M, a totally-rewritten file is also considered as the
1252 source of a rename (usually -M only considers a file that disappeared
1253 as the source of a rename), and the number <code>n</code> controls this aspect of
1254 the -B option (defaults to 50%). <code>-B20%</code> specifies that a change with
1255 addition and deletion compared to 20% or more of the file&#8217;s size are
1256 eligible for being picked up as a possible source of a rename to
1257 another file.</p></div>
1258 </dd>
1259 <dt class="hdlist1">
1260 -M[&lt;n&gt;]
1261 </dt>
1262 <dt class="hdlist1">
1263 --find-renames[=&lt;n&gt;]
1264 </dt>
1265 <dd>
1266 <p>
1267         Detect renames.
1268         If <code>n</code> is specified, it is a threshold on the similarity
1269         index (i.e. amount of addition/deletions compared to the
1270         file&#8217;s size). For example, <code>-M90%</code> means Git should consider a
1271         delete/add pair to be a rename if more than 90% of the file
1272         hasn&#8217;t changed.  Without a <code>%</code> sign, the number is to be read as
1273         a fraction, with a decimal point before it.  I.e., <code>-M5</code> becomes
1274         0.5, and is thus the same as <code>-M50%</code>.  Similarly, <code>-M05</code> is
1275         the same as <code>-M5%</code>.  To limit detection to exact renames, use
1276         <code>-M100%</code>.  The default similarity index is 50%.
1277 </p>
1278 </dd>
1279 <dt class="hdlist1">
1280 -C[&lt;n&gt;]
1281 </dt>
1282 <dt class="hdlist1">
1283 --find-copies[=&lt;n&gt;]
1284 </dt>
1285 <dd>
1286 <p>
1287         Detect copies as well as renames.  See also <code>--find-copies-harder</code>.
1288         If <code>n</code> is specified, it has the same meaning as for <code>-M&lt;n&gt;</code>.
1289 </p>
1290 </dd>
1291 <dt class="hdlist1">
1292 --find-copies-harder
1293 </dt>
1294 <dd>
1295 <p>
1296         For performance reasons, by default, <code>-C</code> option finds copies only
1297         if the original file of the copy was modified in the same
1298         changeset.  This flag makes the command
1299         inspect unmodified files as candidates for the source of
1300         copy.  This is a very expensive operation for large
1301         projects, so use it with caution.  Giving more than one
1302         <code>-C</code> option has the same effect.
1303 </p>
1304 </dd>
1305 <dt class="hdlist1">
1306 -D
1307 </dt>
1308 <dt class="hdlist1">
1309 --irreversible-delete
1310 </dt>
1311 <dd>
1312 <p>
1313         Omit the preimage for deletes, i.e. print only the header but not
1314         the diff between the preimage and <code>/dev/null</code>. The resulting patch
1315         is not meant to be applied with <code>patch</code> or <code>git apply</code>; this is
1316         solely for people who want to just concentrate on reviewing the
1317         text after the change. In addition, the output obviously lacks
1318         enough information to apply such a patch in reverse, even manually,
1319         hence the name of the option.
1320 </p>
1321 <div class="paragraph"><p>When used together with <code>-B</code>, omit also the preimage in the deletion part
1322 of a delete/create pair.</p></div>
1323 </dd>
1324 <dt class="hdlist1">
1325 -l&lt;num&gt;
1326 </dt>
1327 <dd>
1328 <p>
1329         The <code>-M</code> and <code>-C</code> options involve some preliminary steps that
1330         can detect subsets of renames/copies cheaply, followed by an
1331         exhaustive fallback portion that compares all remaining
1332         unpaired destinations to all relevant sources.  (For renames,
1333         only remaining unpaired sources are relevant; for copies, all
1334         original sources are relevant.)  For N sources and
1335         destinations, this exhaustive check is O(N^2).  This option
1336         prevents the exhaustive portion of rename/copy detection from
1337         running if the number of source/destination files involved
1338         exceeds the specified number.  Defaults to diff.renameLimit.
1339         Note that a value of 0 is treated as unlimited.
1340 </p>
1341 </dd>
1342 <dt class="hdlist1">
1343 -O&lt;orderfile&gt;
1344 </dt>
1345 <dd>
1346 <p>
1347         Control the order in which files appear in the output.
1348         This overrides the <code>diff.orderFile</code> configuration variable
1349         (see <a href="git-config.html">git-config(1)</a>).  To cancel <code>diff.orderFile</code>,
1350         use <code>-O/dev/null</code>.
1351 </p>
1352 <div class="paragraph"><p>The output order is determined by the order of glob patterns in
1353 &lt;orderfile&gt;.
1354 All files with pathnames that match the first pattern are output
1355 first, all files with pathnames that match the second pattern (but not
1356 the first) are output next, and so on.
1357 All files with pathnames that do not match any pattern are output
1358 last, as if there was an implicit match-all pattern at the end of the
1359 file.
1360 If multiple pathnames have the same rank (they match the same pattern
1361 but no earlier patterns), their output order relative to each other is
1362 the normal order.</p></div>
1363 <div class="paragraph"><p>&lt;orderfile&gt; is parsed as follows:</p></div>
1364 <div class="openblock">
1365 <div class="content">
1366 <div class="ulist"><ul>
1367 <li>
1368 <p>
1369 Blank lines are ignored, so they can be used as separators for
1370    readability.
1371 </p>
1372 </li>
1373 <li>
1374 <p>
1375 Lines starting with a hash ("<code>#</code>") are ignored, so they can be used
1376    for comments.  Add a backslash ("<code>\</code>") to the beginning of the
1377    pattern if it starts with a hash.
1378 </p>
1379 </li>
1380 <li>
1381 <p>
1382 Each other line contains a single pattern.
1383 </p>
1384 </li>
1385 </ul></div>
1386 </div></div>
1387 <div class="paragraph"><p>Patterns have the same syntax and semantics as patterns used for
1388 fnmatch(3) without the FNM_PATHNAME flag, except a pathname also
1389 matches a pattern if removing any number of the final pathname
1390 components matches the pattern.  For example, the pattern "<code>foo*bar</code>"
1391 matches "<code>fooasdfbar</code>" and "<code>foo/bar/baz/asdf</code>" but not "<code>foobarx</code>".</p></div>
1392 </dd>
1393 <dt class="hdlist1">
1394 --skip-to=&lt;file&gt;
1395 </dt>
1396 <dt class="hdlist1">
1397 --rotate-to=&lt;file&gt;
1398 </dt>
1399 <dd>
1400 <p>
1401         Discard the files before the named &lt;file&gt; from the output
1402         (i.e. <em>skip to</em>), or move them to the end of the output
1403         (i.e. <em>rotate to</em>).  These were invented primarily for use
1404         of the <code>git difftool</code> command, and may not be very useful
1405         otherwise.
1406 </p>
1407 </dd>
1408 <dt class="hdlist1">
1409 --relative[=&lt;path&gt;]
1410 </dt>
1411 <dt class="hdlist1">
1412 --no-relative
1413 </dt>
1414 <dd>
1415 <p>
1416         When run from a subdirectory of the project, it can be
1417         told to exclude changes outside the directory and show
1418         pathnames relative to it with this option.  When you are
1419         not in a subdirectory (e.g. in a bare repository), you
1420         can name which subdirectory to make the output relative
1421         to by giving a &lt;path&gt; as an argument.
1422         <code>--no-relative</code> can be used to countermand both <code>diff.relative</code> config
1423         option and previous <code>--relative</code>.
1424 </p>
1425 </dd>
1426 <dt class="hdlist1">
1427 -a
1428 </dt>
1429 <dt class="hdlist1">
1430 --text
1431 </dt>
1432 <dd>
1433 <p>
1434         Treat all files as text.
1435 </p>
1436 </dd>
1437 <dt class="hdlist1">
1438 --ignore-cr-at-eol
1439 </dt>
1440 <dd>
1441 <p>
1442         Ignore carriage-return at the end of line when doing a comparison.
1443 </p>
1444 </dd>
1445 <dt class="hdlist1">
1446 --ignore-space-at-eol
1447 </dt>
1448 <dd>
1449 <p>
1450         Ignore changes in whitespace at EOL.
1451 </p>
1452 </dd>
1453 <dt class="hdlist1">
1454 -b
1455 </dt>
1456 <dt class="hdlist1">
1457 --ignore-space-change
1458 </dt>
1459 <dd>
1460 <p>
1461         Ignore changes in amount of whitespace.  This ignores whitespace
1462         at line end, and considers all other sequences of one or
1463         more whitespace characters to be equivalent.
1464 </p>
1465 </dd>
1466 <dt class="hdlist1">
1467 -w
1468 </dt>
1469 <dt class="hdlist1">
1470 --ignore-all-space
1471 </dt>
1472 <dd>
1473 <p>
1474         Ignore whitespace when comparing lines.  This ignores
1475         differences even if one line has whitespace where the other
1476         line has none.
1477 </p>
1478 </dd>
1479 <dt class="hdlist1">
1480 --ignore-blank-lines
1481 </dt>
1482 <dd>
1483 <p>
1484         Ignore changes whose lines are all blank.
1485 </p>
1486 </dd>
1487 <dt class="hdlist1">
1488 -I&lt;regex&gt;
1489 </dt>
1490 <dt class="hdlist1">
1491 --ignore-matching-lines=&lt;regex&gt;
1492 </dt>
1493 <dd>
1494 <p>
1495         Ignore changes whose all lines match &lt;regex&gt;.  This option may
1496         be specified more than once.
1497 </p>
1498 </dd>
1499 <dt class="hdlist1">
1500 --inter-hunk-context=&lt;lines&gt;
1501 </dt>
1502 <dd>
1503 <p>
1504         Show the context between diff hunks, up to the specified number
1505         of lines, thereby fusing hunks that are close to each other.
1506         Defaults to <code>diff.interHunkContext</code> or 0 if the config option
1507         is unset.
1508 </p>
1509 </dd>
1510 <dt class="hdlist1">
1511 -W
1512 </dt>
1513 <dt class="hdlist1">
1514 --function-context
1515 </dt>
1516 <dd>
1517 <p>
1518         Show whole function as context lines for each change.
1519         The function names are determined in the same way as
1520         <code>git diff</code> works out patch hunk headers (see <em>Defining a
1521         custom hunk-header</em> in <a href="gitattributes.html">gitattributes(5)</a>).
1522 </p>
1523 </dd>
1524 <dt class="hdlist1">
1525 --ext-diff
1526 </dt>
1527 <dd>
1528 <p>
1529         Allow an external diff helper to be executed. If you set an
1530         external diff driver with <a href="gitattributes.html">gitattributes(5)</a>, you need
1531         to use this option with <a href="git-log.html">git-log(1)</a> and friends.
1532 </p>
1533 </dd>
1534 <dt class="hdlist1">
1535 --no-ext-diff
1536 </dt>
1537 <dd>
1538 <p>
1539         Disallow external diff drivers.
1540 </p>
1541 </dd>
1542 <dt class="hdlist1">
1543 --textconv
1544 </dt>
1545 <dt class="hdlist1">
1546 --no-textconv
1547 </dt>
1548 <dd>
1549 <p>
1550         Allow (or disallow) external text conversion filters to be run
1551         when comparing binary files. See <a href="gitattributes.html">gitattributes(5)</a> for
1552         details. Because textconv filters are typically a one-way
1553         conversion, the resulting diff is suitable for human
1554         consumption, but cannot be applied. For this reason, textconv
1555         filters are enabled by default only for <a href="git-diff.html">git-diff(1)</a> and
1556         <a href="git-log.html">git-log(1)</a>, but not for <a href="git-format-patch.html">git-format-patch(1)</a> or
1557         diff plumbing commands.
1558 </p>
1559 </dd>
1560 <dt class="hdlist1">
1561 --ignore-submodules[=&lt;when&gt;]
1562 </dt>
1563 <dd>
1564 <p>
1565         Ignore changes to submodules in the diff generation. &lt;when&gt; can be
1566         either "none", "untracked", "dirty" or "all", which is the default.
1567         Using "none" will consider the submodule modified when it either contains
1568         untracked or modified files or its HEAD differs from the commit recorded
1569         in the superproject and can be used to override any settings of the
1570         <em>ignore</em> option in <a href="git-config.html">git-config(1)</a> or <a href="gitmodules.html">gitmodules(5)</a>. When
1571         "untracked" is used submodules are not considered dirty when they only
1572         contain untracked content (but they are still scanned for modified
1573         content). Using "dirty" ignores all changes to the work tree of submodules,
1574         only changes to the commits stored in the superproject are shown (this was
1575         the behavior until 1.7.0). Using "all" hides all changes to submodules.
1576 </p>
1577 </dd>
1578 <dt class="hdlist1">
1579 --src-prefix=&lt;prefix&gt;
1580 </dt>
1581 <dd>
1582 <p>
1583         Show the given source prefix instead of "a/".
1584 </p>
1585 </dd>
1586 <dt class="hdlist1">
1587 --dst-prefix=&lt;prefix&gt;
1588 </dt>
1589 <dd>
1590 <p>
1591         Show the given destination prefix instead of "b/".
1592 </p>
1593 </dd>
1594 <dt class="hdlist1">
1595 --no-prefix
1596 </dt>
1597 <dd>
1598 <p>
1599         Do not show any source or destination prefix.
1600 </p>
1601 </dd>
1602 <dt class="hdlist1">
1603 --default-prefix
1604 </dt>
1605 <dd>
1606 <p>
1607         Use the default source and destination prefixes ("a/" and "b/").
1608         This is usually the default already, but may be used to override
1609         config such as <code>diff.noprefix</code>.
1610 </p>
1611 </dd>
1612 <dt class="hdlist1">
1613 --line-prefix=&lt;prefix&gt;
1614 </dt>
1615 <dd>
1616 <p>
1617         Prepend an additional prefix to every line of output.
1618 </p>
1619 </dd>
1620 <dt class="hdlist1">
1621 --ita-invisible-in-index
1622 </dt>
1623 <dd>
1624 <p>
1625         By default entries added by "git add -N" appear as an existing
1626         empty file in "git diff" and a new file in "git diff --cached".
1627         This option makes the entry appear as a new file in "git diff"
1628         and non-existent in "git diff --cached". This option could be
1629         reverted with <code>--ita-visible-in-index</code>. Both options are
1630         experimental and could be removed in future.
1631 </p>
1632 </dd>
1633 </dl></div>
1634 <div class="paragraph"><p>For more detailed explanation on these common options, see also
1635 <a href="gitdiffcore.html">gitdiffcore(7)</a>.</p></div>
1636 <div class="dlist"><dl>
1637 <dt class="hdlist1">
1638 -&lt;n&gt;
1639 </dt>
1640 <dd>
1641 <p>
1642         Prepare patches from the topmost &lt;n&gt; commits.
1643 </p>
1644 </dd>
1645 <dt class="hdlist1">
1646 -o &lt;dir&gt;
1647 </dt>
1648 <dt class="hdlist1">
1649 --output-directory &lt;dir&gt;
1650 </dt>
1651 <dd>
1652 <p>
1653         Use &lt;dir&gt; to store the resulting files, instead of the
1654         current working directory.
1655 </p>
1656 </dd>
1657 <dt class="hdlist1">
1658 -n
1659 </dt>
1660 <dt class="hdlist1">
1661 --numbered
1662 </dt>
1663 <dd>
1664 <p>
1665         Name output in <em>[PATCH n/m]</em> format, even with a single patch.
1666 </p>
1667 </dd>
1668 <dt class="hdlist1">
1669 -N
1670 </dt>
1671 <dt class="hdlist1">
1672 --no-numbered
1673 </dt>
1674 <dd>
1675 <p>
1676         Name output in <em>[PATCH]</em> format.
1677 </p>
1678 </dd>
1679 <dt class="hdlist1">
1680 --start-number &lt;n&gt;
1681 </dt>
1682 <dd>
1683 <p>
1684         Start numbering the patches at &lt;n&gt; instead of 1.
1685 </p>
1686 </dd>
1687 <dt class="hdlist1">
1688 --numbered-files
1689 </dt>
1690 <dd>
1691 <p>
1692         Output file names will be a simple number sequence
1693         without the default first line of the commit appended.
1694 </p>
1695 </dd>
1696 <dt class="hdlist1">
1697 -k
1698 </dt>
1699 <dt class="hdlist1">
1700 --keep-subject
1701 </dt>
1702 <dd>
1703 <p>
1704         Do not strip/add <em>[PATCH]</em> from the first line of the
1705         commit log message.
1706 </p>
1707 </dd>
1708 <dt class="hdlist1">
1709 -s
1710 </dt>
1711 <dt class="hdlist1">
1712 --signoff
1713 </dt>
1714 <dd>
1715 <p>
1716         Add a <code>Signed-off-by</code> trailer to the commit message, using
1717         the committer identity of yourself.
1718         See the signoff option in <a href="git-commit.html">git-commit(1)</a> for more information.
1719 </p>
1720 </dd>
1721 <dt class="hdlist1">
1722 --stdout
1723 </dt>
1724 <dd>
1725 <p>
1726         Print all commits to the standard output in mbox format,
1727         instead of creating a file for each one.
1728 </p>
1729 </dd>
1730 <dt class="hdlist1">
1731 --attach[=&lt;boundary&gt;]
1732 </dt>
1733 <dd>
1734 <p>
1735         Create multipart/mixed attachment, the first part of
1736         which is the commit message and the patch itself in the
1737         second part, with <code>Content-Disposition: attachment</code>.
1738 </p>
1739 </dd>
1740 <dt class="hdlist1">
1741 --no-attach
1742 </dt>
1743 <dd>
1744 <p>
1745         Disable the creation of an attachment, overriding the
1746         configuration setting.
1747 </p>
1748 </dd>
1749 <dt class="hdlist1">
1750 --inline[=&lt;boundary&gt;]
1751 </dt>
1752 <dd>
1753 <p>
1754         Create multipart/mixed attachment, the first part of
1755         which is the commit message and the patch itself in the
1756         second part, with <code>Content-Disposition: inline</code>.
1757 </p>
1758 </dd>
1759 <dt class="hdlist1">
1760 --thread[=&lt;style&gt;]
1761 </dt>
1762 <dt class="hdlist1">
1763 --no-thread
1764 </dt>
1765 <dd>
1766 <p>
1767         Controls addition of <code>In-Reply-To</code> and <code>References</code> headers to
1768         make the second and subsequent mails appear as replies to the
1769         first.  Also controls generation of the <code>Message-ID</code> header to
1770         reference.
1771 </p>
1772 <div class="paragraph"><p>The optional &lt;style&gt; argument can be either <code>shallow</code> or <code>deep</code>.
1773 <em>shallow</em> threading makes every mail a reply to the head of the
1774 series, where the head is chosen from the cover letter, the
1775 <code>--in-reply-to</code>, and the first patch mail, in this order.  <em>deep</em>
1776 threading makes every mail a reply to the previous one.</p></div>
1777 <div class="paragraph"><p>The default is <code>--no-thread</code>, unless the <code>format.thread</code> configuration
1778 is set.  <code>--thread</code> without an argument is equivalent to <code>--thread=shallow</code>.</p></div>
1779 <div class="paragraph"><p>Beware that the default for <em>git send-email</em> is to thread emails
1780 itself.  If you want <code>git format-patch</code> to take care of threading, you
1781 will want to ensure that threading is disabled for <code>git send-email</code>.</p></div>
1782 </dd>
1783 <dt class="hdlist1">
1784 --in-reply-to=&lt;message id&gt;
1785 </dt>
1786 <dd>
1787 <p>
1788         Make the first mail (or all the mails with <code>--no-thread</code>) appear as a
1789         reply to the given &lt;message id&gt;, which avoids breaking threads to
1790         provide a new patch series.
1791 </p>
1792 </dd>
1793 <dt class="hdlist1">
1794 --ignore-if-in-upstream
1795 </dt>
1796 <dd>
1797 <p>
1798         Do not include a patch that matches a commit in
1799         &lt;until&gt;..&lt;since&gt;.  This will examine all patches reachable
1800         from &lt;since&gt; but not from &lt;until&gt; and compare them with the
1801         patches being generated, and any patch that matches is
1802         ignored.
1803 </p>
1804 </dd>
1805 <dt class="hdlist1">
1806 --always
1807 </dt>
1808 <dd>
1809 <p>
1810         Include patches for commits that do not introduce any change,
1811         which are omitted by default.
1812 </p>
1813 </dd>
1814 <dt class="hdlist1">
1815 --cover-from-description=&lt;mode&gt;
1816 </dt>
1817 <dd>
1818 <p>
1819         Controls which parts of the cover letter will be automatically
1820         populated using the branch&#8217;s description.
1821 </p>
1822 <div class="paragraph"><p>If <code>&lt;mode&gt;</code> is <code>message</code> or <code>default</code>, the cover letter subject will be
1823 populated with placeholder text. The body of the cover letter will be
1824 populated with the branch&#8217;s description. This is the default mode when
1825 no configuration nor command line option is specified.</p></div>
1826 <div class="paragraph"><p>If <code>&lt;mode&gt;</code> is <code>subject</code>, the first paragraph of the branch description will
1827 populate the cover letter subject. The remainder of the description will
1828 populate the body of the cover letter.</p></div>
1829 <div class="paragraph"><p>If <code>&lt;mode&gt;</code> is <code>auto</code>, if the first paragraph of the branch description
1830 is greater than 100 bytes, then the mode will be <code>message</code>, otherwise
1831 <code>subject</code> will be used.</p></div>
1832 <div class="paragraph"><p>If <code>&lt;mode&gt;</code> is <code>none</code>, both the cover letter subject and body will be
1833 populated with placeholder text.</p></div>
1834 </dd>
1835 <dt class="hdlist1">
1836 --description-file=&lt;file&gt;
1837 </dt>
1838 <dd>
1839 <p>
1840         Use the contents of &lt;file&gt; instead of the branch&#8217;s description
1841         for generating the cover letter.
1842 </p>
1843 </dd>
1844 <dt class="hdlist1">
1845 --subject-prefix=&lt;subject prefix&gt;
1846 </dt>
1847 <dd>
1848 <p>
1849         Instead of the standard <em>[PATCH]</em> prefix in the subject
1850         line, instead use <em>[&lt;subject prefix&gt;]</em>. This can be used
1851         to name a patch series, and can be combined with the
1852         <code>--numbered</code> option.
1853 </p>
1854 <div class="paragraph"><p>The configuration variable <code>format.subjectPrefix</code> may also be used
1855 to configure a subject prefix to apply to a given repository for
1856 all patches. This is often useful on mailing lists which receive
1857 patches for several repositories and can be used to disambiguate
1858 the patches (with a value of e.g. "PATCH my-project").</p></div>
1859 </dd>
1860 <dt class="hdlist1">
1861 --filename-max-length=&lt;n&gt;
1862 </dt>
1863 <dd>
1864 <p>
1865         Instead of the standard 64 bytes, chomp the generated output
1866         filenames at around <em>&lt;n&gt;</em> bytes (too short a value will be
1867         silently raised to a reasonable length).  Defaults to the
1868         value of the <code>format.filenameMaxLength</code> configuration
1869         variable, or 64 if unconfigured.
1870 </p>
1871 </dd>
1872 <dt class="hdlist1">
1873 --rfc
1874 </dt>
1875 <dd>
1876 <p>
1877         Prepends "RFC" to the subject prefix (producing "RFC PATCH" by
1878         default). RFC means "Request For Comments"; use this when sending
1879         an experimental patch for discussion rather than application.
1880 </p>
1881 </dd>
1882 <dt class="hdlist1">
1883 -v &lt;n&gt;
1884 </dt>
1885 <dt class="hdlist1">
1886 --reroll-count=&lt;n&gt;
1887 </dt>
1888 <dd>
1889 <p>
1890         Mark the series as the &lt;n&gt;-th iteration of the topic. The
1891         output filenames have <code>v&lt;n&gt;</code> prepended to them, and the
1892         subject prefix ("PATCH" by default, but configurable via the
1893         <code>--subject-prefix</code> option) has ` v&lt;n&gt;` appended to it.  E.g.
1894         <code>--reroll-count=4</code> may produce <code>v4-0001-add-makefile.patch</code>
1895         file that has "Subject: [PATCH v4 1/20] Add makefile" in it.
1896         <code>&lt;n&gt;</code> does not have to be an integer (e.g. "--reroll-count=4.4",
1897         or "--reroll-count=4rev2" are allowed), but the downside of
1898         using such a reroll-count is that the range-diff/interdiff
1899         with the previous version does not state exactly which
1900         version the new iteration is compared against.
1901 </p>
1902 </dd>
1903 <dt class="hdlist1">
1904 --to=&lt;email&gt;
1905 </dt>
1906 <dd>
1907 <p>
1908         Add a <code>To:</code> header to the email headers. This is in addition
1909         to any configured headers, and may be used multiple times.
1910         The negated form <code>--no-to</code> discards all <code>To:</code> headers added so
1911         far (from config or command line).
1912 </p>
1913 </dd>
1914 <dt class="hdlist1">
1915 --cc=&lt;email&gt;
1916 </dt>
1917 <dd>
1918 <p>
1919         Add a <code>Cc:</code> header to the email headers. This is in addition
1920         to any configured headers, and may be used multiple times.
1921         The negated form <code>--no-cc</code> discards all <code>Cc:</code> headers added so
1922         far (from config or command line).
1923 </p>
1924 </dd>
1925 <dt class="hdlist1">
1926 --from
1927 </dt>
1928 <dt class="hdlist1">
1929 --from=&lt;ident&gt;
1930 </dt>
1931 <dd>
1932 <p>
1933         Use <code>ident</code> in the <code>From:</code> header of each commit email. If the
1934         author ident of the commit is not textually identical to the
1935         provided <code>ident</code>, place a <code>From:</code> header in the body of the
1936         message with the original author. If no <code>ident</code> is given, use
1937         the committer ident.
1938 </p>
1939 <div class="paragraph"><p>Note that this option is only useful if you are actually sending the
1940 emails and want to identify yourself as the sender, but retain the
1941 original author (and <code>git am</code> will correctly pick up the in-body
1942 header). Note also that <code>git send-email</code> already handles this
1943 transformation for you, and this option should not be used if you are
1944 feeding the result to <code>git send-email</code>.</p></div>
1945 </dd>
1946 <dt class="hdlist1">
1947 --[no-]force-in-body-from
1948 </dt>
1949 <dd>
1950 <p>
1951         With the e-mail sender specified via the <code>--from</code> option, by
1952         default, an in-body "From:" to identify the real author of
1953         the commit is added at the top of the commit log message if
1954         the sender is different from the author.  With this option,
1955         the in-body "From:" is added even when the sender and the
1956         author have the same name and address, which may help if the
1957         mailing list software mangles the sender&#8217;s identity.
1958         Defaults to the value of the <code>format.forceInBodyFrom</code>
1959         configuration variable.
1960 </p>
1961 </dd>
1962 <dt class="hdlist1">
1963 --add-header=&lt;header&gt;
1964 </dt>
1965 <dd>
1966 <p>
1967         Add an arbitrary header to the email headers.  This is in addition
1968         to any configured headers, and may be used multiple times.
1969         For example, <code>--add-header="Organization: git-foo"</code>.
1970         The negated form <code>--no-add-header</code> discards <strong>all</strong> (<code>To:</code>,
1971         <code>Cc:</code>, and custom) headers added so far from config or command
1972         line.
1973 </p>
1974 </dd>
1975 <dt class="hdlist1">
1976 --[no-]cover-letter
1977 </dt>
1978 <dd>
1979 <p>
1980         In addition to the patches, generate a cover letter file
1981         containing the branch description, shortlog and the overall diffstat.  You can
1982         fill in a description in the file before sending it out.
1983 </p>
1984 </dd>
1985 <dt class="hdlist1">
1986 --encode-email-headers
1987 </dt>
1988 <dt class="hdlist1">
1989 --no-encode-email-headers
1990 </dt>
1991 <dd>
1992 <p>
1993         Encode email headers that have non-ASCII characters with
1994         "Q-encoding" (described in RFC 2047), instead of outputting the
1995         headers verbatim. Defaults to the value of the
1996         <code>format.encodeEmailHeaders</code> configuration variable.
1997 </p>
1998 </dd>
1999 <dt class="hdlist1">
2000 --interdiff=&lt;previous&gt;
2001 </dt>
2002 <dd>
2003 <p>
2004         As a reviewer aid, insert an interdiff into the cover letter,
2005         or as commentary of the lone patch of a 1-patch series, showing
2006         the differences between the previous version of the patch series and
2007         the series currently being formatted. <code>previous</code> is a single revision
2008         naming the tip of the previous series which shares a common base with
2009         the series being formatted (for example <code>git format-patch
2010         --cover-letter --interdiff=feature/v1 -3 feature/v2</code>).
2011 </p>
2012 </dd>
2013 <dt class="hdlist1">
2014 --range-diff=&lt;previous&gt;
2015 </dt>
2016 <dd>
2017 <p>
2018         As a reviewer aid, insert a range-diff (see <a href="git-range-diff.html">git-range-diff(1)</a>)
2019         into the cover letter, or as commentary of the lone patch of a
2020         1-patch series, showing the differences between the previous
2021         version of the patch series and the series currently being formatted.
2022         <code>previous</code> can be a single revision naming the tip of the previous
2023         series if it shares a common base with the series being formatted (for
2024         example <code>git format-patch --cover-letter --range-diff=feature/v1 -3
2025         feature/v2</code>), or a revision range if the two versions of the series are
2026         disjoint (for example <code>git format-patch --cover-letter
2027         --range-diff=feature/v1~3..feature/v1 -3 feature/v2</code>).
2028 </p>
2029 <div class="paragraph"><p>Note that diff options passed to the command affect how the primary
2030 product of <code>format-patch</code> is generated, and they are not passed to
2031 the underlying <code>range-diff</code> machinery used to generate the cover-letter
2032 material (this may change in the future).</p></div>
2033 </dd>
2034 <dt class="hdlist1">
2035 --creation-factor=&lt;percent&gt;
2036 </dt>
2037 <dd>
2038 <p>
2039         Used with <code>--range-diff</code>, tweak the heuristic which matches up commits
2040         between the previous and current series of patches by adjusting the
2041         creation/deletion cost fudge factor. See <a href="git-range-diff.html">git-range-diff(1)</a>)
2042         for details.
2043 </p>
2044 </dd>
2045 <dt class="hdlist1">
2046 --notes[=&lt;ref&gt;]
2047 </dt>
2048 <dt class="hdlist1">
2049 --no-notes
2050 </dt>
2051 <dd>
2052 <p>
2053         Append the notes (see <a href="git-notes.html">git-notes(1)</a>) for the commit
2054         after the three-dash line.
2055 </p>
2056 <div class="paragraph"><p>The expected use case of this is to write supporting explanation for
2057 the commit that does not belong to the commit log message proper,
2058 and include it with the patch submission. While one can simply write
2059 these explanations after <code>format-patch</code> has run but before sending,
2060 keeping them as Git notes allows them to be maintained between versions
2061 of the patch series (but see the discussion of the <code>notes.rewrite</code>
2062 configuration options in <a href="git-notes.html">git-notes(1)</a> to use this workflow).</p></div>
2063 <div class="paragraph"><p>The default is <code>--no-notes</code>, unless the <code>format.notes</code> configuration is
2064 set.</p></div>
2065 </dd>
2066 <dt class="hdlist1">
2067 --[no-]signature=&lt;signature&gt;
2068 </dt>
2069 <dd>
2070 <p>
2071         Add a signature to each message produced. Per RFC 3676 the signature
2072         is separated from the body by a line with '-- ' on it. If the
2073         signature option is omitted the signature defaults to the Git version
2074         number.
2075 </p>
2076 </dd>
2077 <dt class="hdlist1">
2078 --signature-file=&lt;file&gt;
2079 </dt>
2080 <dd>
2081 <p>
2082         Works just like --signature except the signature is read from a file.
2083 </p>
2084 </dd>
2085 <dt class="hdlist1">
2086 --suffix=.&lt;sfx&gt;
2087 </dt>
2088 <dd>
2089 <p>
2090         Instead of using <code>.patch</code> as the suffix for generated
2091         filenames, use specified suffix.  A common alternative is
2092         <code>--suffix=.txt</code>.  Leaving this empty will remove the <code>.patch</code>
2093         suffix.
2094 </p>
2095 <div class="paragraph"><p>Note that the leading character does not have to be a dot; for example,
2096 you can use <code>--suffix=-patch</code> to get <code>0001-description-of-my-change-patch</code>.</p></div>
2097 </dd>
2098 <dt class="hdlist1">
2099 -q
2100 </dt>
2101 <dt class="hdlist1">
2102 --quiet
2103 </dt>
2104 <dd>
2105 <p>
2106         Do not print the names of the generated files to standard output.
2107 </p>
2108 </dd>
2109 <dt class="hdlist1">
2110 --no-binary
2111 </dt>
2112 <dd>
2113 <p>
2114         Do not output contents of changes in binary files, instead
2115         display a notice that those files changed.  Patches generated
2116         using this option cannot be applied properly, but they are
2117         still useful for code review.
2118 </p>
2119 </dd>
2120 <dt class="hdlist1">
2121 --zero-commit
2122 </dt>
2123 <dd>
2124 <p>
2125   Output an all-zero hash in each patch&#8217;s From header instead
2126   of the hash of the commit.
2127 </p>
2128 </dd>
2129 <dt class="hdlist1">
2130 --[no-]base[=&lt;commit&gt;]
2131 </dt>
2132 <dd>
2133 <p>
2134         Record the base tree information to identify the state the
2135         patch series applies to.  See the BASE TREE INFORMATION section
2136         below for details. If &lt;commit&gt; is "auto", a base commit is
2137         automatically chosen. The <code>--no-base</code> option overrides a
2138         <code>format.useAutoBase</code> configuration.
2139 </p>
2140 </dd>
2141 <dt class="hdlist1">
2142 --root
2143 </dt>
2144 <dd>
2145 <p>
2146         Treat the revision argument as a &lt;revision range&gt;, even if it
2147         is just a single commit (that would normally be treated as a
2148         &lt;since&gt;).  Note that root commits included in the specified
2149         range are always formatted as creation patches, independently
2150         of this flag.
2151 </p>
2152 </dd>
2153 <dt class="hdlist1">
2154 --progress
2155 </dt>
2156 <dd>
2157 <p>
2158         Show progress reports on stderr as patches are generated.
2159 </p>
2160 </dd>
2161 </dl></div>
2162 </div>
2163 </div>
2164 <div class="sect1">
2165 <h2 id="_configuration">CONFIGURATION</h2>
2166 <div class="sectionbody">
2167 <div class="paragraph"><p>You can specify extra mail header lines to be added to each message,
2168 defaults for the subject prefix and file suffix, number patches when
2169 outputting more than one patch, add "To:" or "Cc:" headers, configure
2170 attachments, change the patch output directory, and sign off patches
2171 with configuration variables.</p></div>
2172 <div class="listingblock">
2173 <div class="content">
2174 <pre><code>[format]
2175         headers = "Organization: git-foo\n"
2176         subjectPrefix = CHANGE
2177         suffix = .txt
2178         numbered = auto
2179         to = &lt;email&gt;
2180         cc = &lt;email&gt;
2181         attach [ = mime-boundary-string ]
2182         signOff = true
2183         outputDirectory = &lt;directory&gt;
2184         coverLetter = auto
2185         coverFromDescription = auto</code></pre>
2186 </div></div>
2187 </div>
2188 </div>
2189 <div class="sect1">
2190 <h2 id="_discussion">DISCUSSION</h2>
2191 <div class="sectionbody">
2192 <div class="paragraph"><p>The patch produced by <em>git format-patch</em> is in UNIX mailbox format,
2193 with a fixed "magic" time stamp to indicate that the file is output
2194 from format-patch rather than a real mailbox, like so:</p></div>
2195 <div class="listingblock">
2196 <div class="content">
2197 <pre><code>From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
2198 From: Tony Luck &lt;tony.luck@intel.com&gt;
2199 Date: Tue, 13 Jul 2010 11:42:54 -0700
2200 Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
2201  =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
2202 MIME-Version: 1.0
2203 Content-Type: text/plain; charset=UTF-8
2204 Content-Transfer-Encoding: 8bit
2205
2206 arch/arm config files were slimmed down using a python script
2207 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
2208
2209 Do the same for ia64 so we can have sleek &amp; trim looking
2210 ...</code></pre>
2211 </div></div>
2212 <div class="paragraph"><p>Typically it will be placed in a MUA&#8217;s drafts folder, edited to add
2213 timely commentary that should not go in the changelog after the three
2214 dashes, and then sent as a message whose body, in our example, starts
2215 with "arch/arm config files were&#8230;".  On the receiving end, readers
2216 can save interesting patches in a UNIX mailbox and apply them with
2217 <a href="git-am.html">git-am(1)</a>.</p></div>
2218 <div class="paragraph"><p>When a patch is part of an ongoing discussion, the patch generated by
2219 <em>git format-patch</em> can be tweaked to take advantage of the <em>git am
2220 --scissors</em> feature.  After your response to the discussion comes a
2221 line that consists solely of "<code>-- &gt;8 --</code>" (scissors and perforation),
2222 followed by the patch with unnecessary header fields removed:</p></div>
2223 <div class="listingblock">
2224 <div class="content">
2225 <pre><code>...
2226 &gt; So we should do such-and-such.
2227
2228 Makes sense to me.  How about this patch?
2229
2230 -- &gt;8 --
2231 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
2232
2233 arch/arm config files were slimmed down using a python script
2234 ...</code></pre>
2235 </div></div>
2236 <div class="paragraph"><p>When sending a patch this way, most often you are sending your own
2237 patch, so in addition to the "<code>From $SHA1 $magic_timestamp</code>" marker you
2238 should omit <code>From:</code> and <code>Date:</code> lines from the patch file.  The patch
2239 title is likely to be different from the subject of the discussion the
2240 patch is in response to, so it is likely that you would want to keep
2241 the Subject: line, like the example above.</p></div>
2242 <div class="sect2">
2243 <h3 id="_checking_for_patch_corruption">Checking for patch corruption</h3>
2244 <div class="paragraph"><p>Many mailers if not set up properly will corrupt whitespace.  Here are
2245 two common types of corruption:</p></div>
2246 <div class="ulist"><ul>
2247 <li>
2248 <p>
2249 Empty context lines that do not have <em>any</em> whitespace.
2250 </p>
2251 </li>
2252 <li>
2253 <p>
2254 Non-empty context lines that have one extra whitespace at the
2255   beginning.
2256 </p>
2257 </li>
2258 </ul></div>
2259 <div class="paragraph"><p>One way to test if your MUA is set up correctly is:</p></div>
2260 <div class="ulist"><ul>
2261 <li>
2262 <p>
2263 Send the patch to yourself, exactly the way you would, except
2264   with To: and Cc: lines that do not contain the list and
2265   maintainer address.
2266 </p>
2267 </li>
2268 <li>
2269 <p>
2270 Save that patch to a file in UNIX mailbox format.  Call it a.patch,
2271   say.
2272 </p>
2273 </li>
2274 <li>
2275 <p>
2276 Apply it:
2277 </p>
2278 <div class="literalblock">
2279 <div class="content">
2280 <pre><code>$ git fetch &lt;project&gt; master:test-apply
2281 $ git switch test-apply
2282 $ git restore --source=HEAD --staged --worktree :/
2283 $ git am a.patch</code></pre>
2284 </div></div>
2285 </li>
2286 </ul></div>
2287 <div class="paragraph"><p>If it does not apply correctly, there can be various reasons.</p></div>
2288 <div class="ulist"><ul>
2289 <li>
2290 <p>
2291 The patch itself does not apply cleanly.  That is <em>bad</em> but
2292   does not have much to do with your MUA.  You might want to rebase
2293   the patch with <a href="git-rebase.html">git-rebase(1)</a> before regenerating it in
2294   this case.
2295 </p>
2296 </li>
2297 <li>
2298 <p>
2299 The MUA corrupted your patch; "am" would complain that
2300   the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and
2301   see what <em>patch</em> file contains and check for the common
2302   corruption patterns mentioned above.
2303 </p>
2304 </li>
2305 <li>
2306 <p>
2307 While at it, check the <em>info</em> and <em>final-commit</em> files as well.
2308   If what is in <em>final-commit</em> is not exactly what you would want to
2309   see in the commit log message, it is very likely that the
2310   receiver would end up hand editing the log message when applying
2311   your patch.  Things like "Hi, this is my first patch.\n" in the
2312   patch e-mail should come after the three-dash line that signals
2313   the end of the commit message.
2314 </p>
2315 </li>
2316 </ul></div>
2317 </div>
2318 </div>
2319 </div>
2320 <div class="sect1">
2321 <h2 id="_mua_specific_hints">MUA-SPECIFIC HINTS</h2>
2322 <div class="sectionbody">
2323 <div class="paragraph"><p>Here are some hints on how to successfully submit patches inline using
2324 various mailers.</p></div>
2325 <div class="sect2">
2326 <h3 id="_gmail">GMail</h3>
2327 <div class="paragraph"><p>GMail does not have any way to turn off line wrapping in the web
2328 interface, so it will mangle any emails that you send.  You can however
2329 use "git send-email" and send your patches through the GMail SMTP server, or
2330 use any IMAP email client to connect to the google IMAP server and forward
2331 the emails through that.</p></div>
2332 <div class="paragraph"><p>For hints on using <em>git send-email</em> to send your patches through the
2333 GMail SMTP server, see the EXAMPLE section of <a href="git-send-email.html">git-send-email(1)</a>.</p></div>
2334 <div class="paragraph"><p>For hints on submission using the IMAP interface, see the EXAMPLE
2335 section of <a href="git-imap-send.html">git-imap-send(1)</a>.</p></div>
2336 </div>
2337 <div class="sect2">
2338 <h3 id="_thunderbird">Thunderbird</h3>
2339 <div class="paragraph"><p>By default, Thunderbird will both wrap emails as well as flag
2340 them as being <em>format=flowed</em>, both of which will make the
2341 resulting email unusable by Git.</p></div>
2342 <div class="paragraph"><p>There are three different approaches: use an add-on to turn off line wraps,
2343 configure Thunderbird to not mangle patches, or use
2344 an external editor to keep Thunderbird from mangling the patches.</p></div>
2345 <div class="sect3">
2346 <h4 id="_approach_1_add_on">Approach #1 (add-on)</h4>
2347 <div class="paragraph"><p>Install the Toggle Word Wrap add-on that is available from
2348 <a href="https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/">https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/</a>
2349 It adds a menu entry "Enable Word Wrap" in the composer&#8217;s "Options" menu
2350 that you can tick off. Now you can compose the message as you otherwise do
2351 (cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc), but you have to
2352 insert line breaks manually in any text that you type.</p></div>
2353 </div>
2354 <div class="sect3">
2355 <h4 id="_approach_2_configuration">Approach #2 (configuration)</h4>
2356 <div class="paragraph"><p>Three steps:</p></div>
2357 <div class="olist arabic"><ol class="arabic">
2358 <li>
2359 <p>
2360 Configure your mail server composition as plain text:
2361    Edit&#8230;Account Settings&#8230;Composition &amp; Addressing,
2362    uncheck "Compose Messages in HTML".
2363 </p>
2364 </li>
2365 <li>
2366 <p>
2367 Configure your general composition window to not wrap.
2368 </p>
2369 <div class="paragraph"><p>In Thunderbird 2:
2370 Edit..Preferences..Composition, wrap plain text messages at 0</p></div>
2371 <div class="paragraph"><p>In Thunderbird 3:
2372 Edit..Preferences..Advanced..Config Editor.  Search for
2373 "mail.wrap_long_lines".
2374 Toggle it to make sure it is set to <code>false</code>. Also, search for
2375 "mailnews.wraplength" and set the value to 0.</p></div>
2376 </li>
2377 <li>
2378 <p>
2379 Disable the use of format=flowed:
2380    Edit..Preferences..Advanced..Config Editor.  Search for
2381    "mailnews.send_plaintext_flowed".
2382    Toggle it to make sure it is set to <code>false</code>.
2383 </p>
2384 </li>
2385 </ol></div>
2386 <div class="paragraph"><p>After that is done, you should be able to compose email as you
2387 otherwise would (cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc),
2388 and the patches will not be mangled.</p></div>
2389 </div>
2390 <div class="sect3">
2391 <h4 id="_approach_3_external_editor">Approach #3 (external editor)</h4>
2392 <div class="paragraph"><p>The following Thunderbird extensions are needed:
2393 AboutConfig from <a href="http://aboutconfig.mozdev.org/">http://aboutconfig.mozdev.org/</a> and
2394 External Editor from <a href="http://globs.org/articles.php?lng=en&amp;pg=8">http://globs.org/articles.php?lng=en&amp;pg=8</a></p></div>
2395 <div class="olist arabic"><ol class="arabic">
2396 <li>
2397 <p>
2398 Prepare the patch as a text file using your method of choice.
2399 </p>
2400 </li>
2401 <li>
2402 <p>
2403 Before opening a compose window, use Edit&#8594;Account Settings to
2404    uncheck the "Compose messages in HTML format" setting in the
2405    "Composition &amp; Addressing" panel of the account to be used to
2406    send the patch.
2407 </p>
2408 </li>
2409 <li>
2410 <p>
2411 In the main Thunderbird window, <em>before</em> you open the compose
2412    window for the patch, use Tools&#8594;about:config to set the
2413    following to the indicated values:
2414 </p>
2415 <div class="listingblock">
2416 <div class="content">
2417 <pre><code>        mailnews.send_plaintext_flowed  =&gt; false
2418         mailnews.wraplength             =&gt; 0</code></pre>
2419 </div></div>
2420 </li>
2421 <li>
2422 <p>
2423 Open a compose window and click the external editor icon.
2424 </p>
2425 </li>
2426 <li>
2427 <p>
2428 In the external editor window, read in the patch file and exit
2429    the editor normally.
2430 </p>
2431 </li>
2432 </ol></div>
2433 <div class="paragraph"><p>Side note: it may be possible to do step 2 with
2434 about:config and the following settings but no one&#8217;s tried yet.</p></div>
2435 <div class="listingblock">
2436 <div class="content">
2437 <pre><code>        mail.html_compose                       =&gt; false
2438         mail.identity.default.compose_html      =&gt; false
2439         mail.identity.id?.compose_html          =&gt; false</code></pre>
2440 </div></div>
2441 <div class="paragraph"><p>There is a script in contrib/thunderbird-patch-inline which can help
2442 you include patches with Thunderbird in an easy way. To use it, do the
2443 steps above and then use the script as the external editor.</p></div>
2444 </div>
2445 </div>
2446 <div class="sect2">
2447 <h3 id="_kmail">KMail</h3>
2448 <div class="paragraph"><p>This should help you to submit patches inline using KMail.</p></div>
2449 <div class="olist arabic"><ol class="arabic">
2450 <li>
2451 <p>
2452 Prepare the patch as a text file.
2453 </p>
2454 </li>
2455 <li>
2456 <p>
2457 Click on New Mail.
2458 </p>
2459 </li>
2460 <li>
2461 <p>
2462 Go under "Options" in the Composer window and be sure that
2463    "Word wrap" is not set.
2464 </p>
2465 </li>
2466 <li>
2467 <p>
2468 Use Message &#8594; Insert file&#8230; and insert the patch.
2469 </p>
2470 </li>
2471 <li>
2472 <p>
2473 Back in the compose window: add whatever other text you wish to the
2474    message, complete the addressing and subject fields, and press send.
2475 </p>
2476 </li>
2477 </ol></div>
2478 </div>
2479 </div>
2480 </div>
2481 <div class="sect1">
2482 <h2 id="_base_tree_information">BASE TREE INFORMATION</h2>
2483 <div class="sectionbody">
2484 <div class="paragraph"><p>The base tree information block is used for maintainers or third party
2485 testers to know the exact state the patch series applies to. It consists
2486 of the <em>base commit</em>, which is a well-known commit that is part of the
2487 stable part of the project history everybody else works off of, and zero
2488 or more <em>prerequisite patches</em>, which are well-known patches in flight
2489 that is not yet part of the <em>base commit</em> that need to be applied on top
2490 of <em>base commit</em> in topological order before the patches can be applied.</p></div>
2491 <div class="paragraph"><p>The <em>base commit</em> is shown as "base-commit: " followed by the 40-hex of
2492 the commit object name.  A <em>prerequisite patch</em> is shown as
2493 "prerequisite-patch-id: " followed by the 40-hex <em>patch id</em>, which can
2494 be obtained by passing the patch through the <code>git patch-id --stable</code>
2495 command.</p></div>
2496 <div class="paragraph"><p>Imagine that on top of the public commit P, you applied well-known
2497 patches X, Y and Z from somebody else, and then built your three-patch
2498 series A, B, C, the history would be like:</p></div>
2499 <div class="literalblock">
2500 <div class="content">
2501 <pre><code>---P---X---Y---Z---A---B---C</code></pre>
2502 </div></div>
2503 <div class="paragraph"><p>With <code>git format-patch --base=P -3 C</code> (or variants thereof, e.g. with
2504 <code>--cover-letter</code> or using <code>Z..C</code> instead of <code>-3 C</code> to specify the
2505 range), the base tree information block is shown at the end of the
2506 first message the command outputs (either the first patch, or the
2507 cover letter), like this:</p></div>
2508 <div class="listingblock">
2509 <div class="content">
2510 <pre><code>base-commit: P
2511 prerequisite-patch-id: X
2512 prerequisite-patch-id: Y
2513 prerequisite-patch-id: Z</code></pre>
2514 </div></div>
2515 <div class="paragraph"><p>For non-linear topology, such as</p></div>
2516 <div class="literalblock">
2517 <div class="content">
2518 <pre><code>---P---X---A---M---C
2519     \         /
2520      Y---Z---B</code></pre>
2521 </div></div>
2522 <div class="paragraph"><p>You can also use <code>git format-patch --base=P -3 C</code> to generate patches
2523 for A, B and C, and the identifiers for P, X, Y, Z are appended at the
2524 end of the first message.</p></div>
2525 <div class="paragraph"><p>If set <code>--base=auto</code> in cmdline, it will automatically compute
2526 the base commit as the merge base of tip commit of the remote-tracking
2527 branch and revision-range specified in cmdline.
2528 For a local branch, you need to make it to track a remote branch by <code>git branch
2529 --set-upstream-to</code> before using this option.</p></div>
2530 </div>
2531 </div>
2532 <div class="sect1">
2533 <h2 id="_examples">EXAMPLES</h2>
2534 <div class="sectionbody">
2535 <div class="ulist"><ul>
2536 <li>
2537 <p>
2538 Extract commits between revisions R1 and R2, and apply them on top of
2539   the current branch using <em>git am</em> to cherry-pick them:
2540 </p>
2541 <div class="listingblock">
2542 <div class="content">
2543 <pre><code>$ git format-patch -k --stdout R1..R2 | git am -3 -k</code></pre>
2544 </div></div>
2545 </li>
2546 <li>
2547 <p>
2548 Extract all commits which are in the current branch but not in the
2549   origin branch:
2550 </p>
2551 <div class="listingblock">
2552 <div class="content">
2553 <pre><code>$ git format-patch origin</code></pre>
2554 </div></div>
2555 <div class="paragraph"><p>For each commit a separate file is created in the current directory.</p></div>
2556 </li>
2557 <li>
2558 <p>
2559 Extract all commits that lead to <em>origin</em> since the inception of the
2560   project:
2561 </p>
2562 <div class="listingblock">
2563 <div class="content">
2564 <pre><code>$ git format-patch --root origin</code></pre>
2565 </div></div>
2566 </li>
2567 <li>
2568 <p>
2569 The same as the previous one:
2570 </p>
2571 <div class="listingblock">
2572 <div class="content">
2573 <pre><code>$ git format-patch -M -B origin</code></pre>
2574 </div></div>
2575 <div class="paragraph"><p>Additionally, it detects and handles renames and complete rewrites
2576 intelligently to produce a renaming patch.  A renaming patch reduces
2577 the amount of text output, and generally makes it easier to review.
2578 Note that non-Git "patch" programs won&#8217;t understand renaming patches, so
2579 use it only when you know the recipient uses Git to apply your patch.</p></div>
2580 </li>
2581 <li>
2582 <p>
2583 Extract three topmost commits from the current branch and format them
2584   as e-mailable patches:
2585 </p>
2586 <div class="listingblock">
2587 <div class="content">
2588 <pre><code>$ git format-patch -3</code></pre>
2589 </div></div>
2590 </li>
2591 </ul></div>
2592 </div>
2593 </div>
2594 <div class="sect1">
2595 <h2 id="_caveats">CAVEATS</h2>
2596 <div class="sectionbody">
2597 <div class="paragraph"><p>Note that <code>format-patch</code> will omit merge commits from the output, even
2598 if they are part of the requested range. A simple "patch" does not
2599 include enough information for the receiving end to reproduce the same
2600 merge commit.</p></div>
2601 </div>
2602 </div>
2603 <div class="sect1">
2604 <h2 id="_see_also">SEE ALSO</h2>
2605 <div class="sectionbody">
2606 <div class="paragraph"><p><a href="git-am.html">git-am(1)</a>, <a href="git-send-email.html">git-send-email(1)</a></p></div>
2607 </div>
2608 </div>
2609 <div class="sect1">
2610 <h2 id="_git">GIT</h2>
2611 <div class="sectionbody">
2612 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
2613 </div>
2614 </div>
2615 </div>
2616 <div id="footnotes"><hr /></div>
2617 <div id="footer">
2618 <div id="footer-text">
2619 Last updated
2620  2023-09-07 15:10:34 PDT
2621 </div>
2622 </div>
2623 </body>
2624 </html>