git-format-patch.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.5.2" />
   7 <title>git-format-patch(1)</title>
   8 <style type="text/css">
   9 /* Debug borders */
  10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  11 /*
  12   border: 1px solid red;
  13 */
  14 }
  15
  16 body {
  17   margin: 1em 5% 1em 5%;
  18 }
  19
  20 a {
  21   color: blue;
  22   text-decoration: underline;
  23 }
  24 a:visited {
  25   color: fuchsia;
  26 }
  27
  28 em {
  29   font-style: italic;
  30   color: navy;
  31 }
  32
  33 strong {
  34   font-weight: bold;
  35   color: #083194;
  36 }
  37
  38 tt {
  39   color: navy;
  40 }
  41
  42 h1, h2, h3, h4, h5, h6 {
  43   color: #527bbd;
  44   font-family: sans-serif;
  45   margin-top: 1.2em;
  46   margin-bottom: 0.5em;
  47   line-height: 1.3;
  48 }
  49
  50 h1, h2, h3 {
  51   border-bottom: 2px solid silver;
  52 }
  53 h2 {
  54   padding-top: 0.5em;
  55 }
  56 h3 {
  57   float: left;
  58 }
  59 h3 + * {
  60   clear: left;
  61 }
  62
  63 div.sectionbody {
  64   font-family: serif;
  65   margin-left: 0;
  66 }
  67
  68 hr {
  69   border: 1px solid silver;
  70 }
  71
  72 p {
  73   margin-top: 0.5em;
  74   margin-bottom: 0.5em;
  75 }
  76
  77 ul, ol, li > p {
  78   margin-top: 0;
  79 }
  80
  81 pre {
  82   padding: 0;
  83   margin: 0;
  84 }
  85
  86 span#author {
  87   color: #527bbd;
  88   font-family: sans-serif;
  89   font-weight: bold;
  90   font-size: 1.1em;
  91 }
  92 span#email {
  93 }
  94 span#revnumber, span#revdate, span#revremark {
  95   font-family: sans-serif;
  96 }
  97
  98 div#footer {
  99   font-family: sans-serif;
 100   font-size: small;
 101   border-top: 2px solid silver;
 102   padding-top: 0.5em;
 103   margin-top: 4.0em;
 104 }
 105 div#footer-text {
 106   float: left;
 107   padding-bottom: 0.5em;
 108 }
 109 div#footer-badges {
 110   float: right;
 111   padding-bottom: 0.5em;
 112 }
 113
 114 div#preamble {
 115   margin-top: 1.5em;
 116   margin-bottom: 1.5em;
 117 }
 118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 120 div.admonitionblock {
 121   margin-top: 1.0em;
 122   margin-bottom: 1.5em;
 123 }
 124 div.admonitionblock {
 125   margin-top: 2.0em;
 126   margin-bottom: 2.0em;
 127   margin-right: 10%;
 128   color: #606060;
 129 }
 130
 131 div.content { /* Block element content. */
 132   padding: 0;
 133 }
 134
 135 /* Block element titles. */
 136 div.title, caption.title {
 137   color: #527bbd;
 138   font-family: sans-serif;
 139   font-weight: bold;
 140   text-align: left;
 141   margin-top: 1.0em;
 142   margin-bottom: 0.5em;
 143 }
 144 div.title + * {
 145   margin-top: 0;
 146 }
 147
 148 td div.title:first-child {
 149   margin-top: 0.0em;
 150 }
 151 div.content div.title:first-child {
 152   margin-top: 0.0em;
 153 }
 154 div.content + div.title {
 155   margin-top: 0.0em;
 156 }
 157
 158 div.sidebarblock > div.content {
 159   background: #ffffee;
 160   border: 1px solid silver;
 161   padding: 0.5em;
 162 }
 163
 164 div.listingblock > div.content {
 165   border: 1px solid silver;
 166   background: #f4f4f4;
 167   padding: 0.5em;
 168 }
 169
 170 div.quoteblock, div.verseblock {
 171   padding-left: 1.0em;
 172   margin-left: 1.0em;
 173   margin-right: 10%;
 174   border-left: 5px solid #dddddd;
 175   color: #777777;
 176 }
 177
 178 div.quoteblock > div.attribution {
 179   padding-top: 0.5em;
 180   text-align: right;
 181 }
 182
 183 div.verseblock > div.content {
 184   white-space: pre;
 185 }
 186 div.verseblock > div.attribution {
 187   padding-top: 0.75em;
 188   text-align: left;
 189 }
 190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 191 div.verseblock + div.attribution {
 192   text-align: left;
 193 }
 194
 195 div.admonitionblock .icon {
 196   vertical-align: top;
 197   font-size: 1.1em;
 198   font-weight: bold;
 199   text-decoration: underline;
 200   color: #527bbd;
 201   padding-right: 0.5em;
 202 }
 203 div.admonitionblock td.content {
 204   padding-left: 0.5em;
 205   border-left: 3px solid #dddddd;
 206 }
 207
 208 div.exampleblock > div.content {
 209   border-left: 3px solid #dddddd;
 210   padding-left: 0.5em;
 211 }
 212
 213 div.imageblock div.content { padding-left: 0; }
 214 span.image img { border-style: none; }
 215 a.image:visited { color: white; }
 216
 217 dl {
 218   margin-top: 0.8em;
 219   margin-bottom: 0.8em;
 220 }
 221 dt {
 222   margin-top: 0.5em;
 223   margin-bottom: 0;
 224   font-style: normal;
 225   color: navy;
 226 }
 227 dd > *:first-child {
 228   margin-top: 0.1em;
 229 }
 230
 231 ul, ol {
 232     list-style-position: outside;
 233 }
 234 ol.arabic {
 235   list-style-type: decimal;
 236 }
 237 ol.loweralpha {
 238   list-style-type: lower-alpha;
 239 }
 240 ol.upperalpha {
 241   list-style-type: upper-alpha;
 242 }
 243 ol.lowerroman {
 244   list-style-type: lower-roman;
 245 }
 246 ol.upperroman {
 247   list-style-type: upper-roman;
 248 }
 249
 250 div.compact ul, div.compact ol,
 251 div.compact p, div.compact p,
 252 div.compact div, div.compact div {
 253   margin-top: 0.1em;
 254   margin-bottom: 0.1em;
 255 }
 256
 257 div.tableblock > table {
 258   border: 3px solid #527bbd;
 259 }
 260 thead, p.table.header {
 261   font-family: sans-serif;
 262   font-weight: bold;
 263 }
 264 tfoot {
 265   font-weight: bold;
 266 }
 267 td > div.verse {
 268   white-space: pre;
 269 }
 270 p.table {
 271   margin-top: 0;
 272 }
 273 /* Because the table frame attribute is overriden by CSS in most browsers. */
 274 div.tableblock > table[frame="void"] {
 275   border-style: none;
 276 }
 277 div.tableblock > table[frame="hsides"] {
 278   border-left-style: none;
 279   border-right-style: none;
 280 }
 281 div.tableblock > table[frame="vsides"] {
 282   border-top-style: none;
 283   border-bottom-style: none;
 284 }
 285
 286
 287 div.hdlist {
 288   margin-top: 0.8em;
 289   margin-bottom: 0.8em;
 290 }
 291 div.hdlist tr {
 292   padding-bottom: 15px;
 293 }
 294 dt.hdlist1.strong, td.hdlist1.strong {
 295   font-weight: bold;
 296 }
 297 td.hdlist1 {
 298   vertical-align: top;
 299   font-style: normal;
 300   padding-right: 0.8em;
 301   color: navy;
 302 }
 303 td.hdlist2 {
 304   vertical-align: top;
 305 }
 306 div.hdlist.compact tr {
 307   margin: 0;
 308   padding-bottom: 0;
 309 }
 310
 311 .comment {
 312   background: yellow;
 313 }
 314
 315 .footnote, .footnoteref {
 316   font-size: 0.8em;
 317 }
 318
 319 span.footnote, span.footnoteref {
 320   vertical-align: super;
 321 }
 322
 323 #footnotes {
 324   margin: 20px 0 20px 0;
 325   padding: 7px 0 0 0;
 326 }
 327
 328 #footnotes div.footnote {
 329   margin: 0 0 5px 0;
 330 }
 331
 332 #footnotes hr {
 333   border: none;
 334   border-top: 1px solid silver;
 335   height: 1px;
 336   text-align: left;
 337   margin-left: 0;
 338   width: 20%;
 339   min-width: 100px;
 340 }
 341
 342
 343 @media print {
 344   div#footer-badges { display: none; }
 345 }
 346
 347 div#toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 div#toctitle {
 352   color: #527bbd;
 353   font-family: sans-serif;
 354   font-size: 1.1em;
 355   font-weight: bold;
 356   margin-top: 1.0em;
 357   margin-bottom: 0.1em;
 358 }
 359
 360 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 361   margin-top: 0;
 362   margin-bottom: 0;
 363 }
 364 div.toclevel2 {
 365   margin-left: 2em;
 366   font-size: 0.9em;
 367 }
 368 div.toclevel3 {
 369   margin-left: 4em;
 370   font-size: 0.9em;
 371 }
 372 div.toclevel4 {
 373   margin-left: 6em;
 374   font-size: 0.9em;
 375 }
 376 /* Overrides for manpage documents */
 377 h1 {
 378   padding-top: 0.5em;
 379   padding-bottom: 0.5em;
 380   border-top: 2px solid silver;
 381   border-bottom: 2px solid silver;
 382 }
 383 h2 {
 384   border-style: none;
 385 }
 386 div.sectionbody {
 387   margin-left: 5%;
 388 }
 389
 390 @media print {
 391   div#toc { display: none; }
 392 }
 393
 394 /* Workarounds for IE6's broken and incomplete CSS2. */
 395
 396 div.sidebar-content {
 397   background: #ffffee;
 398   border: 1px solid silver;
 399   padding: 0.5em;
 400 }
 401 div.sidebar-title, div.image-title {
 402   color: #527bbd;
 403   font-family: sans-serif;
 404   font-weight: bold;
 405   margin-top: 0.0em;
 406   margin-bottom: 0.5em;
 407 }
 408
 409 div.listingblock div.content {
 410   border: 1px solid silver;
 411   background: #f4f4f4;
 412   padding: 0.5em;
 413 }
 414
 415 div.quoteblock-attribution {
 416   padding-top: 0.5em;
 417   text-align: right;
 418 }
 419
 420 div.verseblock-content {
 421   white-space: pre;
 422 }
 423 div.verseblock-attribution {
 424   padding-top: 0.75em;
 425   text-align: left;
 426 }
 427
 428 div.exampleblock-content {
 429   border-left: 3px solid #dddddd;
 430   padding-left: 0.5em;
 431 }
 432
 433 /* IE6 sets dynamically generated links as visited. */
 434 div#toc a:visited { color: blue; }
 435 </style>
 436 <script type="text/javascript">
 437 /*<![CDATA[*/
 438 window.onload = function(){asciidoc.footnotes();}
 439 var asciidoc = {  // Namespace.
 440
 441 /////////////////////////////////////////////////////////////////////
 442 // Table Of Contents generator
 443 /////////////////////////////////////////////////////////////////////
 444
 445 /* Author: Mihai Bazon, September 2002
 446  * http://students.infoiasi.ro/~mishoo
 447  *
 448  * Table Of Content generator
 449  * Version: 0.4
 450  *
 451  * Feel free to use this script under the terms of the GNU General Public
 452  * License, as long as you do not remove or alter this notice.
 453  */
 454
 455  /* modified by Troy D. Hanson, September 2006. License: GPL */
 456  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 457
 458 // toclevels = 1..4.
 459 toc: function (toclevels) {
 460
 461   function getText(el) {
 462     var text = "";
 463     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 464       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 465         text += i.data;
 466       else if (i.firstChild != null)
 467         text += getText(i);
 468     }
 469     return text;
 470   }
 471
 472   function TocEntry(el, text, toclevel) {
 473     this.element = el;
 474     this.text = text;
 475     this.toclevel = toclevel;
 476   }
 477
 478   function tocEntries(el, toclevels) {
 479     var result = new Array;
 480     var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
 481     // Function that scans the DOM tree for header elements (the DOM2
 482     // nodeIterator API would be a better technique but not supported by all
 483     // browsers).
 484     var iterate = function (el) {
 485       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 486         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 487           var mo = re.exec(i.tagName);
 488           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 489             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 490           }
 491           iterate(i);
 492         }
 493       }
 494     }
 495     iterate(el);
 496     return result;
 497   }
 498
 499   var toc = document.getElementById("toc");
 500   var entries = tocEntries(document.getElementById("content"), toclevels);
 501   for (var i = 0; i < entries.length; ++i) {
 502     var entry = entries[i];
 503     if (entry.element.id == "")
 504       entry.element.id = "_toc_" + i;
 505     var a = document.createElement("a");
 506     a.href = "#" + entry.element.id;
 507     a.appendChild(document.createTextNode(entry.text));
 508     var div = document.createElement("div");
 509     div.appendChild(a);
 510     div.className = "toclevel" + entry.toclevel;
 511     toc.appendChild(div);
 512   }
 513   if (entries.length == 0)
 514     toc.parentNode.removeChild(toc);
 515 },
 516
 517
 518 /////////////////////////////////////////////////////////////////////
 519 // Footnotes generator
 520 /////////////////////////////////////////////////////////////////////
 521
 522 /* Based on footnote generation code from:
 523  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 524  */
 525
 526 footnotes: function () {
 527   var cont = document.getElementById("content");
 528   var noteholder = document.getElementById("footnotes");
 529   var spans = cont.getElementsByTagName("span");
 530   var refs = {};
 531   var n = 0;
 532   for (i=0; i<spans.length; i++) {
 533     if (spans[i].className == "footnote") {
 534       n++;
 535       // Use [\s\S] in place of . so multi-line matches work.
 536       // Because JavaScript has no s (dotall) regex flag.
 537       note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 538       noteholder.innerHTML +=
 539         "<div class='footnote' id='_footnote_" + n + "'>" +
 540         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 541         n + "</a>. " + note + "</div>";
 542       spans[i].innerHTML =
 543         "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 544         "' title='View footnote' class='footnote'>" + n + "</a>]";
 545       var id =spans[i].getAttribute("id");
 546       if (id != null) refs["#"+id] = n;
 547     }
 548   }
 549   if (n == 0)
 550     noteholder.parentNode.removeChild(noteholder);
 551   else {
 552     // Process footnoterefs.
 553     for (i=0; i<spans.length; i++) {
 554       if (spans[i].className == "footnoteref") {
 555         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 556         href = href.match(/#.*/)[0];  // Because IE return full URL.
 557         n = refs[href];
 558         spans[i].innerHTML =
 559           "[<a href='#_footnote_" + n +
 560           "' title='View footnote' class='footnote'>" + n + "</a>]";
 561       }
 562     }
 563   }
 564 }
 565
 566 }
 567 /*]]>*/
 568 </script>
 569 </head>
 570 <body>
 571 <div id="header">
 572 <h1>
 573 git-format-patch(1) Manual Page
 574 </h1>
 575 <h2>NAME</h2>
 576 <div class="sectionbody">
 577 <p>git-format-patch -
 578    Prepare patches for e-mail submission
 579 </p>
 580 </div>
 581 </div>
 582 <div id="content">
 583 <h2 id="_synopsis">SYNOPSIS</h2>
 584 <div class="sectionbody">
 585 <div class="verseblock">
 586 <div class="verseblock-content"><em>git format-patch</em> [-k] [(-o|--output-directory) &lt;dir&gt; | --stdout]
 587                    [--no-thread | --thread[=&lt;style&gt;]]
 588                    [(--attach|--inline)[=&lt;boundary&gt;] | --no-attach]
 589                    [-s | --signoff]
 590                    [--signature=&lt;signature&gt; | --no-signature]
 591                    [-n | --numbered | -N | --no-numbered]
 592                    [--start-number &lt;n&gt;] [--numbered-files]
 593                    [--in-reply-to=Message-Id] [--suffix=.&lt;sfx&gt;]
 594                    [--ignore-if-in-upstream]
 595                    [--subject-prefix=Subject-Prefix]
 596                    [--to=&lt;email&gt;] [--cc=&lt;email&gt;]
 597                    [--cover-letter] [--quiet]
 598                    [&lt;common diff options&gt;]
 599                    [ &lt;since&gt; | &lt;revision range&gt; ]</div>
 600 <div class="verseblock-attribution">
 601 </div></div>
 602 </div>
 603 <h2 id="_description">DESCRIPTION</h2>
 604 <div class="sectionbody">
 605 <div class="paragraph"><p>Prepare each commit with its patch in
 606 one file per commit, formatted to resemble UNIX mailbox format.
 607 The output of this command is convenient for e-mail submission or
 608 for use with <em>git am</em>.</p></div>
 609 <div class="paragraph"><p>There are two ways to specify which commits to operate on.</p></div>
 610 <div class="olist arabic"><ol class="arabic">
 611 <li>
 612 <p>
 613 A single commit, &lt;since&gt;, specifies that the commits leading
 614    to the tip of the current branch that are not in the history
 615    that leads to the &lt;since&gt; to be output.
 616 </p>
 617 </li>
 618 <li>
 619 <p>
 620 Generic &lt;revision range&gt; expression (see "SPECIFYING
 621    REVISIONS" section in <a href="gitrevisions.html">gitrevisions(7)</a>) means the
 622    commits in the specified range.
 623 </p>
 624 </li>
 625 </ol></div>
 626 <div class="paragraph"><p>The first rule takes precedence in the case of a single &lt;commit&gt;.  To
 627 apply the second rule, i.e., format everything since the beginning of
 628 history up until &lt;commit&gt;, use the <em>--root</em> option: <tt>git format-patch
 629 --root &lt;commit&gt;</tt>.  If you want to format only &lt;commit&gt; itself, you
 630 can do this with <tt>git format-patch -1 &lt;commit&gt;</tt>.</p></div>
 631 <div class="paragraph"><p>By default, each output file is numbered sequentially from 1, and uses the
 632 first line of the commit message (massaged for pathname safety) as
 633 the filename. With the <tt>--numbered-files</tt> option, the output file names
 634 will only be numbers, without the first line of the commit appended.
 635 The names of the output files are printed to standard
 636 output, unless the <tt>--stdout</tt> option is specified.</p></div>
 637 <div class="paragraph"><p>If <tt>-o</tt> is specified, output files are created in &lt;dir&gt;.  Otherwise
 638 they are created in the current working directory.</p></div>
 639 <div class="paragraph"><p>By default, the subject of a single patch is "[PATCH] First Line" and
 640 the subject when multiple patches are output is "[PATCH n/m] First
 641 Line". To force 1/1 to be added for a single patch, use <tt>-n</tt>.  To omit
 642 patch numbers from the subject, use <tt>-N</tt>.</p></div>
 643 <div class="paragraph"><p>If given <tt>--thread</tt>, <tt>git-format-patch</tt> will generate <tt>In-Reply-To</tt> and
 644 <tt>References</tt> headers to make the second and subsequent patch mails appear
 645 as replies to the first mail; this also generates a <tt>Message-Id</tt> header to
 646 reference.</p></div>
 647 </div>
 648 <h2 id="_options">OPTIONS</h2>
 649 <div class="sectionbody">
 650 <div class="dlist"><dl>
 651 <dt class="hdlist1">
 652 -p
 653 </dt>
 654 <dt class="hdlist1">
 655 --no-stat
 656 </dt>
 657 <dd>
 658 <p>
 659         Generate plain patches without any diffstats.
 660 </p>
 661 </dd>
 662 <dt class="hdlist1">
 663 -U&lt;n&gt;
 664 </dt>
 665 <dt class="hdlist1">
 666 --unified=&lt;n&gt;
 667 </dt>
 668 <dd>
 669 <p>
 670         Generate diffs with &lt;n&gt; lines of context instead of
 671         the usual three.
 672 </p>
 673 </dd>
 674 <dt class="hdlist1">
 675 --minimal
 676 </dt>
 677 <dd>
 678 <p>
 679         Spend extra time to make sure the smallest possible
 680         diff is produced.
 681 </p>
 682 </dd>
 683 <dt class="hdlist1">
 684 --patience
 685 </dt>
 686 <dd>
 687 <p>
 688         Generate a diff using the "patience diff" algorithm.
 689 </p>
 690 </dd>
 691 <dt class="hdlist1">
 692 --stat[=&lt;width&gt;[,&lt;name-width&gt;[,&lt;count&gt;]]]
 693 </dt>
 694 <dd>
 695 <p>
 696         Generate a diffstat.  You can override the default
 697         output width for 80-column terminal by <tt>--stat=&lt;width&gt;</tt>.
 698         The width of the filename part can be controlled by
 699         giving another width to it separated by a comma.
 700         By giving a third parameter <tt>&lt;count&gt;</tt>, you can limit the
 701         output to the first <tt>&lt;count&gt;</tt> lines, followed by
 702         <tt>&#8230;</tt> if there are more.
 703 </p>
 704 <div class="paragraph"><p>These parameters can also be set individually with <tt>--stat-width=&lt;width&gt;</tt>,
 705 <tt>--stat-name-width=&lt;name-width&gt;</tt> and <tt>--stat-count=&lt;count&gt;</tt>.</p></div>
 706 </dd>
 707 <dt class="hdlist1">
 708 --numstat
 709 </dt>
 710 <dd>
 711 <p>
 712         Similar to <tt>--stat</tt>, but shows number of added and
 713         deleted lines in decimal notation and pathname without
 714         abbreviation, to make it more machine friendly.  For
 715         binary files, outputs two <tt>-</tt> instead of saying
 716         <tt>0 0</tt>.
 717 </p>
 718 </dd>
 719 <dt class="hdlist1">
 720 --shortstat
 721 </dt>
 722 <dd>
 723 <p>
 724         Output only the last line of the <tt>--stat</tt> format containing total
 725         number of modified files, as well as number of added and deleted
 726         lines.
 727 </p>
 728 </dd>
 729 <dt class="hdlist1">
 730 --dirstat[=&lt;param1,param2,&#8230;&gt;]
 731 </dt>
 732 <dd>
 733 <p>
 734         Output the distribution of relative amount of changes for each
 735         sub-directory. The behavior of <tt>--dirstat</tt> can be customized by
 736         passing it a comma separated list of parameters.
 737         The defaults are controlled by the <tt>diff.dirstat</tt> configuration
 738         variable (see <a href="git-config.html">git-config(1)</a>).
 739         The following parameters are available:
 740 </p>
 741 <div class="dlist"><dl>
 742 <dt class="hdlist1">
 743 <tt>changes</tt>
 744 </dt>
 745 <dd>
 746 <p>
 747         Compute the dirstat numbers by counting the lines that have been
 748         removed from the source, or added to the destination. This ignores
 749         the amount of pure code movements within a file.  In other words,
 750         rearranging lines in a file is not counted as much as other changes.
 751         This is the default behavior when no parameter is given.
 752 </p>
 753 </dd>
 754 <dt class="hdlist1">
 755 <tt>lines</tt>
 756 </dt>
 757 <dd>
 758 <p>
 759         Compute the dirstat numbers by doing the regular line-based diff
 760         analysis, and summing the removed/added line counts. (For binary
 761         files, count 64-byte chunks instead, since binary files have no
 762         natural concept of lines). This is a more expensive <tt>--dirstat</tt>
 763         behavior than the <tt>changes</tt> behavior, but it does count rearranged
 764         lines within a file as much as other changes. The resulting output
 765         is consistent with what you get from the other <tt>--*stat</tt> options.
 766 </p>
 767 </dd>
 768 <dt class="hdlist1">
 769 <tt>files</tt>
 770 </dt>
 771 <dd>
 772 <p>
 773         Compute the dirstat numbers by counting the number of files changed.
 774         Each changed file counts equally in the dirstat analysis. This is
 775         the computationally cheapest <tt>--dirstat</tt> behavior, since it does
 776         not have to look at the file contents at all.
 777 </p>
 778 </dd>
 779 <dt class="hdlist1">
 780 <tt>cumulative</tt>
 781 </dt>
 782 <dd>
 783 <p>
 784         Count changes in a child directory for the parent directory as well.
 785         Note that when using <tt>cumulative</tt>, the sum of the percentages
 786         reported may exceed 100%. The default (non-cumulative) behavior can
 787         be specified with the <tt>noncumulative</tt> parameter.
 788 </p>
 789 </dd>
 790 <dt class="hdlist1">
 791 &lt;limit&gt;
 792 </dt>
 793 <dd>
 794 <p>
 795         An integer parameter specifies a cut-off percent (3% by default).
 796         Directories contributing less than this percentage of the changes
 797         are not shown in the output.
 798 </p>
 799 </dd>
 800 </dl></div>
 801 <div class="paragraph"><p>Example: The following will count changed files, while ignoring
 802 directories with less than 10% of the total amount of changed files,
 803 and accumulating child directory counts in the parent directories:
 804 <tt>--dirstat=files,10,cumulative</tt>.</p></div>
 805 </dd>
 806 <dt class="hdlist1">
 807 --summary
 808 </dt>
 809 <dd>
 810 <p>
 811         Output a condensed summary of extended header information
 812         such as creations, renames and mode changes.
 813 </p>
 814 </dd>
 815 <dt class="hdlist1">
 816 --no-renames
 817 </dt>
 818 <dd>
 819 <p>
 820         Turn off rename detection, even when the configuration
 821         file gives the default to do so.
 822 </p>
 823 </dd>
 824 <dt class="hdlist1">
 825 --full-index
 826 </dt>
 827 <dd>
 828 <p>
 829         Instead of the first handful of characters, show the full
 830         pre- and post-image blob object names on the "index"
 831         line when generating patch format output.
 832 </p>
 833 </dd>
 834 <dt class="hdlist1">
 835 --binary
 836 </dt>
 837 <dd>
 838 <p>
 839         In addition to <tt>--full-index</tt>, output a binary diff that
 840         can be applied with <tt>git-apply</tt>.
 841 </p>
 842 </dd>
 843 <dt class="hdlist1">
 844 --abbrev[=&lt;n&gt;]
 845 </dt>
 846 <dd>
 847 <p>
 848         Instead of showing the full 40-byte hexadecimal object
 849         name in diff-raw format output and diff-tree header
 850         lines, show only a partial prefix.  This is
 851         independent of the <tt>--full-index</tt> option above, which controls
 852         the diff-patch output format.  Non default number of
 853         digits can be specified with <tt>--abbrev=&lt;n&gt;</tt>.
 854 </p>
 855 </dd>
 856 <dt class="hdlist1">
 857 -B[&lt;n&gt;][/&lt;m&gt;]
 858 </dt>
 859 <dt class="hdlist1">
 860 --break-rewrites[=[&lt;n&gt;][/&lt;m&gt;]]
 861 </dt>
 862 <dd>
 863 <p>
 864         Break complete rewrite changes into pairs of delete and
 865         create. This serves two purposes:
 866 </p>
 867 <div class="paragraph"><p>It affects the way a change that amounts to a total rewrite of a file
 868 not as a series of deletion and insertion mixed together with a very
 869 few lines that happen to match textually as the context, but as a
 870 single deletion of everything old followed by a single insertion of
 871 everything new, and the number <tt>m</tt> controls this aspect of the -B
 872 option (defaults to 60%). <tt>-B/70%</tt> specifies that less than 30% of the
 873 original should remain in the result for git to consider it a total
 874 rewrite (i.e. otherwise the resulting patch will be a series of
 875 deletion and insertion mixed together with context lines).</p></div>
 876 <div class="paragraph"><p>When used with -M, a totally-rewritten file is also considered as the
 877 source of a rename (usually -M only considers a file that disappeared
 878 as the source of a rename), and the number <tt>n</tt> controls this aspect of
 879 the -B option (defaults to 50%). <tt>-B20%</tt> specifies that a change with
 880 addition and deletion compared to 20% or more of the file&#8217;s size are
 881 eligible for being picked up as a possible source of a rename to
 882 another file.</p></div>
 883 </dd>
 884 <dt class="hdlist1">
 885 -M[&lt;n&gt;]
 886 </dt>
 887 <dt class="hdlist1">
 888 --find-renames[=&lt;n&gt;]
 889 </dt>
 890 <dd>
 891 <p>
 892         Detect renames.
 893         If <tt>n</tt> is specified, it is a threshold on the similarity
 894         index (i.e. amount of addition/deletions compared to the
 895         file&#8217;s size). For example, <tt>-M90%</tt> means git should consider a
 896         delete/add pair to be a rename if more than 90% of the file
 897         hasn&#8217;t changed.
 898 </p>
 899 </dd>
 900 <dt class="hdlist1">
 901 -C[&lt;n&gt;]
 902 </dt>
 903 <dt class="hdlist1">
 904 --find-copies[=&lt;n&gt;]
 905 </dt>
 906 <dd>
 907 <p>
 908         Detect copies as well as renames.  See also <tt>--find-copies-harder</tt>.
 909         If <tt>n</tt> is specified, it has the same meaning as for <tt>-M&lt;n&gt;</tt>.
 910 </p>
 911 </dd>
 912 <dt class="hdlist1">
 913 --find-copies-harder
 914 </dt>
 915 <dd>
 916 <p>
 917         For performance reasons, by default, <tt>-C</tt> option finds copies only
 918         if the original file of the copy was modified in the same
 919         changeset.  This flag makes the command
 920         inspect unmodified files as candidates for the source of
 921         copy.  This is a very expensive operation for large
 922         projects, so use it with caution.  Giving more than one
 923         <tt>-C</tt> option has the same effect.
 924 </p>
 925 </dd>
 926 <dt class="hdlist1">
 927 -D
 928 </dt>
 929 <dt class="hdlist1">
 930 --irreversible-delete
 931 </dt>
 932 <dd>
 933 <p>
 934         Omit the preimage for deletes, i.e. print only the header but not
 935         the diff between the preimage and <tt>/dev/null</tt>. The resulting patch
 936         is not meant to be applied with <tt>patch</tt> nor <tt>git apply</tt>; this is
 937         solely for people who want to just concentrate on reviewing the
 938         text after the change. In addition, the output obviously lack
 939         enough information to apply such a patch in reverse, even manually,
 940         hence the name of the option.
 941 </p>
 942 <div class="paragraph"><p>When used together with <tt>-B</tt>, omit also the preimage in the deletion part
 943 of a delete/create pair.</p></div>
 944 </dd>
 945 <dt class="hdlist1">
 946 -l&lt;num&gt;
 947 </dt>
 948 <dd>
 949 <p>
 950         The <tt>-M</tt> and <tt>-C</tt> options require O(n^2) processing time where n
 951         is the number of potential rename/copy targets.  This
 952         option prevents rename/copy detection from running if
 953         the number of rename/copy targets exceeds the specified
 954         number.
 955 </p>
 956 </dd>
 957 <dt class="hdlist1">
 958 -O&lt;orderfile&gt;
 959 </dt>
 960 <dd>
 961 <p>
 962         Output the patch in the order specified in the
 963         &lt;orderfile&gt;, which has one shell glob pattern per line.
 964 </p>
 965 </dd>
 966 <dt class="hdlist1">
 967 -a
 968 </dt>
 969 <dt class="hdlist1">
 970 --text
 971 </dt>
 972 <dd>
 973 <p>
 974         Treat all files as text.
 975 </p>
 976 </dd>
 977 <dt class="hdlist1">
 978 --ignore-space-at-eol
 979 </dt>
 980 <dd>
 981 <p>
 982         Ignore changes in whitespace at EOL.
 983 </p>
 984 </dd>
 985 <dt class="hdlist1">
 986 -b
 987 </dt>
 988 <dt class="hdlist1">
 989 --ignore-space-change
 990 </dt>
 991 <dd>
 992 <p>
 993         Ignore changes in amount of whitespace.  This ignores whitespace
 994         at line end, and considers all other sequences of one or
 995         more whitespace characters to be equivalent.
 996 </p>
 997 </dd>
 998 <dt class="hdlist1">
 999 -w
1000 </dt>
1001 <dt class="hdlist1">
1002 --ignore-all-space
1003 </dt>
1004 <dd>
1005 <p>
1006         Ignore whitespace when comparing lines.  This ignores
1007         differences even if one line has whitespace where the other
1008         line has none.
1009 </p>
1010 </dd>
1011 <dt class="hdlist1">
1012 --inter-hunk-context=&lt;lines&gt;
1013 </dt>
1014 <dd>
1015 <p>
1016         Show the context between diff hunks, up to the specified number
1017         of lines, thereby fusing hunks that are close to each other.
1018 </p>
1019 </dd>
1020 <dt class="hdlist1">
1021 -W
1022 </dt>
1023 <dt class="hdlist1">
1024 --function-context
1025 </dt>
1026 <dd>
1027 <p>
1028         Show whole surrounding functions of changes.
1029 </p>
1030 </dd>
1031 <dt class="hdlist1">
1032 --ext-diff
1033 </dt>
1034 <dd>
1035 <p>
1036         Allow an external diff helper to be executed. If you set an
1037         external diff driver with <a href="gitattributes.html">gitattributes(5)</a>, you need
1038         to use this option with <a href="git-log.html">git-log(1)</a> and friends.
1039 </p>
1040 </dd>
1041 <dt class="hdlist1">
1042 --no-ext-diff
1043 </dt>
1044 <dd>
1045 <p>
1046         Disallow external diff drivers.
1047 </p>
1048 </dd>
1049 <dt class="hdlist1">
1050 --textconv
1051 </dt>
1052 <dt class="hdlist1">
1053 --no-textconv
1054 </dt>
1055 <dd>
1056 <p>
1057         Allow (or disallow) external text conversion filters to be run
1058         when comparing binary files. See <a href="gitattributes.html">gitattributes(5)</a> for
1059         details. Because textconv filters are typically a one-way
1060         conversion, the resulting diff is suitable for human
1061         consumption, but cannot be applied. For this reason, textconv
1062         filters are enabled by default only for <a href="git-diff.html">git-diff(1)</a> and
1063         <a href="git-log.html">git-log(1)</a>, but not for <a href="git-format-patch.html">git-format-patch(1)</a> or
1064         diff plumbing commands.
1065 </p>
1066 </dd>
1067 <dt class="hdlist1">
1068 --ignore-submodules[=&lt;when&gt;]
1069 </dt>
1070 <dd>
1071 <p>
1072         Ignore changes to submodules in the diff generation. &lt;when&gt; can be
1073         either "none", "untracked", "dirty" or "all", which is the default
1074         Using "none" will consider the submodule modified when it either contains
1075         untracked or modified files or its HEAD differs from the commit recorded
1076         in the superproject and can be used to override any settings of the
1077         <em>ignore</em> option in <a href="git-config.html">git-config(1)</a> or <a href="gitmodules.html">gitmodules(5)</a>. When
1078         "untracked" is used submodules are not considered dirty when they only
1079         contain untracked content (but they are still scanned for modified
1080         content). Using "dirty" ignores all changes to the work tree of submodules,
1081         only changes to the commits stored in the superproject are shown (this was
1082         the behavior until 1.7.0). Using "all" hides all changes to submodules.
1083 </p>
1084 </dd>
1085 <dt class="hdlist1">
1086 --src-prefix=&lt;prefix&gt;
1087 </dt>
1088 <dd>
1089 <p>
1090         Show the given source prefix instead of "a/".
1091 </p>
1092 </dd>
1093 <dt class="hdlist1">
1094 --dst-prefix=&lt;prefix&gt;
1095 </dt>
1096 <dd>
1097 <p>
1098         Show the given destination prefix instead of "b/".
1099 </p>
1100 </dd>
1101 <dt class="hdlist1">
1102 --no-prefix
1103 </dt>
1104 <dd>
1105 <p>
1106         Do not show any source or destination prefix.
1107 </p>
1108 </dd>
1109 </dl></div>
1110 <div class="paragraph"><p>For more detailed explanation on these common options, see also
1111 <a href="gitdiffcore.html">gitdiffcore(7)</a>.</p></div>
1112 <div class="dlist"><dl>
1113 <dt class="hdlist1">
1114 -&lt;n&gt;
1115 </dt>
1116 <dd>
1117 <p>
1118         Prepare patches from the topmost &lt;n&gt; commits.
1119 </p>
1120 </dd>
1121 <dt class="hdlist1">
1122 -o &lt;dir&gt;
1123 </dt>
1124 <dt class="hdlist1">
1125 --output-directory &lt;dir&gt;
1126 </dt>
1127 <dd>
1128 <p>
1129         Use &lt;dir&gt; to store the resulting files, instead of the
1130         current working directory.
1131 </p>
1132 </dd>
1133 <dt class="hdlist1">
1134 -n
1135 </dt>
1136 <dt class="hdlist1">
1137 --numbered
1138 </dt>
1139 <dd>
1140 <p>
1141         Name output in <em>[PATCH n/m]</em> format, even with a single patch.
1142 </p>
1143 </dd>
1144 <dt class="hdlist1">
1145 -N
1146 </dt>
1147 <dt class="hdlist1">
1148 --no-numbered
1149 </dt>
1150 <dd>
1151 <p>
1152         Name output in <em>[PATCH]</em> format.
1153 </p>
1154 </dd>
1155 <dt class="hdlist1">
1156 --start-number &lt;n&gt;
1157 </dt>
1158 <dd>
1159 <p>
1160         Start numbering the patches at &lt;n&gt; instead of 1.
1161 </p>
1162 </dd>
1163 <dt class="hdlist1">
1164 --numbered-files
1165 </dt>
1166 <dd>
1167 <p>
1168         Output file names will be a simple number sequence
1169         without the default first line of the commit appended.
1170 </p>
1171 </dd>
1172 <dt class="hdlist1">
1173 -k
1174 </dt>
1175 <dt class="hdlist1">
1176 --keep-subject
1177 </dt>
1178 <dd>
1179 <p>
1180         Do not strip/add <em>[PATCH]</em> from the first line of the
1181         commit log message.
1182 </p>
1183 </dd>
1184 <dt class="hdlist1">
1185 -s
1186 </dt>
1187 <dt class="hdlist1">
1188 --signoff
1189 </dt>
1190 <dd>
1191 <p>
1192         Add <tt>Signed-off-by:</tt> line to the commit message, using
1193         the committer identity of yourself.
1194 </p>
1195 </dd>
1196 <dt class="hdlist1">
1197 --stdout
1198 </dt>
1199 <dd>
1200 <p>
1201         Print all commits to the standard output in mbox format,
1202         instead of creating a file for each one.
1203 </p>
1204 </dd>
1205 <dt class="hdlist1">
1206 --attach[=&lt;boundary&gt;]
1207 </dt>
1208 <dd>
1209 <p>
1210         Create multipart/mixed attachment, the first part of
1211         which is the commit message and the patch itself in the
1212         second part, with <tt>Content-Disposition: attachment</tt>.
1213 </p>
1214 </dd>
1215 <dt class="hdlist1">
1216 --no-attach
1217 </dt>
1218 <dd>
1219 <p>
1220         Disable the creation of an attachment, overriding the
1221         configuration setting.
1222 </p>
1223 </dd>
1224 <dt class="hdlist1">
1225 --inline[=&lt;boundary&gt;]
1226 </dt>
1227 <dd>
1228 <p>
1229         Create multipart/mixed attachment, the first part of
1230         which is the commit message and the patch itself in the
1231         second part, with <tt>Content-Disposition: inline</tt>.
1232 </p>
1233 </dd>
1234 <dt class="hdlist1">
1235 --thread[=&lt;style&gt;]
1236 </dt>
1237 <dt class="hdlist1">
1238 --no-thread
1239 </dt>
1240 <dd>
1241 <p>
1242         Controls addition of <tt>In-Reply-To</tt> and <tt>References</tt> headers to
1243         make the second and subsequent mails appear as replies to the
1244         first.  Also controls generation of the <tt>Message-Id</tt> header to
1245         reference.
1246 </p>
1247 <div class="paragraph"><p>The optional &lt;style&gt; argument can be either <tt>shallow</tt> or <tt>deep</tt>.
1248 <em>shallow</em> threading makes every mail a reply to the head of the
1249 series, where the head is chosen from the cover letter, the
1250 <tt>--in-reply-to</tt>, and the first patch mail, in this order.  <em>deep</em>
1251 threading makes every mail a reply to the previous one.</p></div>
1252 <div class="paragraph"><p>The default is <tt>--no-thread</tt>, unless the <em>format.thread</em> configuration
1253 is set.  If <tt>--thread</tt> is specified without a style, it defaults to the
1254 style specified by <em>format.thread</em> if any, or else <tt>shallow</tt>.</p></div>
1255 <div class="paragraph"><p>Beware that the default for <em>git send-email</em> is to thread emails
1256 itself.  If you want <tt>git format-patch</tt> to take care of threading, you
1257 will want to ensure that threading is disabled for <tt>git send-email</tt>.</p></div>
1258 </dd>
1259 <dt class="hdlist1">
1260 --in-reply-to=Message-Id
1261 </dt>
1262 <dd>
1263 <p>
1264         Make the first mail (or all the mails with <tt>--no-thread</tt>) appear as a
1265         reply to the given Message-Id, which avoids breaking threads to
1266         provide a new patch series.
1267 </p>
1268 </dd>
1269 <dt class="hdlist1">
1270 --ignore-if-in-upstream
1271 </dt>
1272 <dd>
1273 <p>
1274         Do not include a patch that matches a commit in
1275         &lt;until&gt;..&lt;since&gt;.  This will examine all patches reachable
1276         from &lt;since&gt; but not from &lt;until&gt; and compare them with the
1277         patches being generated, and any patch that matches is
1278         ignored.
1279 </p>
1280 </dd>
1281 <dt class="hdlist1">
1282 --subject-prefix=&lt;Subject-Prefix&gt;
1283 </dt>
1284 <dd>
1285 <p>
1286         Instead of the standard <em>[PATCH]</em> prefix in the subject
1287         line, instead use <em>[&lt;Subject-Prefix&gt;]</em>. This
1288         allows for useful naming of a patch series, and can be
1289         combined with the <tt>--numbered</tt> option.
1290 </p>
1291 </dd>
1292 <dt class="hdlist1">
1293 --to=&lt;email&gt;
1294 </dt>
1295 <dd>
1296 <p>
1297         Add a <tt>To:</tt> header to the email headers. This is in addition
1298         to any configured headers, and may be used multiple times.
1299         The negated form <tt>--no-to</tt> discards all <tt>To:</tt> headers added so
1300         far (from config or command line).
1301 </p>
1302 </dd>
1303 <dt class="hdlist1">
1304 --cc=&lt;email&gt;
1305 </dt>
1306 <dd>
1307 <p>
1308         Add a <tt>Cc:</tt> header to the email headers. This is in addition
1309         to any configured headers, and may be used multiple times.
1310         The negated form <tt>--no-cc</tt> discards all <tt>Cc:</tt> headers added so
1311         far (from config or command line).
1312 </p>
1313 </dd>
1314 <dt class="hdlist1">
1315 --add-header=&lt;header&gt;
1316 </dt>
1317 <dd>
1318 <p>
1319         Add an arbitrary header to the email headers.  This is in addition
1320         to any configured headers, and may be used multiple times.
1321         For example, <tt>--add-header="Organization: git-foo"</tt>.
1322         The negated form <tt>--no-add-header</tt> discards <strong>all</strong> (<tt>To:</tt>,
1323         <tt>Cc:</tt>, and custom) headers added so far from config or command
1324         line.
1325 </p>
1326 </dd>
1327 <dt class="hdlist1">
1328 --cover-letter
1329 </dt>
1330 <dd>
1331 <p>
1332         In addition to the patches, generate a cover letter file
1333         containing the shortlog and the overall diffstat.  You can
1334         fill in a description in the file before sending it out.
1335 </p>
1336 </dd>
1337 <dt class="hdlist1">
1338 --[no]-signature=&lt;signature&gt;
1339 </dt>
1340 <dd>
1341 <p>
1342         Add a signature to each message produced. Per RFC 3676 the signature
1343         is separated from the body by a line with '-- ' on it. If the
1344         signature option is omitted the signature defaults to the git version
1345         number.
1346 </p>
1347 </dd>
1348 <dt class="hdlist1">
1349 --suffix=.&lt;sfx&gt;
1350 </dt>
1351 <dd>
1352 <p>
1353         Instead of using <tt>.patch</tt> as the suffix for generated
1354         filenames, use specified suffix.  A common alternative is
1355         <tt>--suffix=.txt</tt>.  Leaving this empty will remove the <tt>.patch</tt>
1356         suffix.
1357 </p>
1358 <div class="paragraph"><p>Note that the leading character does not have to be a dot; for example,
1359 you can use <tt>--suffix=-patch</tt> to get <tt>0001-description-of-my-change-patch</tt>.</p></div>
1360 </dd>
1361 <dt class="hdlist1">
1362 --quiet
1363 </dt>
1364 <dd>
1365 <p>
1366         Do not print the names of the generated files to standard output.
1367 </p>
1368 </dd>
1369 <dt class="hdlist1">
1370 --no-binary
1371 </dt>
1372 <dd>
1373 <p>
1374         Do not output contents of changes in binary files, instead
1375         display a notice that those files changed.  Patches generated
1376         using this option cannot be applied properly, but they are
1377         still useful for code review.
1378 </p>
1379 </dd>
1380 <dt class="hdlist1">
1381 --root
1382 </dt>
1383 <dd>
1384 <p>
1385         Treat the revision argument as a &lt;revision range&gt;, even if it
1386         is just a single commit (that would normally be treated as a
1387         &lt;since&gt;).  Note that root commits included in the specified
1388         range are always formatted as creation patches, independently
1389         of this flag.
1390 </p>
1391 </dd>
1392 </dl></div>
1393 </div>
1394 <h2 id="_configuration">CONFIGURATION</h2>
1395 <div class="sectionbody">
1396 <div class="paragraph"><p>You can specify extra mail header lines to be added to each message,
1397 defaults for the subject prefix and file suffix, number patches when
1398 outputting more than one patch, add "To" or "Cc:" headers, configure
1399 attachments, and sign off patches with configuration variables.</p></div>
1400 <div class="listingblock">
1401 <div class="content">
1402 <pre><tt>[format]
1403         headers = "Organization: git-foo\n"
1404         subjectprefix = CHANGE
1405         suffix = .txt
1406         numbered = auto
1407         to = &lt;email&gt;
1408         cc = &lt;email&gt;
1409         attach [ = mime-boundary-string ]
1410         signoff = true</tt></pre>
1411 </div></div>
1412 </div>
1413 <h2 id="_discussion">DISCUSSION</h2>
1414 <div class="sectionbody">
1415 <div class="paragraph"><p>The patch produced by <em>git format-patch</em> is in UNIX mailbox format,
1416 with a fixed "magic" time stamp to indicate that the file is output
1417 from format-patch rather than a real mailbox, like so:</p></div>
1418 <div class="listingblock">
1419 <div class="content">
1420 <pre><tt>From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
1421 From: Tony Luck &lt;tony.luck@intel.com&gt;
1422 Date: Tue, 13 Jul 2010 11:42:54 -0700
1423 Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
1424  =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
1425 MIME-Version: 1.0
1426 Content-Type: text/plain; charset=UTF-8
1427 Content-Transfer-Encoding: 8bit
1428
1429 arch/arm config files were slimmed down using a python script
1430 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
1431
1432 Do the same for ia64 so we can have sleek &amp; trim looking
1433 ...</tt></pre>
1434 </div></div>
1435 <div class="paragraph"><p>Typically it will be placed in a MUA&#8217;s drafts folder, edited to add
1436 timely commentary that should not go in the changelog after the three
1437 dashes, and then sent as a message whose body, in our example, starts
1438 with "arch/arm config files were&#8230;".  On the receiving end, readers
1439 can save interesting patches in a UNIX mailbox and apply them with
1440 <a href="git-am.html">git-am(1)</a>.</p></div>
1441 <div class="paragraph"><p>When a patch is part of an ongoing discussion, the patch generated by
1442 <em>git format-patch</em> can be tweaked to take advantage of the <em>git am
1443 --scissors</em> feature.  After your response to the discussion comes a
1444 line that consists solely of "<tt>-- &gt;8 --</tt>" (scissors and perforation),
1445 followed by the patch with unnecessary header fields removed:</p></div>
1446 <div class="listingblock">
1447 <div class="content">
1448 <pre><tt>...
1449 &gt; So we should do such-and-such.
1450
1451 Makes sense to me.  How about this patch?
1452
1453 -- &gt;8 --
1454 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
1455
1456 arch/arm config files were slimmed down using a python script
1457 ...</tt></pre>
1458 </div></div>
1459 <div class="paragraph"><p>When sending a patch this way, most often you are sending your own
1460 patch, so in addition to the "<tt>From $SHA1 $magic_timestamp</tt>" marker you
1461 should omit <tt>From:</tt> and <tt>Date:</tt> lines from the patch file.  The patch
1462 title is likely to be different from the subject of the discussion the
1463 patch is in response to, so it is likely that you would want to keep
1464 the Subject: line, like the example above.</p></div>
1465 <h3 id="_checking_for_patch_corruption">Checking for patch corruption</h3><div style="clear:left"></div>
1466 <div class="paragraph"><p>Many mailers if not set up properly will corrupt whitespace.  Here are
1467 two common types of corruption:</p></div>
1468 <div class="ulist"><ul>
1469 <li>
1470 <p>
1471 Empty context lines that do not have <em>any</em> whitespace.
1472 </p>
1473 </li>
1474 <li>
1475 <p>
1476 Non-empty context lines that have one extra whitespace at the
1477   beginning.
1478 </p>
1479 </li>
1480 </ul></div>
1481 <div class="paragraph"><p>One way to test if your MUA is set up correctly is:</p></div>
1482 <div class="ulist"><ul>
1483 <li>
1484 <p>
1485 Send the patch to yourself, exactly the way you would, except
1486   with To: and Cc: lines that do not contain the list and
1487   maintainer address.
1488 </p>
1489 </li>
1490 <li>
1491 <p>
1492 Save that patch to a file in UNIX mailbox format.  Call it a.patch,
1493   say.
1494 </p>
1495 </li>
1496 <li>
1497 <p>
1498 Apply it:
1499 </p>
1500 <div class="literalblock">
1501 <div class="content">
1502 <pre><tt>$ git fetch &lt;project&gt; master:test-apply
1503 $ git checkout test-apply
1504 $ git reset --hard
1505 $ git am a.patch</tt></pre>
1506 </div></div>
1507 </li>
1508 </ul></div>
1509 <div class="paragraph"><p>If it does not apply correctly, there can be various reasons.</p></div>
1510 <div class="ulist"><ul>
1511 <li>
1512 <p>
1513 The patch itself does not apply cleanly.  That is <em>bad</em> but
1514   does not have much to do with your MUA.  You might want to rebase
1515   the patch with <a href="git-rebase.html">git-rebase(1)</a> before regenerating it in
1516   this case.
1517 </p>
1518 </li>
1519 <li>
1520 <p>
1521 The MUA corrupted your patch; "am" would complain that
1522   the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and
1523   see what <em>patch</em> file contains and check for the common
1524   corruption patterns mentioned above.
1525 </p>
1526 </li>
1527 <li>
1528 <p>
1529 While at it, check the <em>info</em> and <em>final-commit</em> files as well.
1530   If what is in <em>final-commit</em> is not exactly what you would want to
1531   see in the commit log message, it is very likely that the
1532   receiver would end up hand editing the log message when applying
1533   your patch.  Things like "Hi, this is my first patch.\n" in the
1534   patch e-mail should come after the three-dash line that signals
1535   the end of the commit message.
1536 </p>
1537 </li>
1538 </ul></div>
1539 </div>
1540 <h2 id="_mua_specific_hints">MUA-SPECIFIC HINTS</h2>
1541 <div class="sectionbody">
1542 <div class="paragraph"><p>Here are some hints on how to successfully submit patches inline using
1543 various mailers.</p></div>
1544 <h3 id="_gmail">GMail</h3><div style="clear:left"></div>
1545 <div class="paragraph"><p>GMail does not have any way to turn off line wrapping in the web
1546 interface, so it will mangle any emails that you send.  You can however
1547 use "git send-email" and send your patches through the GMail SMTP server, or
1548 use any IMAP email client to connect to the google IMAP server and forward
1549 the emails through that.</p></div>
1550 <div class="paragraph"><p>For hints on using <em>git send-email</em> to send your patches through the
1551 GMail SMTP server, see the EXAMPLE section of <a href="git-send-email.html">git-send-email(1)</a>.</p></div>
1552 <div class="paragraph"><p>For hints on submission using the IMAP interface, see the EXAMPLE
1553 section of <a href="git-imap-send.html">git-imap-send(1)</a>.</p></div>
1554 <h3 id="_thunderbird">Thunderbird</h3><div style="clear:left"></div>
1555 <div class="paragraph"><p>By default, Thunderbird will both wrap emails as well as flag
1556 them as being <em>format=flowed</em>, both of which will make the
1557 resulting email unusable by git.</p></div>
1558 <div class="paragraph"><p>There are three different approaches: use an add-on to turn off line wraps,
1559 configure Thunderbird to not mangle patches, or use
1560 an external editor to keep Thunderbird from mangling the patches.</p></div>
1561 <h4 id="_approach_1_add_on">Approach #1 (add-on)</h4>
1562 <div class="paragraph"><p>Install the Toggle Word Wrap add-on that is available from
1563 <a href="https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/">https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/</a>
1564 It adds a menu entry "Enable Word Wrap" in the composer&#8217;s "Options" menu
1565 that you can tick off. Now you can compose the message as you otherwise do
1566 (cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc), but you have to
1567 insert line breaks manually in any text that you type.</p></div>
1568 <h4 id="_approach_2_configuration">Approach #2 (configuration)</h4>
1569 <div class="paragraph"><p>Three steps:</p></div>
1570 <div class="olist arabic"><ol class="arabic">
1571 <li>
1572 <p>
1573 Configure your mail server composition as plain text:
1574    Edit&#8230;Account Settings&#8230;Composition &amp; Addressing,
1575    uncheck "Compose Messages in HTML".
1576 </p>
1577 </li>
1578 <li>
1579 <p>
1580 Configure your general composition window to not wrap.
1581 </p>
1582 <div class="paragraph"><p>In Thunderbird 2:
1583 Edit..Preferences..Composition, wrap plain text messages at 0</p></div>
1584 <div class="paragraph"><p>In Thunderbird 3:
1585 Edit..Preferences..Advanced..Config Editor.  Search for
1586 "mail.wrap_long_lines".
1587 Toggle it to make sure it is set to <tt>false</tt>.</p></div>
1588 </li>
1589 <li>
1590 <p>
1591 Disable the use of format=flowed:
1592 Edit..Preferences..Advanced..Config Editor.  Search for
1593 "mailnews.send_plaintext_flowed".
1594 Toggle it to make sure it is set to <tt>false</tt>.
1595 </p>
1596 </li>
1597 </ol></div>
1598 <div class="paragraph"><p>After that is done, you should be able to compose email as you
1599 otherwise would (cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc),
1600 and the patches will not be mangled.</p></div>
1601 <h4 id="_approach_3_external_editor">Approach #3 (external editor)</h4>
1602 <div class="paragraph"><p>The following Thunderbird extensions are needed:
1603 AboutConfig from <a href="http://aboutconfig.mozdev.org/">http://aboutconfig.mozdev.org/</a> and
1604 External Editor from <a href="http://globs.org/articles.php?lng=en&amp;pg=8">http://globs.org/articles.php?lng=en&amp;pg=8</a></p></div>
1605 <div class="olist arabic"><ol class="arabic">
1606 <li>
1607 <p>
1608 Prepare the patch as a text file using your method of choice.
1609 </p>
1610 </li>
1611 <li>
1612 <p>
1613 Before opening a compose window, use Edit&#8594;Account Settings to
1614    uncheck the "Compose messages in HTML format" setting in the
1615    "Composition &amp; Addressing" panel of the account to be used to
1616    send the patch.
1617 </p>
1618 </li>
1619 <li>
1620 <p>
1621 In the main Thunderbird window, <em>before</em> you open the compose
1622    window for the patch, use Tools&#8594;about:config to set the
1623    following to the indicated values:
1624 </p>
1625 <div class="listingblock">
1626 <div class="content">
1627 <pre><tt>        mailnews.send_plaintext_flowed  =&gt; false
1628         mailnews.wraplength             =&gt; 0</tt></pre>
1629 </div></div>
1630 </li>
1631 <li>
1632 <p>
1633 Open a compose window and click the external editor icon.
1634 </p>
1635 </li>
1636 <li>
1637 <p>
1638 In the external editor window, read in the patch file and exit
1639    the editor normally.
1640 </p>
1641 </li>
1642 </ol></div>
1643 <div class="paragraph"><p>Side note: it may be possible to do step 2 with
1644 about:config and the following settings but no one&#8217;s tried yet.</p></div>
1645 <div class="listingblock">
1646 <div class="content">
1647 <pre><tt>        mail.html_compose                       =&gt; false
1648         mail.identity.default.compose_html      =&gt; false
1649         mail.identity.id?.compose_html          =&gt; false</tt></pre>
1650 </div></div>
1651 <div class="paragraph"><p>There is a script in contrib/thunderbird-patch-inline which can help
1652 you include patches with Thunderbird in an easy way. To use it, do the
1653 steps above and then use the script as the external editor.</p></div>
1654 <h3 id="_kmail">KMail</h3><div style="clear:left"></div>
1655 <div class="paragraph"><p>This should help you to submit patches inline using KMail.</p></div>
1656 <div class="olist arabic"><ol class="arabic">
1657 <li>
1658 <p>
1659 Prepare the patch as a text file.
1660 </p>
1661 </li>
1662 <li>
1663 <p>
1664 Click on New Mail.
1665 </p>
1666 </li>
1667 <li>
1668 <p>
1669 Go under "Options" in the Composer window and be sure that
1670    "Word wrap" is not set.
1671 </p>
1672 </li>
1673 <li>
1674 <p>
1675 Use Message &#8594; Insert file&#8230; and insert the patch.
1676 </p>
1677 </li>
1678 <li>
1679 <p>
1680 Back in the compose window: add whatever other text you wish to the
1681    message, complete the addressing and subject fields, and press send.
1682 </p>
1683 </li>
1684 </ol></div>
1685 </div>
1686 <h2 id="_examples">EXAMPLES</h2>
1687 <div class="sectionbody">
1688 <div class="ulist"><ul>
1689 <li>
1690 <p>
1691 Extract commits between revisions R1 and R2, and apply them on top of
1692 the current branch using <em>git am</em> to cherry-pick them:
1693 </p>
1694 <div class="listingblock">
1695 <div class="content">
1696 <pre><tt>$ git format-patch -k --stdout R1..R2 | git am -3 -k</tt></pre>
1697 </div></div>
1698 </li>
1699 <li>
1700 <p>
1701 Extract all commits which are in the current branch but not in the
1702 origin branch:
1703 </p>
1704 <div class="listingblock">
1705 <div class="content">
1706 <pre><tt>$ git format-patch origin</tt></pre>
1707 </div></div>
1708 <div class="paragraph"><p>For each commit a separate file is created in the current directory.</p></div>
1709 </li>
1710 <li>
1711 <p>
1712 Extract all commits that lead to <em>origin</em> since the inception of the
1713 project:
1714 </p>
1715 <div class="listingblock">
1716 <div class="content">
1717 <pre><tt>$ git format-patch --root origin</tt></pre>
1718 </div></div>
1719 </li>
1720 <li>
1721 <p>
1722 The same as the previous one:
1723 </p>
1724 <div class="listingblock">
1725 <div class="content">
1726 <pre><tt>$ git format-patch -M -B origin</tt></pre>
1727 </div></div>
1728 <div class="paragraph"><p>Additionally, it detects and handles renames and complete rewrites
1729 intelligently to produce a renaming patch.  A renaming patch reduces
1730 the amount of text output, and generally makes it easier to review.
1731 Note that non-git "patch" programs won&#8217;t understand renaming patches, so
1732 use it only when you know the recipient uses git to apply your patch.</p></div>
1733 </li>
1734 <li>
1735 <p>
1736 Extract three topmost commits from the current branch and format them
1737 as e-mailable patches:
1738 </p>
1739 <div class="listingblock">
1740 <div class="content">
1741 <pre><tt>$ git format-patch -3</tt></pre>
1742 </div></div>
1743 </li>
1744 </ul></div>
1745 </div>
1746 <h2 id="_see_also">SEE ALSO</h2>
1747 <div class="sectionbody">
1748 <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>
1749 </div>
1750 <h2 id="_git">GIT</h2>
1751 <div class="sectionbody">
1752 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1753 </div>
1754 </div>
1755 <div id="footnotes"><hr /></div>
1756 <div id="footer">
1757 <div id="footer-text">
1758 Last updated 2011-09-21 23:01:14 PDT
1759 </div>
1760 </div>
1761 </body>
1762 </html>