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