git-format-patch.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
   7 <meta name="generator" content="AsciiDoc 10.2.0" />
   8 <title>git-format-patch(1)</title>
   9 <style type="text/css">
  10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
  11
  12 /* Default font. */
  13 body {
  14   font-family: Georgia,serif;
  15 }
  16
  17 /* Title font. */
  18 h1, h2, h3, h4, h5, h6,
  19 div.title, caption.title,
  20 thead, p.table.header,
  21 #toctitle,
  22 #author, #revnumber, #revdate, #revremark,
  23 #footer {
  24   font-family: Arial,Helvetica,sans-serif;
  25 }
  26
  27 body {
  28   margin: 1em 5% 1em 5%;
  29 }
  30
  31 a {
  32   color: blue;
  33   text-decoration: underline;
  34 }
  35 a:visited {
  36   color: fuchsia;
  37 }
  38
  39 em {
  40   font-style: italic;
  41   color: navy;
  42 }
  43
  44 strong {
  45   font-weight: bold;
  46   color: #083194;
  47 }
  48
  49 h1, h2, h3, h4, h5, h6 {
  50   color: #527bbd;
  51   margin-top: 1.2em;
  52   margin-bottom: 0.5em;
  53   line-height: 1.3;
  54 }
  55
  56 h1, h2, h3 {
  57   border-bottom: 2px solid silver;
  58 }
  59 h2 {
  60   padding-top: 0.5em;
  61 }
  62 h3 {
  63   float: left;
  64 }
  65 h3 + * {
  66   clear: left;
  67 }
  68 h5 {
  69   font-size: 1.0em;
  70 }
  71
  72 div.sectionbody {
  73   margin-left: 0;
  74 }
  75
  76 hr {
  77   border: 1px solid silver;
  78 }
  79
  80 p {
  81   margin-top: 0.5em;
  82   margin-bottom: 0.5em;
  83 }
  84
  85 ul, ol, li > p {
  86   margin-top: 0;
  87 }
  88 ul > li     { color: #aaa; }
  89 ul > li > * { color: black; }
  90
  91 .monospaced, code, pre {
  92   font-family: "Courier New", Courier, monospace;
  93   font-size: inherit;
  94   color: navy;
  95   padding: 0;
  96   margin: 0;
  97 }
  98 pre {
  99   white-space: pre-wrap;
 100 }
 101
 102 #author {
 103   color: #527bbd;
 104   font-weight: bold;
 105   font-size: 1.1em;
 106 }
 107 #email {
 108 }
 109 #revnumber, #revdate, #revremark {
 110 }
 111
 112 #footer {
 113   font-size: small;
 114   border-top: 2px solid silver;
 115   padding-top: 0.5em;
 116   margin-top: 4.0em;
 117 }
 118 #footer-text {
 119   float: left;
 120   padding-bottom: 0.5em;
 121 }
 122 #footer-badges {
 123   float: right;
 124   padding-bottom: 0.5em;
 125 }
 126
 127 #preamble {
 128   margin-top: 1.5em;
 129   margin-bottom: 1.5em;
 130 }
 131 div.imageblock, div.exampleblock, div.verseblock,
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 133 div.admonitionblock {
 134   margin-top: 1.0em;
 135   margin-bottom: 1.5em;
 136 }
 137 div.admonitionblock {
 138   margin-top: 2.0em;
 139   margin-bottom: 2.0em;
 140   margin-right: 10%;
 141   color: #606060;
 142 }
 143
 144 div.content { /* Block element content. */
 145   padding: 0;
 146 }
 147
 148 /* Block element titles. */
 149 div.title, caption.title {
 150   color: #527bbd;
 151   font-weight: bold;
 152   text-align: left;
 153   margin-top: 1.0em;
 154   margin-bottom: 0.5em;
 155 }
 156 div.title + * {
 157   margin-top: 0;
 158 }
 159
 160 td div.title:first-child {
 161   margin-top: 0.0em;
 162 }
 163 div.content div.title:first-child {
 164   margin-top: 0.0em;
 165 }
 166 div.content + div.title {
 167   margin-top: 0.0em;
 168 }
 169
 170 div.sidebarblock > div.content {
 171   background: #ffffee;
 172   border: 1px solid #dddddd;
 173   border-left: 4px solid #f0f0f0;
 174   padding: 0.5em;
 175 }
 176
 177 div.listingblock > div.content {
 178   border: 1px solid #dddddd;
 179   border-left: 5px solid #f0f0f0;
 180   background: #f8f8f8;
 181   padding: 0.5em;
 182 }
 183
 184 div.quoteblock, div.verseblock {
 185   padding-left: 1.0em;
 186   margin-left: 1.0em;
 187   margin-right: 10%;
 188   border-left: 5px solid #f0f0f0;
 189   color: #888;
 190 }
 191
 192 div.quoteblock > div.attribution {
 193   padding-top: 0.5em;
 194   text-align: right;
 195 }
 196
 197 div.verseblock > pre.content {
 198   font-family: inherit;
 199   font-size: inherit;
 200 }
 201 div.verseblock > div.attribution {
 202   padding-top: 0.75em;
 203   text-align: left;
 204 }
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 206 div.verseblock + div.attribution {
 207   text-align: left;
 208 }
 209
 210 div.admonitionblock .icon {
 211   vertical-align: top;
 212   font-size: 1.1em;
 213   font-weight: bold;
 214   text-decoration: underline;
 215   color: #527bbd;
 216   padding-right: 0.5em;
 217 }
 218 div.admonitionblock td.content {
 219   padding-left: 0.5em;
 220   border-left: 3px solid #dddddd;
 221 }
 222
 223 div.exampleblock > div.content {
 224   border-left: 3px solid #dddddd;
 225   padding-left: 0.5em;
 226 }
 227
 228 div.imageblock div.content { padding-left: 0; }
 229 span.image img { border-style: none; vertical-align: text-bottom; }
 230 a.image:visited { color: white; }
 231
 232 dl {
 233   margin-top: 0.8em;
 234   margin-bottom: 0.8em;
 235 }
 236 dt {
 237   margin-top: 0.5em;
 238   margin-bottom: 0;
 239   font-style: normal;
 240   color: navy;
 241 }
 242 dd > *:first-child {
 243   margin-top: 0.1em;
 244 }
 245
 246 ul, ol {
 247     list-style-position: outside;
 248 }
 249 ol.arabic {
 250   list-style-type: decimal;
 251 }
 252 ol.loweralpha {
 253   list-style-type: lower-alpha;
 254 }
 255 ol.upperalpha {
 256   list-style-type: upper-alpha;
 257 }
 258 ol.lowerroman {
 259   list-style-type: lower-roman;
 260 }
 261 ol.upperroman {
 262   list-style-type: upper-roman;
 263 }
 264
 265 div.compact ul, div.compact ol,
 266 div.compact p, div.compact p,
 267 div.compact div, div.compact div {
 268   margin-top: 0.1em;
 269   margin-bottom: 0.1em;
 270 }
 271
 272 tfoot {
 273   font-weight: bold;
 274 }
 275 td > div.verse {
 276   white-space: pre;
 277 }
 278
 279 div.hdlist {
 280   margin-top: 0.8em;
 281   margin-bottom: 0.8em;
 282 }
 283 div.hdlist tr {
 284   padding-bottom: 15px;
 285 }
 286 dt.hdlist1.strong, td.hdlist1.strong {
 287   font-weight: bold;
 288 }
 289 td.hdlist1 {
 290   vertical-align: top;
 291   font-style: normal;
 292   padding-right: 0.8em;
 293   color: navy;
 294 }
 295 td.hdlist2 {
 296   vertical-align: top;
 297 }
 298 div.hdlist.compact tr {
 299   margin: 0;
 300   padding-bottom: 0;
 301 }
 302
 303 .comment {
 304   background: yellow;
 305 }
 306
 307 .footnote, .footnoteref {
 308   font-size: 0.8em;
 309 }
 310
 311 span.footnote, span.footnoteref {
 312   vertical-align: super;
 313 }
 314
 315 #footnotes {
 316   margin: 20px 0 20px 0;
 317   padding: 7px 0 0 0;
 318 }
 319
 320 #footnotes div.footnote {
 321   margin: 0 0 5px 0;
 322 }
 323
 324 #footnotes hr {
 325   border: none;
 326   border-top: 1px solid silver;
 327   height: 1px;
 328   text-align: left;
 329   margin-left: 0;
 330   width: 20%;
 331   min-width: 100px;
 332 }
 333
 334 div.colist td {
 335   padding-right: 0.5em;
 336   padding-bottom: 0.3em;
 337   vertical-align: top;
 338 }
 339 div.colist td img {
 340   margin-top: 0.3em;
 341 }
 342
 343 @media print {
 344   #footer-badges { display: none; }
 345 }
 346
 347 #toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 #toctitle {
 352   color: #527bbd;
 353   font-size: 1.1em;
 354   font-weight: bold;
 355   margin-top: 1.0em;
 356   margin-bottom: 0.1em;
 357 }
 358
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 360   margin-top: 0;
 361   margin-bottom: 0;
 362 }
 363 div.toclevel2 {
 364   margin-left: 2em;
 365   font-size: 0.9em;
 366 }
 367 div.toclevel3 {
 368   margin-left: 4em;
 369   font-size: 0.9em;
 370 }
 371 div.toclevel4 {
 372   margin-left: 6em;
 373   font-size: 0.9em;
 374 }
 375
 376 span.aqua { color: aqua; }
 377 span.black { color: black; }
 378 span.blue { color: blue; }
 379 span.fuchsia { color: fuchsia; }
 380 span.gray { color: gray; }
 381 span.green { color: green; }
 382 span.lime { color: lime; }
 383 span.maroon { color: maroon; }
 384 span.navy { color: navy; }
 385 span.olive { color: olive; }
 386 span.purple { color: purple; }
 387 span.red { color: red; }
 388 span.silver { color: silver; }
 389 span.teal { color: teal; }
 390 span.white { color: white; }
 391 span.yellow { color: yellow; }
 392
 393 span.aqua-background { background: aqua; }
 394 span.black-background { background: black; }
 395 span.blue-background { background: blue; }
 396 span.fuchsia-background { background: fuchsia; }
 397 span.gray-background { background: gray; }
 398 span.green-background { background: green; }
 399 span.lime-background { background: lime; }
 400 span.maroon-background { background: maroon; }
 401 span.navy-background { background: navy; }
 402 span.olive-background { background: olive; }
 403 span.purple-background { background: purple; }
 404 span.red-background { background: red; }
 405 span.silver-background { background: silver; }
 406 span.teal-background { background: teal; }
 407 span.white-background { background: white; }
 408 span.yellow-background { background: yellow; }
 409
 410 span.big { font-size: 2em; }
 411 span.small { font-size: 0.6em; }
 412
 413 span.underline { text-decoration: underline; }
 414 span.overline { text-decoration: overline; }
 415 span.line-through { text-decoration: line-through; }
 416
 417 div.unbreakable { page-break-inside: avoid; }
 418
 419
 420 /*
 421  * xhtml11 specific
 422  *
 423  * */
 424
 425 div.tableblock {
 426   margin-top: 1.0em;
 427   margin-bottom: 1.5em;
 428 }
 429 div.tableblock > table {
 430   border: 3px solid #527bbd;
 431 }
 432 thead, p.table.header {
 433   font-weight: bold;
 434   color: #527bbd;
 435 }
 436 p.table {
 437   margin-top: 0;
 438 }
 439 /* Because the table frame attribute is overridden by CSS in most browsers. */
 440 div.tableblock > table[frame="void"] {
 441   border-style: none;
 442 }
 443 div.tableblock > table[frame="hsides"] {
 444   border-left-style: none;
 445   border-right-style: none;
 446 }
 447 div.tableblock > table[frame="vsides"] {
 448   border-top-style: none;
 449   border-bottom-style: none;
 450 }
 451
 452
 453 /*
 454  * html5 specific
 455  *
 456  * */
 457
 458 table.tableblock {
 459   margin-top: 1.0em;
 460   margin-bottom: 1.5em;
 461 }
 462 thead, p.tableblock.header {
 463   font-weight: bold;
 464   color: #527bbd;
 465 }
 466 p.tableblock {
 467   margin-top: 0;
 468 }
 469 table.tableblock {
 470   border-width: 3px;
 471   border-spacing: 0px;
 472   border-style: solid;
 473   border-color: #527bbd;
 474   border-collapse: collapse;
 475 }
 476 th.tableblock, td.tableblock {
 477   border-width: 1px;
 478   padding: 4px;
 479   border-style: solid;
 480   border-color: #527bbd;
 481 }
 482
 483 table.tableblock.frame-topbot {
 484   border-left-style: hidden;
 485   border-right-style: hidden;
 486 }
 487 table.tableblock.frame-sides {
 488   border-top-style: hidden;
 489   border-bottom-style: hidden;
 490 }
 491 table.tableblock.frame-none {
 492   border-style: hidden;
 493 }
 494
 495 th.tableblock.halign-left, td.tableblock.halign-left {
 496   text-align: left;
 497 }
 498 th.tableblock.halign-center, td.tableblock.halign-center {
 499   text-align: center;
 500 }
 501 th.tableblock.halign-right, td.tableblock.halign-right {
 502   text-align: right;
 503 }
 504
 505 th.tableblock.valign-top, td.tableblock.valign-top {
 506   vertical-align: top;
 507 }
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {
 509   vertical-align: middle;
 510 }
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 512   vertical-align: bottom;
 513 }
 514
 515
 516 /*
 517  * manpage specific
 518  *
 519  * */
 520
 521 body.manpage h1 {
 522   padding-top: 0.5em;
 523   padding-bottom: 0.5em;
 524   border-top: 2px solid silver;
 525   border-bottom: 2px solid silver;
 526 }
 527 body.manpage h2 {
 528   border-style: none;
 529 }
 530 body.manpage div.sectionbody {
 531   margin-left: 3em;
 532 }
 533
 534 @media print {
 535   body.manpage div#toc { display: none; }
 536 }
 537
 538
 539 </style>
 540 <script type="text/javascript">
 541 /*<![CDATA[*/
 542 var asciidoc = {  // Namespace.
 543
 544 /////////////////////////////////////////////////////////////////////
 545 // Table Of Contents generator
 546 /////////////////////////////////////////////////////////////////////
 547
 548 /* Author: Mihai Bazon, September 2002
 549  * http://students.infoiasi.ro/~mishoo
 550  *
 551  * Table Of Content generator
 552  * Version: 0.4
 553  *
 554  * Feel free to use this script under the terms of the GNU General Public
 555  * License, as long as you do not remove or alter this notice.
 556  */
 557
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 560
 561 // toclevels = 1..4.
 562 toc: function (toclevels) {
 563
 564   function getText(el) {
 565     var text = "";
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 568         text += i.data;
 569       else if (i.firstChild != null)
 570         text += getText(i);
 571     }
 572     return text;
 573   }
 574
 575   function TocEntry(el, text, toclevel) {
 576     this.element = el;
 577     this.text = text;
 578     this.toclevel = toclevel;
 579   }
 580
 581   function tocEntries(el, toclevels) {
 582     var result = new Array;
 583     var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
 584     // Function that scans the DOM tree for header elements (the DOM2
 585     // nodeIterator API would be a better technique but not supported by all
 586     // browsers).
 587     var iterate = function (el) {
 588       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 589         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 590           var mo = re.exec(i.tagName);
 591           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 592             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 593           }
 594           iterate(i);
 595         }
 596       }
 597     }
 598     iterate(el);
 599     return result;
 600   }
 601
 602   var toc = document.getElementById("toc");
 603   if (!toc) {
 604     return;
 605   }
 606
 607   // Delete existing TOC entries in case we're reloading the TOC.
 608   var tocEntriesToRemove = [];
 609   var i;
 610   for (i = 0; i < toc.childNodes.length; i++) {
 611     var entry = toc.childNodes[i];
 612     if (entry.nodeName.toLowerCase() == 'div'
 613      && entry.getAttribute("class")
 614      && entry.getAttribute("class").match(/^toclevel/))
 615       tocEntriesToRemove.push(entry);
 616   }
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {
 618     toc.removeChild(tocEntriesToRemove[i]);
 619   }
 620
 621   // Rebuild TOC entries.
 622   var entries = tocEntries(document.getElementById("content"), toclevels);
 623   for (var i = 0; i < entries.length; ++i) {
 624     var entry = entries[i];
 625     if (entry.element.id == "")
 626       entry.element.id = "_toc_" + i;
 627     var a = document.createElement("a");
 628     a.href = "#" + entry.element.id;
 629     a.appendChild(document.createTextNode(entry.text));
 630     var div = document.createElement("div");
 631     div.appendChild(a);
 632     div.className = "toclevel" + entry.toclevel;
 633     toc.appendChild(div);
 634   }
 635   if (entries.length == 0)
 636     toc.parentNode.removeChild(toc);
 637 },
 638
 639
 640 /////////////////////////////////////////////////////////////////////
 641 // Footnotes generator
 642 /////////////////////////////////////////////////////////////////////
 643
 644 /* Based on footnote generation code from:
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 646  */
 647
 648 footnotes: function () {
 649   // Delete existing footnote entries in case we're reloading the footnodes.
 650   var i;
 651   var noteholder = document.getElementById("footnotes");
 652   if (!noteholder) {
 653     return;
 654   }
 655   var entriesToRemove = [];
 656   for (i = 0; i < noteholder.childNodes.length; i++) {
 657     var entry = noteholder.childNodes[i];
 658     if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
 659       entriesToRemove.push(entry);
 660   }
 661   for (i = 0; i < entriesToRemove.length; i++) {
 662     noteholder.removeChild(entriesToRemove[i]);
 663   }
 664
 665   // Rebuild footnote entries.
 666   var cont = document.getElementById("content");
 667   var spans = cont.getElementsByTagName("span");
 668   var refs = {};
 669   var n = 0;
 670   for (i=0; i<spans.length; i++) {
 671     if (spans[i].className == "footnote") {
 672       n++;
 673       var note = spans[i].getAttribute("data-note");
 674       if (!note) {
 675         // Use [\s\S] in place of . so multi-line matches work.
 676         // Because JavaScript has no s (dotall) regex flag.
 677         note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 678         spans[i].innerHTML =
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";
 681         spans[i].setAttribute("data-note", note);
 682       }
 683       noteholder.innerHTML +=
 684         "<div class='footnote' id='_footnote_" + n + "'>" +
 685         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 686         n + "</a>. " + note + "</div>";
 687       var id =spans[i].getAttribute("id");
 688       if (id != null) refs["#"+id] = n;
 689     }
 690   }
 691   if (n == 0)
 692     noteholder.parentNode.removeChild(noteholder);
 693   else {
 694     // Process footnoterefs.
 695     for (i=0; i<spans.length; i++) {
 696       if (spans[i].className == "footnoteref") {
 697         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 698         href = href.match(/#.*/)[0];  // Because IE return full URL.
 699         n = refs[href];
 700         spans[i].innerHTML =
 701           "[<a href='#_footnote_" + n +
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";
 703       }
 704     }
 705   }
 706 },
 707
 708 install: function(toclevels) {
 709   var timerId;
 710
 711   function reinstall() {
 712     asciidoc.footnotes();
 713     if (toclevels) {
 714       asciidoc.toc(toclevels);
 715     }
 716   }
 717
 718   function reinstallAndRemoveTimer() {
 719     clearInterval(timerId);
 720     reinstall();
 721   }
 722
 723   timerId = setInterval(reinstall, 500);
 724   if (document.addEventListener)
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
 726   else
 727     window.onload = reinstallAndRemoveTimer;
 728 }
 729
 730 }
 731 asciidoc.install();
 732 /*]]>*/
 733 </script>
 734 </head>
 735 <body class="manpage">
 736 <div id="header">
 737 <h1>
 738 git-format-patch(1) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>git-format-patch -
 743    Prepare patches for e-mail submission
 744 </p>
 745 </div>
 746 </div>
 747 <div id="content">
 748 <div class="sect1">
 749 <h2 id="_synopsis">SYNOPSIS</h2>
 750 <div class="sectionbody">
 751 <div class="verseblock">
 752 <pre class="content"><em>git format-patch</em> [-k] [(-o|--output-directory) &lt;dir&gt; | --stdout]
 753                    [--no-thread | --thread[=&lt;style&gt;]]
 754                    [(--attach|--inline)[=&lt;boundary&gt;] | --no-attach]
 755                    [-s | --signoff]
 756                    [--signature=&lt;signature&gt; | --no-signature]
 757                    [--signature-file=&lt;file&gt;]
 758                    [-n | --numbered | -N | --no-numbered]
 759                    [--start-number &lt;n&gt;] [--numbered-files]
 760                    [--in-reply-to=&lt;message-id&gt;] [--suffix=.&lt;sfx&gt;]
 761                    [--ignore-if-in-upstream] [--always]
 762                    [--cover-from-description=&lt;mode&gt;]
 763                    [--rfc] [--subject-prefix=&lt;subject-prefix&gt;]
 764                    [(--reroll-count|-v) &lt;n&gt;]
 765                    [--to=&lt;email&gt;] [--cc=&lt;email&gt;]
 766                    [--[no-]cover-letter] [--quiet]
 767                    [--[no-]encode-email-headers]
 768                    [--no-notes | --notes[=&lt;ref&gt;]]
 769                    [--interdiff=&lt;previous&gt;]
 770                    [--range-diff=&lt;previous&gt; [--creation-factor=&lt;percent&gt;]]
 771                    [--filename-max-length=&lt;n&gt;]
 772                    [--progress]
 773                    [&lt;common-diff-options&gt;]
 774                    [ &lt;since&gt; | &lt;revision-range&gt; ]</pre>
 775 <div class="attribution">
 776 </div></div>
 777 </div>
 778 </div>
 779 <div class="sect1">
 780 <h2 id="_description">DESCRIPTION</h2>
 781 <div class="sectionbody">
 782 <div class="paragraph"><p>Prepare each non-merge commit with its "patch" in
 783 one "message" per commit, formatted to resemble a UNIX mailbox.
 784 The output of this command is convenient for e-mail submission or
 785 for use with <em>git am</em>.</p></div>
 786 <div class="paragraph"><p>A "message" generated by the command consists of three parts:</p></div>
 787 <div class="ulist"><ul>
 788 <li>
 789 <p>
 790 A brief metadata header that begins with <code>From &lt;commit&gt;</code>
 791   with a fixed <code>Mon Sep 17 00:00:00 2001</code> datestamp to help programs
 792   like "file(1)" to recognize that the file is an output from this
 793   command, fields that record the author identity, the author date,
 794   and the title of the change (taken from the first paragraph of the
 795   commit log message).
 796 </p>
 797 </li>
 798 <li>
 799 <p>
 800 The second and subsequent paragraphs of the commit log message.
 801 </p>
 802 </li>
 803 <li>
 804 <p>
 805 The "patch", which is the "diff -p --stat" output (see
 806   <a href="git-diff.html">git-diff(1)</a>) between the commit and its parent.
 807 </p>
 808 </li>
 809 </ul></div>
 810 <div class="paragraph"><p>The log message and the patch 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
1876 </dt>
1877 <dd>
1878 <p>
1879         Prepends "RFC" to the subject prefix (producing "RFC PATCH" by
1880         default). RFC means "Request For Comments"; use this when sending
1881         an experimental patch for discussion rather than application.
1882 </p>
1883 </dd>
1884 <dt class="hdlist1">
1885 -v &lt;n&gt;
1886 </dt>
1887 <dt class="hdlist1">
1888 --reroll-count=&lt;n&gt;
1889 </dt>
1890 <dd>
1891 <p>
1892         Mark the series as the &lt;n&gt;-th iteration of the topic. The
1893         output filenames have <code>v&lt;n&gt;</code> prepended to them, and the
1894         subject prefix ("PATCH" by default, but configurable via the
1895         <code>--subject-prefix</code> option) has ` v&lt;n&gt;` appended to it.  E.g.
1896         <code>--reroll-count=4</code> may produce <code>v4-0001-add-makefile.patch</code>
1897         file that has "Subject: [PATCH v4 1/20] Add makefile" in it.
1898         <code>&lt;n&gt;</code> does not have to be an integer (e.g. "--reroll-count=4.4",
1899         or "--reroll-count=4rev2" are allowed), but the downside of
1900         using such a reroll-count is that the range-diff/interdiff
1901         with the previous version does not state exactly which
1902         version the new iteration is compared against.
1903 </p>
1904 </dd>
1905 <dt class="hdlist1">
1906 --to=&lt;email&gt;
1907 </dt>
1908 <dd>
1909 <p>
1910         Add a <code>To:</code> header to the email headers. This is in addition
1911         to any configured headers, and may be used multiple times.
1912         The negated form <code>--no-to</code> discards all <code>To:</code> headers added so
1913         far (from config or command line).
1914 </p>
1915 </dd>
1916 <dt class="hdlist1">
1917 --cc=&lt;email&gt;
1918 </dt>
1919 <dd>
1920 <p>
1921         Add a <code>Cc:</code> header to the email headers. This is in addition
1922         to any configured headers, and may be used multiple times.
1923         The negated form <code>--no-cc</code> discards all <code>Cc:</code> headers added so
1924         far (from config or command line).
1925 </p>
1926 </dd>
1927 <dt class="hdlist1">
1928 --from
1929 </dt>
1930 <dt class="hdlist1">
1931 --from=&lt;ident&gt;
1932 </dt>
1933 <dd>
1934 <p>
1935         Use <code>ident</code> in the <code>From:</code> header of each commit email. If the
1936         author ident of the commit is not textually identical to the
1937         provided <code>ident</code>, place a <code>From:</code> header in the body of the
1938         message with the original author. If no <code>ident</code> is given, use
1939         the committer ident.
1940 </p>
1941 <div class="paragraph"><p>Note that this option is only useful if you are actually sending the
1942 emails and want to identify yourself as the sender, but retain the
1943 original author (and <code>git am</code> will correctly pick up the in-body
1944 header). Note also that <code>git send-email</code> already handles this
1945 transformation for you, and this option should not be used if you are
1946 feeding the result to <code>git send-email</code>.</p></div>
1947 </dd>
1948 <dt class="hdlist1">
1949 --[no-]force-in-body-from
1950 </dt>
1951 <dd>
1952 <p>
1953         With the e-mail sender specified via the <code>--from</code> option, by
1954         default, an in-body "From:" to identify the real author of
1955         the commit is added at the top of the commit log message if
1956         the sender is different from the author.  With this option,
1957         the in-body "From:" is added even when the sender and the
1958         author have the same name and address, which may help if the
1959         mailing list software mangles the sender&#8217;s identity.
1960         Defaults to the value of the <code>format.forceInBodyFrom</code>
1961         configuration variable.
1962 </p>
1963 </dd>
1964 <dt class="hdlist1">
1965 --add-header=&lt;header&gt;
1966 </dt>
1967 <dd>
1968 <p>
1969         Add an arbitrary header to the email headers.  This is in addition
1970         to any configured headers, and may be used multiple times.
1971         For example, <code>--add-header="Organization: git-foo"</code>.
1972         The negated form <code>--no-add-header</code> discards <strong>all</strong> (<code>To:</code>,
1973         <code>Cc:</code>, and custom) headers added so far from config or command
1974         line.
1975 </p>
1976 </dd>
1977 <dt class="hdlist1">
1978 --[no-]cover-letter
1979 </dt>
1980 <dd>
1981 <p>
1982         In addition to the patches, generate a cover letter file
1983         containing the branch description, shortlog and the overall diffstat.  You can
1984         fill in a description in the file before sending it out.
1985 </p>
1986 </dd>
1987 <dt class="hdlist1">
1988 --encode-email-headers
1989 </dt>
1990 <dt class="hdlist1">
1991 --no-encode-email-headers
1992 </dt>
1993 <dd>
1994 <p>
1995         Encode email headers that have non-ASCII characters with
1996         "Q-encoding" (described in RFC 2047), instead of outputting the
1997         headers verbatim. Defaults to the value of the
1998         <code>format.encodeEmailHeaders</code> configuration variable.
1999 </p>
2000 </dd>
2001 <dt class="hdlist1">
2002 --interdiff=&lt;previous&gt;
2003 </dt>
2004 <dd>
2005 <p>
2006         As a reviewer aid, insert an interdiff into the cover letter,
2007         or as commentary of the lone patch of a 1-patch series, showing
2008         the differences between the previous version of the patch series and
2009         the series currently being formatted. <code>previous</code> is a single revision
2010         naming the tip of the previous series which shares a common base with
2011         the series being formatted (for example <code>git format-patch
2012         --cover-letter --interdiff=feature/v1 -3 feature/v2</code>).
2013 </p>
2014 </dd>
2015 <dt class="hdlist1">
2016 --range-diff=&lt;previous&gt;
2017 </dt>
2018 <dd>
2019 <p>
2020         As a reviewer aid, insert a range-diff (see <a href="git-range-diff.html">git-range-diff(1)</a>)
2021         into the cover letter, or as commentary of the lone patch of a
2022         1-patch series, showing the differences between the previous
2023         version of the patch series and the series currently being formatted.
2024         <code>previous</code> can be a single revision naming the tip of the previous
2025         series if it shares a common base with the series being formatted (for
2026         example <code>git format-patch --cover-letter --range-diff=feature/v1 -3
2027         feature/v2</code>), or a revision range if the two versions of the series are
2028         disjoint (for example <code>git format-patch --cover-letter
2029         --range-diff=feature/v1~3..feature/v1 -3 feature/v2</code>).
2030 </p>
2031 <div class="paragraph"><p>Note that diff options passed to the command affect how the primary
2032 product of <code>format-patch</code> is generated, and they are not passed to
2033 the underlying <code>range-diff</code> machinery used to generate the cover-letter
2034 material (this may change in the future).</p></div>
2035 </dd>
2036 <dt class="hdlist1">
2037 --creation-factor=&lt;percent&gt;
2038 </dt>
2039 <dd>
2040 <p>
2041         Used with <code>--range-diff</code>, tweak the heuristic which matches up commits
2042         between the previous and current series of patches by adjusting the
2043         creation/deletion cost fudge factor. See <a href="git-range-diff.html">git-range-diff(1)</a>)
2044         for details.
2045 </p>
2046 </dd>
2047 <dt class="hdlist1">
2048 --notes[=&lt;ref&gt;]
2049 </dt>
2050 <dt class="hdlist1">
2051 --no-notes
2052 </dt>
2053 <dd>
2054 <p>
2055         Append the notes (see <a href="git-notes.html">git-notes(1)</a>) for the commit
2056         after the three-dash line.
2057 </p>
2058 <div class="paragraph"><p>The expected use case of this is to write supporting explanation for
2059 the commit that does not belong to the commit log message proper,
2060 and include it with the patch submission. While one can simply write
2061 these explanations after <code>format-patch</code> has run but before sending,
2062 keeping them as Git notes allows them to be maintained between versions
2063 of the patch series (but see the discussion of the <code>notes.rewrite</code>
2064 configuration options in <a href="git-notes.html">git-notes(1)</a> to use this workflow).</p></div>
2065 <div class="paragraph"><p>The default is <code>--no-notes</code>, unless the <code>format.notes</code> configuration is
2066 set.</p></div>
2067 </dd>
2068 <dt class="hdlist1">
2069 --[no-]signature=&lt;signature&gt;
2070 </dt>
2071 <dd>
2072 <p>
2073         Add a signature to each message produced. Per RFC 3676 the signature
2074         is separated from the body by a line with '-- ' on it. If the
2075         signature option is omitted the signature defaults to the Git version
2076         number.
2077 </p>
2078 </dd>
2079 <dt class="hdlist1">
2080 --signature-file=&lt;file&gt;
2081 </dt>
2082 <dd>
2083 <p>
2084         Works just like --signature except the signature is read from a file.
2085 </p>
2086 </dd>
2087 <dt class="hdlist1">
2088 --suffix=.&lt;sfx&gt;
2089 </dt>
2090 <dd>
2091 <p>
2092         Instead of using <code>.patch</code> as the suffix for generated
2093         filenames, use specified suffix.  A common alternative is
2094         <code>--suffix=.txt</code>.  Leaving this empty will remove the <code>.patch</code>
2095         suffix.
2096 </p>
2097 <div class="paragraph"><p>Note that the leading character does not have to be a dot; for example,
2098 you can use <code>--suffix=-patch</code> to get <code>0001-description-of-my-change-patch</code>.</p></div>
2099 </dd>
2100 <dt class="hdlist1">
2101 -q
2102 </dt>
2103 <dt class="hdlist1">
2104 --quiet
2105 </dt>
2106 <dd>
2107 <p>
2108         Do not print the names of the generated files to standard output.
2109 </p>
2110 </dd>
2111 <dt class="hdlist1">
2112 --no-binary
2113 </dt>
2114 <dd>
2115 <p>
2116         Do not output contents of changes in binary files, instead
2117         display a notice that those files changed.  Patches generated
2118         using this option cannot be applied properly, but they are
2119         still useful for code review.
2120 </p>
2121 </dd>
2122 <dt class="hdlist1">
2123 --zero-commit
2124 </dt>
2125 <dd>
2126 <p>
2127   Output an all-zero hash in each patch&#8217;s From header instead
2128   of the hash of the commit.
2129 </p>
2130 </dd>
2131 <dt class="hdlist1">
2132 --[no-]base[=&lt;commit&gt;]
2133 </dt>
2134 <dd>
2135 <p>
2136         Record the base tree information to identify the state the
2137         patch series applies to.  See the BASE TREE INFORMATION section
2138         below for details. If &lt;commit&gt; is "auto", a base commit is
2139         automatically chosen. The <code>--no-base</code> option overrides a
2140         <code>format.useAutoBase</code> configuration.
2141 </p>
2142 </dd>
2143 <dt class="hdlist1">
2144 --root
2145 </dt>
2146 <dd>
2147 <p>
2148         Treat the revision argument as a &lt;revision-range&gt;, even if it
2149         is just a single commit (that would normally be treated as a
2150         &lt;since&gt;).  Note that root commits included in the specified
2151         range are always formatted as creation patches, independently
2152         of this flag.
2153 </p>
2154 </dd>
2155 <dt class="hdlist1">
2156 --progress
2157 </dt>
2158 <dd>
2159 <p>
2160         Show progress reports on stderr as patches are generated.
2161 </p>
2162 </dd>
2163 </dl></div>
2164 </div>
2165 </div>
2166 <div class="sect1">
2167 <h2 id="_configuration">CONFIGURATION</h2>
2168 <div class="sectionbody">
2169 <div class="paragraph"><p>You can specify extra mail header lines to be added to each message,
2170 defaults for the subject prefix and file suffix, number patches when
2171 outputting more than one patch, add "To:" or "Cc:" headers, configure
2172 attachments, change the patch output directory, and sign off patches
2173 with configuration variables.</p></div>
2174 <div class="listingblock">
2175 <div class="content">
2176 <pre><code>[format]
2177         headers = "Organization: git-foo\n"
2178         subjectPrefix = CHANGE
2179         suffix = .txt
2180         numbered = auto
2181         to = &lt;email&gt;
2182         cc = &lt;email&gt;
2183         attach [ = mime-boundary-string ]
2184         signOff = true
2185         outputDirectory = &lt;directory&gt;
2186         coverLetter = auto
2187         coverFromDescription = auto</code></pre>
2188 </div></div>
2189 </div>
2190 </div>
2191 <div class="sect1">
2192 <h2 id="_discussion">DISCUSSION</h2>
2193 <div class="sectionbody">
2194 <div class="paragraph"><p>The patch produced by <em>git format-patch</em> is in UNIX mailbox format,
2195 with a fixed "magic" time stamp to indicate that the file is output
2196 from format-patch rather than a real mailbox, like so:</p></div>
2197 <div class="listingblock">
2198 <div class="content">
2199 <pre><code>From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
2200 From: Tony Luck &lt;tony.luck@intel.com&gt;
2201 Date: Tue, 13 Jul 2010 11:42:54 -0700
2202 Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
2203  =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
2204 MIME-Version: 1.0
2205 Content-Type: text/plain; charset=UTF-8
2206 Content-Transfer-Encoding: 8bit
2207
2208 arch/arm config files were slimmed down using a python script
2209 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
2210
2211 Do the same for ia64 so we can have sleek &amp; trim looking
2212 ...</code></pre>
2213 </div></div>
2214 <div class="paragraph"><p>Typically it will be placed in a MUA&#8217;s drafts folder, edited to add
2215 timely commentary that should not go in the changelog after the three
2216 dashes, and then sent as a message whose body, in our example, starts
2217 with "arch/arm config files were&#8230;".  On the receiving end, readers
2218 can save interesting patches in a UNIX mailbox and apply them with
2219 <a href="git-am.html">git-am(1)</a>.</p></div>
2220 <div class="paragraph"><p>When a patch is part of an ongoing discussion, the patch generated by
2221 <em>git format-patch</em> can be tweaked to take advantage of the <em>git am
2222 --scissors</em> feature.  After your response to the discussion comes a
2223 line that consists solely of "<code>-- &gt;8 --</code>" (scissors and perforation),
2224 followed by the patch with unnecessary header fields removed:</p></div>
2225 <div class="listingblock">
2226 <div class="content">
2227 <pre><code>...
2228 &gt; So we should do such-and-such.
2229
2230 Makes sense to me.  How about this patch?
2231
2232 -- &gt;8 --
2233 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
2234
2235 arch/arm config files were slimmed down using a python script
2236 ...</code></pre>
2237 </div></div>
2238 <div class="paragraph"><p>When sending a patch this way, most often you are sending your own
2239 patch, so in addition to the "<code>From $SHA1 $magic_timestamp</code>" marker you
2240 should omit <code>From:</code> and <code>Date:</code> lines from the patch file.  The patch
2241 title is likely to be different from the subject of the discussion the
2242 patch is in response to, so it is likely that you would want to keep
2243 the Subject: line, like the example above.</p></div>
2244 <div class="sect2">
2245 <h3 id="_checking_for_patch_corruption">Checking for patch corruption</h3>
2246 <div class="paragraph"><p>Many mailers if not set up properly will corrupt whitespace.  Here are
2247 two common types of corruption:</p></div>
2248 <div class="ulist"><ul>
2249 <li>
2250 <p>
2251 Empty context lines that do not have <em>any</em> whitespace.
2252 </p>
2253 </li>
2254 <li>
2255 <p>
2256 Non-empty context lines that have one extra whitespace at the
2257   beginning.
2258 </p>
2259 </li>
2260 </ul></div>
2261 <div class="paragraph"><p>One way to test if your MUA is set up correctly is:</p></div>
2262 <div class="ulist"><ul>
2263 <li>
2264 <p>
2265 Send the patch to yourself, exactly the way you would, except
2266   with To: and Cc: lines that do not contain the list and
2267   maintainer address.
2268 </p>
2269 </li>
2270 <li>
2271 <p>
2272 Save that patch to a file in UNIX mailbox format.  Call it a.patch,
2273   say.
2274 </p>
2275 </li>
2276 <li>
2277 <p>
2278 Apply it:
2279 </p>
2280 <div class="literalblock">
2281 <div class="content">
2282 <pre><code>$ git fetch &lt;project&gt; master:test-apply
2283 $ git switch test-apply
2284 $ git restore --source=HEAD --staged --worktree :/
2285 $ git am a.patch</code></pre>
2286 </div></div>
2287 </li>
2288 </ul></div>
2289 <div class="paragraph"><p>If it does not apply correctly, there can be various reasons.</p></div>
2290 <div class="ulist"><ul>
2291 <li>
2292 <p>
2293 The patch itself does not apply cleanly.  That is <em>bad</em> but
2294   does not have much to do with your MUA.  You might want to rebase
2295   the patch with <a href="git-rebase.html">git-rebase(1)</a> before regenerating it in
2296   this case.
2297 </p>
2298 </li>
2299 <li>
2300 <p>
2301 The MUA corrupted your patch; "am" would complain that
2302   the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and
2303   see what <em>patch</em> file contains and check for the common
2304   corruption patterns mentioned above.
2305 </p>
2306 </li>
2307 <li>
2308 <p>
2309 While at it, check the <em>info</em> and <em>final-commit</em> files as well.
2310   If what is in <em>final-commit</em> is not exactly what you would want to
2311   see in the commit log message, it is very likely that the
2312   receiver would end up hand editing the log message when applying
2313   your patch.  Things like "Hi, this is my first patch.\n" in the
2314   patch e-mail should come after the three-dash line that signals
2315   the end of the commit message.
2316 </p>
2317 </li>
2318 </ul></div>
2319 </div>
2320 </div>
2321 </div>
2322 <div class="sect1">
2323 <h2 id="_mua_specific_hints">MUA-SPECIFIC HINTS</h2>
2324 <div class="sectionbody">
2325 <div class="paragraph"><p>Here are some hints on how to successfully submit patches inline using
2326 various mailers.</p></div>
2327 <div class="sect2">
2328 <h3 id="_gmail">GMail</h3>
2329 <div class="paragraph"><p>GMail does not have any way to turn off line wrapping in the web
2330 interface, so it will mangle any emails that you send.  You can however
2331 use "git send-email" and send your patches through the GMail SMTP server, or
2332 use any IMAP email client to connect to the google IMAP server and forward
2333 the emails through that.</p></div>
2334 <div class="paragraph"><p>For hints on using <em>git send-email</em> to send your patches through the
2335 GMail SMTP server, see the EXAMPLE section of <a href="git-send-email.html">git-send-email(1)</a>.</p></div>
2336 <div class="paragraph"><p>For hints on submission using the IMAP interface, see the EXAMPLE
2337 section of <a href="git-imap-send.html">git-imap-send(1)</a>.</p></div>
2338 </div>
2339 <div class="sect2">
2340 <h3 id="_thunderbird">Thunderbird</h3>
2341 <div class="paragraph"><p>By default, Thunderbird will both wrap emails as well as flag
2342 them as being <em>format=flowed</em>, both of which will make the
2343 resulting email unusable by Git.</p></div>
2344 <div class="paragraph"><p>There are three different approaches: use an add-on to turn off line wraps,
2345 configure Thunderbird to not mangle patches, or use
2346 an external editor to keep Thunderbird from mangling the patches.</p></div>
2347 <div class="sect3">
2348 <h4 id="_approach_1_add_on">Approach #1 (add-on)</h4>
2349 <div class="paragraph"><p>Install the Toggle Word Wrap add-on that is available from
2350 <a href="https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/">https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/</a>
2351 It adds a menu entry "Enable Word Wrap" in the composer&#8217;s "Options" menu
2352 that you can tick off. Now you can compose the message as you otherwise do
2353 (cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc), but you have to
2354 insert line breaks manually in any text that you type.</p></div>
2355 </div>
2356 <div class="sect3">
2357 <h4 id="_approach_2_configuration">Approach #2 (configuration)</h4>
2358 <div class="paragraph"><p>Three steps:</p></div>
2359 <div class="olist arabic"><ol class="arabic">
2360 <li>
2361 <p>
2362 Configure your mail server composition as plain text:
2363    Edit&#8230;Account Settings&#8230;Composition &amp; Addressing,
2364    uncheck "Compose Messages in HTML".
2365 </p>
2366 </li>
2367 <li>
2368 <p>
2369 Configure your general composition window to not wrap.
2370 </p>
2371 <div class="paragraph"><p>In Thunderbird 2:
2372 Edit..Preferences..Composition, wrap plain text messages at 0</p></div>
2373 <div class="paragraph"><p>In Thunderbird 3:
2374 Edit..Preferences..Advanced..Config Editor.  Search for
2375 "mail.wrap_long_lines".
2376 Toggle it to make sure it is set to <code>false</code>. Also, search for
2377 "mailnews.wraplength" and set the value to 0.</p></div>
2378 </li>
2379 <li>
2380 <p>
2381 Disable the use of format=flowed:
2382    Edit..Preferences..Advanced..Config Editor.  Search for
2383    "mailnews.send_plaintext_flowed".
2384    Toggle it to make sure it is set to <code>false</code>.
2385 </p>
2386 </li>
2387 </ol></div>
2388 <div class="paragraph"><p>After that is done, you should be able to compose email as you
2389 otherwise would (cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc),
2390 and the patches will not be mangled.</p></div>
2391 </div>
2392 <div class="sect3">
2393 <h4 id="_approach_3_external_editor">Approach #3 (external editor)</h4>
2394 <div class="paragraph"><p>The following Thunderbird extensions are needed:
2395 AboutConfig from <a href="https://mjg.github.io/AboutConfig/">https://mjg.github.io/AboutConfig/</a> and
2396 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>
2397 <div class="olist arabic"><ol class="arabic">
2398 <li>
2399 <p>
2400 Prepare the patch as a text file using your method of choice.
2401 </p>
2402 </li>
2403 <li>
2404 <p>
2405 Before opening a compose window, use Edit&#8594;Account Settings to
2406    uncheck the "Compose messages in HTML format" setting in the
2407    "Composition &amp; Addressing" panel of the account to be used to
2408    send the patch.
2409 </p>
2410 </li>
2411 <li>
2412 <p>
2413 In the main Thunderbird window, <em>before</em> you open the compose
2414    window for the patch, use Tools&#8594;about:config to set the
2415    following to the indicated values:
2416 </p>
2417 <div class="listingblock">
2418 <div class="content">
2419 <pre><code>        mailnews.send_plaintext_flowed  =&gt; false
2420         mailnews.wraplength             =&gt; 0</code></pre>
2421 </div></div>
2422 </li>
2423 <li>
2424 <p>
2425 Open a compose window and click the external editor icon.
2426 </p>
2427 </li>
2428 <li>
2429 <p>
2430 In the external editor window, read in the patch file and exit
2431    the editor normally.
2432 </p>
2433 </li>
2434 </ol></div>
2435 <div class="paragraph"><p>Side note: it may be possible to do step 2 with
2436 about:config and the following settings but no one&#8217;s tried yet.</p></div>
2437 <div class="listingblock">
2438 <div class="content">
2439 <pre><code>        mail.html_compose                       =&gt; false
2440         mail.identity.default.compose_html      =&gt; false
2441         mail.identity.id?.compose_html          =&gt; false</code></pre>
2442 </div></div>
2443 <div class="paragraph"><p>There is a script in contrib/thunderbird-patch-inline which can help
2444 you include patches with Thunderbird in an easy way. To use it, do the
2445 steps above and then use the script as the external editor.</p></div>
2446 </div>
2447 </div>
2448 <div class="sect2">
2449 <h3 id="_kmail">KMail</h3>
2450 <div class="paragraph"><p>This should help you to submit patches inline using KMail.</p></div>
2451 <div class="olist arabic"><ol class="arabic">
2452 <li>
2453 <p>
2454 Prepare the patch as a text file.
2455 </p>
2456 </li>
2457 <li>
2458 <p>
2459 Click on New Mail.
2460 </p>
2461 </li>
2462 <li>
2463 <p>
2464 Go under "Options" in the Composer window and be sure that
2465    "Word wrap" is not set.
2466 </p>
2467 </li>
2468 <li>
2469 <p>
2470 Use Message &#8594; Insert file&#8230; and insert the patch.
2471 </p>
2472 </li>
2473 <li>
2474 <p>
2475 Back in the compose window: add whatever other text you wish to the
2476    message, complete the addressing and subject fields, and press send.
2477 </p>
2478 </li>
2479 </ol></div>
2480 </div>
2481 </div>
2482 </div>
2483 <div class="sect1">
2484 <h2 id="_base_tree_information">BASE TREE INFORMATION</h2>
2485 <div class="sectionbody">
2486 <div class="paragraph"><p>The base tree information block is used for maintainers or third party
2487 testers to know the exact state the patch series applies to. It consists
2488 of the <em>base commit</em>, which is a well-known commit that is part of the
2489 stable part of the project history everybody else works off of, and zero
2490 or more <em>prerequisite patches</em>, which are well-known patches in flight
2491 that is not yet part of the <em>base commit</em> that need to be applied on top
2492 of <em>base commit</em> in topological order before the patches can be applied.</p></div>
2493 <div class="paragraph"><p>The <em>base commit</em> is shown as "base-commit: " followed by the 40-hex of
2494 the commit object name.  A <em>prerequisite patch</em> is shown as
2495 "prerequisite-patch-id: " followed by the 40-hex <em>patch id</em>, which can
2496 be obtained by passing the patch through the <code>git patch-id --stable</code>
2497 command.</p></div>
2498 <div class="paragraph"><p>Imagine that on top of the public commit P, you applied well-known
2499 patches X, Y and Z from somebody else, and then built your three-patch
2500 series A, B, C, the history would be like:</p></div>
2501 <div class="literalblock">
2502 <div class="content">
2503 <pre><code>---P---X---Y---Z---A---B---C</code></pre>
2504 </div></div>
2505 <div class="paragraph"><p>With <code>git format-patch --base=P -3 C</code> (or variants thereof, e.g. with
2506 <code>--cover-letter</code> or using <code>Z..C</code> instead of <code>-3 C</code> to specify the
2507 range), the base tree information block is shown at the end of the
2508 first message the command outputs (either the first patch, or the
2509 cover letter), like this:</p></div>
2510 <div class="listingblock">
2511 <div class="content">
2512 <pre><code>base-commit: P
2513 prerequisite-patch-id: X
2514 prerequisite-patch-id: Y
2515 prerequisite-patch-id: Z</code></pre>
2516 </div></div>
2517 <div class="paragraph"><p>For non-linear topology, such as</p></div>
2518 <div class="literalblock">
2519 <div class="content">
2520 <pre><code>---P---X---A---M---C
2521     \         /
2522      Y---Z---B</code></pre>
2523 </div></div>
2524 <div class="paragraph"><p>You can also use <code>git format-patch --base=P -3 C</code> to generate patches
2525 for A, B and C, and the identifiers for P, X, Y, Z are appended at the
2526 end of the first message.</p></div>
2527 <div class="paragraph"><p>If set <code>--base=auto</code> in cmdline, it will automatically compute
2528 the base commit as the merge base of tip commit of the remote-tracking
2529 branch and revision-range specified in cmdline.
2530 For a local branch, you need to make it to track a remote branch by <code>git branch
2531 --set-upstream-to</code> before using this option.</p></div>
2532 </div>
2533 </div>
2534 <div class="sect1">
2535 <h2 id="_examples">EXAMPLES</h2>
2536 <div class="sectionbody">
2537 <div class="ulist"><ul>
2538 <li>
2539 <p>
2540 Extract commits between revisions R1 and R2, and apply them on top of
2541   the current branch using <em>git am</em> to cherry-pick them:
2542 </p>
2543 <div class="listingblock">
2544 <div class="content">
2545 <pre><code>$ git format-patch -k --stdout R1..R2 | git am -3 -k</code></pre>
2546 </div></div>
2547 </li>
2548 <li>
2549 <p>
2550 Extract all commits which are in the current branch but not in the
2551   origin branch:
2552 </p>
2553 <div class="listingblock">
2554 <div class="content">
2555 <pre><code>$ git format-patch origin</code></pre>
2556 </div></div>
2557 <div class="paragraph"><p>For each commit a separate file is created in the current directory.</p></div>
2558 </li>
2559 <li>
2560 <p>
2561 Extract all commits that lead to <em>origin</em> since the inception of the
2562   project:
2563 </p>
2564 <div class="listingblock">
2565 <div class="content">
2566 <pre><code>$ git format-patch --root origin</code></pre>
2567 </div></div>
2568 </li>
2569 <li>
2570 <p>
2571 The same as the previous one:
2572 </p>
2573 <div class="listingblock">
2574 <div class="content">
2575 <pre><code>$ git format-patch -M -B origin</code></pre>
2576 </div></div>
2577 <div class="paragraph"><p>Additionally, it detects and handles renames and complete rewrites
2578 intelligently to produce a renaming patch.  A renaming patch reduces
2579 the amount of text output, and generally makes it easier to review.
2580 Note that non-Git "patch" programs won&#8217;t understand renaming patches, so
2581 use it only when you know the recipient uses Git to apply your patch.</p></div>
2582 </li>
2583 <li>
2584 <p>
2585 Extract three topmost commits from the current branch and format them
2586   as e-mailable patches:
2587 </p>
2588 <div class="listingblock">
2589 <div class="content">
2590 <pre><code>$ git format-patch -3</code></pre>
2591 </div></div>
2592 </li>
2593 </ul></div>
2594 </div>
2595 </div>
2596 <div class="sect1">
2597 <h2 id="_caveats">CAVEATS</h2>
2598 <div class="sectionbody">
2599 <div class="paragraph"><p>Note that <code>format-patch</code> will omit merge commits from the output, even
2600 if they are part of the requested range. A simple "patch" does not
2601 include enough information for the receiving end to reproduce the same
2602 merge commit.</p></div>
2603 </div>
2604 </div>
2605 <div class="sect1">
2606 <h2 id="_see_also">SEE ALSO</h2>
2607 <div class="sectionbody">
2608 <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>
2609 </div>
2610 </div>
2611 <div class="sect1">
2612 <h2 id="_git">GIT</h2>
2613 <div class="sectionbody">
2614 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
2615 </div>
2616 </div>
2617 </div>
2618 <div id="footnotes"><hr /></div>
2619 <div id="footer">
2620 <div id="footer-text">
2621 Last updated
2622  2024-02-08 15:45:59 PST
2623 </div>
2624 </div>
2625 </body>
2626 </html>