doc/source/en/TortoiseGit/git_doc/git-format-patch.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-format-patch(1)">\r
   5 <articleinfo>\r
   6     <title>git-format-patch(1)</title>\r
   7 <indexterm>\r
   8 <primary>git-format-patch(1)</primary>\r
   9 </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-format-patch - Prepare patches for e-mail submission</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git format-patch</emphasis> [-k] [(-o|--output-directory) &lt;dir&gt; | --stdout]\r
  19                    [--no-thread | --thread[=&lt;style&gt;]]\r
  20                    [(--attach|--inline)[=&lt;boundary&gt;] | --no-attach]\r
  21                    [-s | --signoff]\r
  22                    [--signature=&lt;signature&gt; | --no-signature]\r
  23                    [-n | --numbered | -N | --no-numbered]\r
  24                    [--start-number &lt;n&gt;] [--numbered-files]\r
  25                    [--in-reply-to=Message-Id] [--suffix=.&lt;sfx&gt;]\r
  26                    [--ignore-if-in-upstream]\r
  27                    [--subject-prefix=Subject-Prefix]\r
  28                    [--to=&lt;email&gt;] [--cc=&lt;email&gt;]\r
  29                    [--cover-letter] [--quiet]\r
  30                    [&lt;common diff options&gt;]\r
  31                    [ &lt;since&gt; | &lt;revision range&gt; ]</literallayout>\r
  32 </blockquote>\r
  33 </simplesect>\r
  34 <simplesect id="_description">\r
  35 <title>DESCRIPTION</title>\r
  36 <simpara>Prepare each commit with its patch in\r
  37 one file per commit, formatted to resemble UNIX mailbox format.\r
  38 The output of this command is convenient for e-mail submission or\r
  39 for use with <emphasis>git am</emphasis>.</simpara>\r
  40 <simpara>There are two ways to specify which commits to operate on.</simpara>\r
  41 <orderedlist numeration="arabic">\r
  42 <listitem>\r
  43 <simpara>\r
  44 A single commit, &lt;since&gt;, specifies that the commits leading\r
  45    to the tip of the current branch that are not in the history\r
  46    that leads to the &lt;since&gt; to be output.\r
  47 </simpara>\r
  48 </listitem>\r
  49 <listitem>\r
  50 <simpara>\r
  51 Generic &lt;revision range&gt; expression (see "SPECIFYING\r
  52    REVISIONS" section in <xref linkend="gitrevisions(7)" />) means the\r
  53    commits in the specified range.\r
  54 </simpara>\r
  55 </listitem>\r
  56 </orderedlist>\r
  57 <simpara>The first rule takes precedence in the case of a single &lt;commit&gt;.  To\r
  58 apply the second rule, i.e., format everything since the beginning of\r
  59 history up until &lt;commit&gt;, use the <emphasis>--root</emphasis> option: <emphasis>git format-patch\r
  60 --root &lt;commit&gt;</emphasis>.  If you want to format only &lt;commit&gt; itself, you\r
  61 can do this with <emphasis>git format-patch -1 &lt;commit&gt;</emphasis>.</simpara>\r
  62 <simpara>By default, each output file is numbered sequentially from 1, and uses the\r
  63 first line of the commit message (massaged for pathname safety) as\r
  64 the filename. With the <emphasis>--numbered-files</emphasis> option, the output file names\r
  65 will only be numbers, without the first line of the commit appended.\r
  66 The names of the output files are printed to standard\r
  67 output, unless the <emphasis>--stdout</emphasis> option is specified.</simpara>\r
  68 <simpara>If <emphasis>-o</emphasis> is specified, output files are created in &lt;dir&gt;.  Otherwise\r
  69 they are created in the current working directory.</simpara>\r
  70 <simpara>By default, the subject of a single patch is "[PATCH] First Line" and\r
  71 the subject when multiple patches are output is "[PATCH n/m] First\r
  72 Line". To force 1/1 to be added for a single patch, use <emphasis>-n</emphasis>.  To omit\r
  73 patch numbers from the subject, use <emphasis>-N</emphasis>.</simpara>\r
  74 <simpara>If given <emphasis>--thread</emphasis>, <emphasis>git-format-patch</emphasis> will generate <emphasis>In-Reply-To</emphasis> and\r
  75 <emphasis>References</emphasis> headers to make the second and subsequent patch mails appear\r
  76 as replies to the first mail; this also generates a <emphasis>Message-Id</emphasis> header to\r
  77 reference.</simpara>\r
  78 </simplesect>\r
  79 <simplesect id="_options">\r
  80 <title>OPTIONS</title>\r
  81 <variablelist>\r
  82 <varlistentry>\r
  83 <term>\r
  84 -p\r
  85 </term>\r
  86 <term>\r
  87 --no-stat\r
  88 </term>\r
  89 <listitem>\r
  90 <simpara>\r
  91         Generate plain patches without any diffstats.\r
  92 </simpara>\r
  93 </listitem>\r
  94 </varlistentry>\r
  95 <varlistentry>\r
  96 <term>\r
  97 -U&lt;n&gt;\r
  98 </term>\r
  99 <term>\r
 100 --unified=&lt;n&gt;\r
 101 </term>\r
 102 <listitem>\r
 103 <simpara>\r
 104         Generate diffs with &lt;n&gt; lines of context instead of\r
 105         the usual three.\r
 106 </simpara>\r
 107 </listitem>\r
 108 </varlistentry>\r
 109 <varlistentry>\r
 110 <term>\r
 111 --minimal\r
 112 </term>\r
 113 <listitem>\r
 114 <simpara>\r
 115         Spend extra time to make sure the smallest possible\r
 116         diff is produced.\r
 117 </simpara>\r
 118 </listitem>\r
 119 </varlistentry>\r
 120 <varlistentry>\r
 121 <term>\r
 122 --patience\r
 123 </term>\r
 124 <listitem>\r
 125 <simpara>\r
 126         Generate a diff using the "patience diff" algorithm.\r
 127 </simpara>\r
 128 </listitem>\r
 129 </varlistentry>\r
 130 <varlistentry>\r
 131 <term>\r
 132 --histogram\r
 133 </term>\r
 134 <listitem>\r
 135 <simpara>\r
 136         Generate a diff using the "histogram diff" algorithm.\r
 137 </simpara>\r
 138 </listitem>\r
 139 </varlistentry>\r
 140 <varlistentry>\r
 141 <term>\r
 142 --stat[=&lt;width&gt;[,&lt;name-width&gt;[,&lt;count&gt;]]]\r
 143 </term>\r
 144 <listitem>\r
 145 <simpara>\r
 146         Generate a diffstat. By default, as much space as necessary\r
 147         will be used for the filename part, and the rest for the graph\r
 148         part. Maximum width defaults to terminal width, or 80 columns\r
 149         if not connected to a terminal, and can be overriden by\r
 150         <emphasis>&lt;width&gt;</emphasis>. The width of the filename part can be limited by\r
 151         giving another width <emphasis>&lt;name-width&gt;</emphasis> after a comma. The width\r
 152         of the graph part can be limited by using\r
 153         <emphasis>--stat-graph-width=&lt;width&gt;</emphasis> (affects all commands generating\r
 154         a stat graph) or by setting <emphasis>diff.statGraphWidth=&lt;width&gt;</emphasis>\r
 155         (does not affect <emphasis>git format-patch</emphasis>).\r
 156         By giving a third parameter <emphasis>&lt;count&gt;</emphasis>, you can limit the\r
 157         output to the first <emphasis>&lt;count&gt;</emphasis> lines, followed by <emphasis>...</emphasis> if\r
 158         there are more.\r
 159 </simpara>\r
 160 <simpara>These parameters can also be set individually with <emphasis>--stat-width=&lt;width&gt;</emphasis>,\r
 161 <emphasis>--stat-name-width=&lt;name-width&gt;</emphasis> and <emphasis>--stat-count=&lt;count&gt;</emphasis>.</simpara>\r
 162 </listitem>\r
 163 </varlistentry>\r
 164 <varlistentry>\r
 165 <term>\r
 166 --numstat\r
 167 </term>\r
 168 <listitem>\r
 169 <simpara>\r
 170         Similar to <emphasis>--stat</emphasis>, but shows number of added and\r
 171         deleted lines in decimal notation and pathname without\r
 172         abbreviation, to make it more machine friendly.  For\r
 173         binary files, outputs two <emphasis>-</emphasis> instead of saying\r
 174         <emphasis>0 0</emphasis>.\r
 175 </simpara>\r
 176 </listitem>\r
 177 </varlistentry>\r
 178 <varlistentry>\r
 179 <term>\r
 180 --shortstat\r
 181 </term>\r
 182 <listitem>\r
 183 <simpara>\r
 184         Output only the last line of the <emphasis>--stat</emphasis> format containing total\r
 185         number of modified files, as well as number of added and deleted\r
 186         lines.\r
 187 </simpara>\r
 188 </listitem>\r
 189 </varlistentry>\r
 190 <varlistentry>\r
 191 <term>\r
 192 --dirstat[=&lt;param1,param2,&#8230;&gt;]\r
 193 </term>\r
 194 <listitem>\r
 195 <simpara>\r
 196         Output the distribution of relative amount of changes for each\r
 197         sub-directory. The behavior of <emphasis>--dirstat</emphasis> can be customized by\r
 198         passing it a comma separated list of parameters.\r
 199         The defaults are controlled by the <emphasis>diff.dirstat</emphasis> configuration\r
 200         variable (see <xref linkend="git-config(1)" />).\r
 201         The following parameters are available:\r
 202 </simpara>\r
 203 <variablelist>\r
 204 <varlistentry>\r
 205 <term>\r
 206 <emphasis>changes</emphasis>\r
 207 </term>\r
 208 <listitem>\r
 209 <simpara>\r
 210         Compute the dirstat numbers by counting the lines that have been\r
 211         removed from the source, or added to the destination. This ignores\r
 212         the amount of pure code movements within a file.  In other words,\r
 213         rearranging lines in a file is not counted as much as other changes.\r
 214         This is the default behavior when no parameter is given.\r
 215 </simpara>\r
 216 </listitem>\r
 217 </varlistentry>\r
 218 <varlistentry>\r
 219 <term>\r
 220 <emphasis>lines</emphasis>\r
 221 </term>\r
 222 <listitem>\r
 223 <simpara>\r
 224         Compute the dirstat numbers by doing the regular line-based diff\r
 225         analysis, and summing the removed/added line counts. (For binary\r
 226         files, count 64-byte chunks instead, since binary files have no\r
 227         natural concept of lines). This is a more expensive <emphasis>--dirstat</emphasis>\r
 228         behavior than the <emphasis>changes</emphasis> behavior, but it does count rearranged\r
 229         lines within a file as much as other changes. The resulting output\r
 230         is consistent with what you get from the other <emphasis>--*stat</emphasis> options.\r
 231 </simpara>\r
 232 </listitem>\r
 233 </varlistentry>\r
 234 <varlistentry>\r
 235 <term>\r
 236 <emphasis>files</emphasis>\r
 237 </term>\r
 238 <listitem>\r
 239 <simpara>\r
 240         Compute the dirstat numbers by counting the number of files changed.\r
 241         Each changed file counts equally in the dirstat analysis. This is\r
 242         the computationally cheapest <emphasis>--dirstat</emphasis> behavior, since it does\r
 243         not have to look at the file contents at all.\r
 244 </simpara>\r
 245 </listitem>\r
 246 </varlistentry>\r
 247 <varlistentry>\r
 248 <term>\r
 249 <emphasis>cumulative</emphasis>\r
 250 </term>\r
 251 <listitem>\r
 252 <simpara>\r
 253         Count changes in a child directory for the parent directory as well.\r
 254         Note that when using <emphasis>cumulative</emphasis>, the sum of the percentages\r
 255         reported may exceed 100%. The default (non-cumulative) behavior can\r
 256         be specified with the <emphasis>noncumulative</emphasis> parameter.\r
 257 </simpara>\r
 258 </listitem>\r
 259 </varlistentry>\r
 260 <varlistentry>\r
 261 <term>\r
 262 &lt;limit&gt;\r
 263 </term>\r
 264 <listitem>\r
 265 <simpara>\r
 266         An integer parameter specifies a cut-off percent (3% by default).\r
 267         Directories contributing less than this percentage of the changes\r
 268         are not shown in the output.\r
 269 </simpara>\r
 270 </listitem>\r
 271 </varlistentry>\r
 272 </variablelist>\r
 273 <simpara>Example: The following will count changed files, while ignoring\r
 274 directories with less than 10% of the total amount of changed files,\r
 275 and accumulating child directory counts in the parent directories:\r
 276 <emphasis>--dirstat=files,10,cumulative</emphasis>.</simpara>\r
 277 </listitem>\r
 278 </varlistentry>\r
 279 <varlistentry>\r
 280 <term>\r
 281 --summary\r
 282 </term>\r
 283 <listitem>\r
 284 <simpara>\r
 285         Output a condensed summary of extended header information\r
 286         such as creations, renames and mode changes.\r
 287 </simpara>\r
 288 </listitem>\r
 289 </varlistentry>\r
 290 <varlistentry>\r
 291 <term>\r
 292 --no-renames\r
 293 </term>\r
 294 <listitem>\r
 295 <simpara>\r
 296         Turn off rename detection, even when the configuration\r
 297         file gives the default to do so.\r
 298 </simpara>\r
 299 </listitem>\r
 300 </varlistentry>\r
 301 <varlistentry>\r
 302 <term>\r
 303 --full-index\r
 304 </term>\r
 305 <listitem>\r
 306 <simpara>\r
 307         Instead of the first handful of characters, show the full\r
 308         pre- and post-image blob object names on the "index"\r
 309         line when generating patch format output.\r
 310 </simpara>\r
 311 </listitem>\r
 312 </varlistentry>\r
 313 <varlistentry>\r
 314 <term>\r
 315 --binary\r
 316 </term>\r
 317 <listitem>\r
 318 <simpara>\r
 319         In addition to <emphasis>--full-index</emphasis>, output a binary diff that\r
 320         can be applied with <emphasis>git-apply</emphasis>.\r
 321 </simpara>\r
 322 </listitem>\r
 323 </varlistentry>\r
 324 <varlistentry>\r
 325 <term>\r
 326 --abbrev[=&lt;n&gt;]\r
 327 </term>\r
 328 <listitem>\r
 329 <simpara>\r
 330         Instead of showing the full 40-byte hexadecimal object\r
 331         name in diff-raw format output and diff-tree header\r
 332         lines, show only a partial prefix.  This is\r
 333         independent of the <emphasis>--full-index</emphasis> option above, which controls\r
 334         the diff-patch output format.  Non default number of\r
 335         digits can be specified with <emphasis>--abbrev=&lt;n&gt;</emphasis>.\r
 336 </simpara>\r
 337 </listitem>\r
 338 </varlistentry>\r
 339 <varlistentry>\r
 340 <term>\r
 341 -B[&lt;n&gt;][/&lt;m&gt;]\r
 342 </term>\r
 343 <term>\r
 344 --break-rewrites[=[&lt;n&gt;][/&lt;m&gt;]]\r
 345 </term>\r
 346 <listitem>\r
 347 <simpara>\r
 348         Break complete rewrite changes into pairs of delete and\r
 349         create. This serves two purposes:\r
 350 </simpara>\r
 351 <simpara>It affects the way a change that amounts to a total rewrite of a file\r
 352 not as a series of deletion and insertion mixed together with a very\r
 353 few lines that happen to match textually as the context, but as a\r
 354 single deletion of everything old followed by a single insertion of\r
 355 everything new, and the number <emphasis>m</emphasis> controls this aspect of the -B\r
 356 option (defaults to 60%). <emphasis>-B/70%</emphasis> specifies that less than 30% of the\r
 357 original should remain in the result for git to consider it a total\r
 358 rewrite (i.e. otherwise the resulting patch will be a series of\r
 359 deletion and insertion mixed together with context lines).</simpara>\r
 360 <simpara>When used with -M, a totally-rewritten file is also considered as the\r
 361 source of a rename (usually -M only considers a file that disappeared\r
 362 as the source of a rename), and the number <emphasis>n</emphasis> controls this aspect of\r
 363 the -B option (defaults to 50%). <emphasis>-B20%</emphasis> specifies that a change with\r
 364 addition and deletion compared to 20% or more of the file's size are\r
 365 eligible for being picked up as a possible source of a rename to\r
 366 another file.</simpara>\r
 367 </listitem>\r
 368 </varlistentry>\r
 369 <varlistentry>\r
 370 <term>\r
 371 -M[&lt;n&gt;]\r
 372 </term>\r
 373 <term>\r
 374 --find-renames[=&lt;n&gt;]\r
 375 </term>\r
 376 <listitem>\r
 377 <simpara>\r
 378         Detect renames.\r
 379         If <emphasis>n</emphasis> is specified, it is a threshold on the similarity\r
 380         index (i.e. amount of addition/deletions compared to the\r
 381         file's size). For example, <emphasis>-M90%</emphasis> means git should consider a\r
 382         delete/add pair to be a rename if more than 90% of the file\r
 383         hasn't changed.\r
 384 </simpara>\r
 385 </listitem>\r
 386 </varlistentry>\r
 387 <varlistentry>\r
 388 <term>\r
 389 -C[&lt;n&gt;]\r
 390 </term>\r
 391 <term>\r
 392 --find-copies[=&lt;n&gt;]\r
 393 </term>\r
 394 <listitem>\r
 395 <simpara>\r
 396         Detect copies as well as renames.  See also <emphasis>--find-copies-harder</emphasis>.\r
 397         If <emphasis>n</emphasis> is specified, it has the same meaning as for <emphasis>-M&lt;n&gt;</emphasis>.\r
 398 </simpara>\r
 399 </listitem>\r
 400 </varlistentry>\r
 401 <varlistentry>\r
 402 <term>\r
 403 --find-copies-harder\r
 404 </term>\r
 405 <listitem>\r
 406 <simpara>\r
 407         For performance reasons, by default, <emphasis>-C</emphasis> option finds copies only\r
 408         if the original file of the copy was modified in the same\r
 409         changeset.  This flag makes the command\r
 410         inspect unmodified files as candidates for the source of\r
 411         copy.  This is a very expensive operation for large\r
 412         projects, so use it with caution.  Giving more than one\r
 413         <emphasis>-C</emphasis> option has the same effect.\r
 414 </simpara>\r
 415 </listitem>\r
 416 </varlistentry>\r
 417 <varlistentry>\r
 418 <term>\r
 419 -D\r
 420 </term>\r
 421 <term>\r
 422 --irreversible-delete\r
 423 </term>\r
 424 <listitem>\r
 425 <simpara>\r
 426         Omit the preimage for deletes, i.e. print only the header but not\r
 427         the diff between the preimage and <emphasis>/dev/null</emphasis>. The resulting patch\r
 428         is not meant to be applied with <emphasis>patch</emphasis> nor <emphasis>git apply</emphasis>; this is\r
 429         solely for people who want to just concentrate on reviewing the\r
 430         text after the change. In addition, the output obviously lack\r
 431         enough information to apply such a patch in reverse, even manually,\r
 432         hence the name of the option.\r
 433 </simpara>\r
 434 <simpara>When used together with <emphasis>-B</emphasis>, omit also the preimage in the deletion part\r
 435 of a delete/create pair.</simpara>\r
 436 </listitem>\r
 437 </varlistentry>\r
 438 <varlistentry>\r
 439 <term>\r
 440 -l&lt;num&gt;\r
 441 </term>\r
 442 <listitem>\r
 443 <simpara>\r
 444         The <emphasis>-M</emphasis> and <emphasis>-C</emphasis> options require O(n^2) processing time where n\r
 445         is the number of potential rename/copy targets.  This\r
 446         option prevents rename/copy detection from running if\r
 447         the number of rename/copy targets exceeds the specified\r
 448         number.\r
 449 </simpara>\r
 450 </listitem>\r
 451 </varlistentry>\r
 452 <varlistentry>\r
 453 <term>\r
 454 -O&lt;orderfile&gt;\r
 455 </term>\r
 456 <listitem>\r
 457 <simpara>\r
 458         Output the patch in the order specified in the\r
 459         &lt;orderfile&gt;, which has one shell glob pattern per line.\r
 460 </simpara>\r
 461 </listitem>\r
 462 </varlistentry>\r
 463 <varlistentry>\r
 464 <term>\r
 465 -a\r
 466 </term>\r
 467 <term>\r
 468 --text\r
 469 </term>\r
 470 <listitem>\r
 471 <simpara>\r
 472         Treat all files as text.\r
 473 </simpara>\r
 474 </listitem>\r
 475 </varlistentry>\r
 476 <varlistentry>\r
 477 <term>\r
 478 --ignore-space-at-eol\r
 479 </term>\r
 480 <listitem>\r
 481 <simpara>\r
 482         Ignore changes in whitespace at EOL.\r
 483 </simpara>\r
 484 </listitem>\r
 485 </varlistentry>\r
 486 <varlistentry>\r
 487 <term>\r
 488 -b\r
 489 </term>\r
 490 <term>\r
 491 --ignore-space-change\r
 492 </term>\r
 493 <listitem>\r
 494 <simpara>\r
 495         Ignore changes in amount of whitespace.  This ignores whitespace\r
 496         at line end, and considers all other sequences of one or\r
 497         more whitespace characters to be equivalent.\r
 498 </simpara>\r
 499 </listitem>\r
 500 </varlistentry>\r
 501 <varlistentry>\r
 502 <term>\r
 503 -w\r
 504 </term>\r
 505 <term>\r
 506 --ignore-all-space\r
 507 </term>\r
 508 <listitem>\r
 509 <simpara>\r
 510         Ignore whitespace when comparing lines.  This ignores\r
 511         differences even if one line has whitespace where the other\r
 512         line has none.\r
 513 </simpara>\r
 514 </listitem>\r
 515 </varlistentry>\r
 516 <varlistentry>\r
 517 <term>\r
 518 --inter-hunk-context=&lt;lines&gt;\r
 519 </term>\r
 520 <listitem>\r
 521 <simpara>\r
 522         Show the context between diff hunks, up to the specified number\r
 523         of lines, thereby fusing hunks that are close to each other.\r
 524 </simpara>\r
 525 </listitem>\r
 526 </varlistentry>\r
 527 <varlistentry>\r
 528 <term>\r
 529 -W\r
 530 </term>\r
 531 <term>\r
 532 --function-context\r
 533 </term>\r
 534 <listitem>\r
 535 <simpara>\r
 536         Show whole surrounding functions of changes.\r
 537 </simpara>\r
 538 </listitem>\r
 539 </varlistentry>\r
 540 <varlistentry>\r
 541 <term>\r
 542 --ext-diff\r
 543 </term>\r
 544 <listitem>\r
 545 <simpara>\r
 546         Allow an external diff helper to be executed. If you set an\r
 547         external diff driver with <xref linkend="gitattributes(5)" />, you need\r
 548         to use this option with <xref linkend="git-log(1)" /> and friends.\r
 549 </simpara>\r
 550 </listitem>\r
 551 </varlistentry>\r
 552 <varlistentry>\r
 553 <term>\r
 554 --no-ext-diff\r
 555 </term>\r
 556 <listitem>\r
 557 <simpara>\r
 558         Disallow external diff drivers.\r
 559 </simpara>\r
 560 </listitem>\r
 561 </varlistentry>\r
 562 <varlistentry>\r
 563 <term>\r
 564 --textconv\r
 565 </term>\r
 566 <term>\r
 567 --no-textconv\r
 568 </term>\r
 569 <listitem>\r
 570 <simpara>\r
 571         Allow (or disallow) external text conversion filters to be run\r
 572         when comparing binary files. See <xref linkend="gitattributes(5)" /> for\r
 573         details. Because textconv filters are typically a one-way\r
 574         conversion, the resulting diff is suitable for human\r
 575         consumption, but cannot be applied. For this reason, textconv\r
 576         filters are enabled by default only for <xref linkend="git-diff(1)" /> and\r
 577         <xref linkend="git-log(1)" />, but not for <xref linkend="git-format-patch(1)" /> or\r
 578         diff plumbing commands.\r
 579 </simpara>\r
 580 </listitem>\r
 581 </varlistentry>\r
 582 <varlistentry>\r
 583 <term>\r
 584 --ignore-submodules[=&lt;when&gt;]\r
 585 </term>\r
 586 <listitem>\r
 587 <simpara>\r
 588         Ignore changes to submodules in the diff generation. &lt;when&gt; can be\r
 589         either "none", "untracked", "dirty" or "all", which is the default\r
 590         Using "none" will consider the submodule modified when it either contains\r
 591         untracked or modified files or its HEAD differs from the commit recorded\r
 592         in the superproject and can be used to override any settings of the\r
 593         <emphasis>ignore</emphasis> option in <xref linkend="git-config(1)" /> or <xref linkend="gitmodules(5)" />. When\r
 594         "untracked" is used submodules are not considered dirty when they only\r
 595         contain untracked content (but they are still scanned for modified\r
 596         content). Using "dirty" ignores all changes to the work tree of submodules,\r
 597         only changes to the commits stored in the superproject are shown (this was\r
 598         the behavior until 1.7.0). Using "all" hides all changes to submodules.\r
 599 </simpara>\r
 600 </listitem>\r
 601 </varlistentry>\r
 602 <varlistentry>\r
 603 <term>\r
 604 --src-prefix=&lt;prefix&gt;\r
 605 </term>\r
 606 <listitem>\r
 607 <simpara>\r
 608         Show the given source prefix instead of "a/".\r
 609 </simpara>\r
 610 </listitem>\r
 611 </varlistentry>\r
 612 <varlistentry>\r
 613 <term>\r
 614 --dst-prefix=&lt;prefix&gt;\r
 615 </term>\r
 616 <listitem>\r
 617 <simpara>\r
 618         Show the given destination prefix instead of "b/".\r
 619 </simpara>\r
 620 </listitem>\r
 621 </varlistentry>\r
 622 <varlistentry>\r
 623 <term>\r
 624 --no-prefix\r
 625 </term>\r
 626 <listitem>\r
 627 <simpara>\r
 628         Do not show any source or destination prefix.\r
 629 </simpara>\r
 630 </listitem>\r
 631 </varlistentry>\r
 632 </variablelist>\r
 633 <simpara>For more detailed explanation on these common options, see also\r
 634 <xref linkend="gitdiffcore(7)" />.</simpara>\r
 635 <variablelist>\r
 636 <varlistentry>\r
 637 <term>\r
 638 -&lt;n&gt;\r
 639 </term>\r
 640 <listitem>\r
 641 <simpara>\r
 642         Prepare patches from the topmost &lt;n&gt; commits.\r
 643 </simpara>\r
 644 </listitem>\r
 645 </varlistentry>\r
 646 <varlistentry>\r
 647 <term>\r
 648 -o &lt;dir&gt;\r
 649 </term>\r
 650 <term>\r
 651 --output-directory &lt;dir&gt;\r
 652 </term>\r
 653 <listitem>\r
 654 <simpara>\r
 655         Use &lt;dir&gt; to store the resulting files, instead of the\r
 656         current working directory.\r
 657 </simpara>\r
 658 </listitem>\r
 659 </varlistentry>\r
 660 <varlistentry>\r
 661 <term>\r
 662 -n\r
 663 </term>\r
 664 <term>\r
 665 --numbered\r
 666 </term>\r
 667 <listitem>\r
 668 <simpara>\r
 669         Name output in <emphasis>[PATCH n/m]</emphasis> format, even with a single patch.\r
 670 </simpara>\r
 671 </listitem>\r
 672 </varlistentry>\r
 673 <varlistentry>\r
 674 <term>\r
 675 -N\r
 676 </term>\r
 677 <term>\r
 678 --no-numbered\r
 679 </term>\r
 680 <listitem>\r
 681 <simpara>\r
 682         Name output in <emphasis>[PATCH]</emphasis> format.\r
 683 </simpara>\r
 684 </listitem>\r
 685 </varlistentry>\r
 686 <varlistentry>\r
 687 <term>\r
 688 --start-number &lt;n&gt;\r
 689 </term>\r
 690 <listitem>\r
 691 <simpara>\r
 692         Start numbering the patches at &lt;n&gt; instead of 1.\r
 693 </simpara>\r
 694 </listitem>\r
 695 </varlistentry>\r
 696 <varlistentry>\r
 697 <term>\r
 698 --numbered-files\r
 699 </term>\r
 700 <listitem>\r
 701 <simpara>\r
 702         Output file names will be a simple number sequence\r
 703         without the default first line of the commit appended.\r
 704 </simpara>\r
 705 </listitem>\r
 706 </varlistentry>\r
 707 <varlistentry>\r
 708 <term>\r
 709 -k\r
 710 </term>\r
 711 <term>\r
 712 --keep-subject\r
 713 </term>\r
 714 <listitem>\r
 715 <simpara>\r
 716         Do not strip/add <emphasis>[PATCH]</emphasis> from the first line of the\r
 717         commit log message.\r
 718 </simpara>\r
 719 </listitem>\r
 720 </varlistentry>\r
 721 <varlistentry>\r
 722 <term>\r
 723 -s\r
 724 </term>\r
 725 <term>\r
 726 --signoff\r
 727 </term>\r
 728 <listitem>\r
 729 <simpara>\r
 730         Add <emphasis>Signed-off-by:</emphasis> line to the commit message, using\r
 731         the committer identity of yourself.\r
 732 </simpara>\r
 733 </listitem>\r
 734 </varlistentry>\r
 735 <varlistentry>\r
 736 <term>\r
 737 --stdout\r
 738 </term>\r
 739 <listitem>\r
 740 <simpara>\r
 741         Print all commits to the standard output in mbox format,\r
 742         instead of creating a file for each one.\r
 743 </simpara>\r
 744 </listitem>\r
 745 </varlistentry>\r
 746 <varlistentry>\r
 747 <term>\r
 748 --attach[=&lt;boundary&gt;]\r
 749 </term>\r
 750 <listitem>\r
 751 <simpara>\r
 752         Create multipart/mixed attachment, the first part of\r
 753         which is the commit message and the patch itself in the\r
 754         second part, with <emphasis>Content-Disposition: attachment</emphasis>.\r
 755 </simpara>\r
 756 </listitem>\r
 757 </varlistentry>\r
 758 <varlistentry>\r
 759 <term>\r
 760 --no-attach\r
 761 </term>\r
 762 <listitem>\r
 763 <simpara>\r
 764         Disable the creation of an attachment, overriding the\r
 765         configuration setting.\r
 766 </simpara>\r
 767 </listitem>\r
 768 </varlistentry>\r
 769 <varlistentry>\r
 770 <term>\r
 771 --inline[=&lt;boundary&gt;]\r
 772 </term>\r
 773 <listitem>\r
 774 <simpara>\r
 775         Create multipart/mixed attachment, the first part of\r
 776         which is the commit message and the patch itself in the\r
 777         second part, with <emphasis>Content-Disposition: inline</emphasis>.\r
 778 </simpara>\r
 779 </listitem>\r
 780 </varlistentry>\r
 781 <varlistentry>\r
 782 <term>\r
 783 --thread[=&lt;style&gt;]\r
 784 </term>\r
 785 <term>\r
 786 --no-thread\r
 787 </term>\r
 788 <listitem>\r
 789 <simpara>\r
 790         Controls addition of <emphasis>In-Reply-To</emphasis> and <emphasis>References</emphasis> headers to\r
 791         make the second and subsequent mails appear as replies to the\r
 792         first.  Also controls generation of the <emphasis>Message-Id</emphasis> header to\r
 793         reference.\r
 794 </simpara>\r
 795 <simpara>The optional &lt;style&gt; argument can be either <emphasis>shallow</emphasis> or <emphasis>deep</emphasis>.\r
 796 <emphasis>shallow</emphasis> threading makes every mail a reply to the head of the\r
 797 series, where the head is chosen from the cover letter, the\r
 798 <emphasis>--in-reply-to</emphasis>, and the first patch mail, in this order.  <emphasis>deep</emphasis>\r
 799 threading makes every mail a reply to the previous one.</simpara>\r
 800 <simpara>The default is <emphasis>--no-thread</emphasis>, unless the <emphasis>format.thread</emphasis> configuration\r
 801 is set.  If <emphasis>--thread</emphasis> is specified without a style, it defaults to the\r
 802 style specified by <emphasis>format.thread</emphasis> if any, or else <emphasis>shallow</emphasis>.</simpara>\r
 803 <simpara>Beware that the default for <emphasis>git send-email</emphasis> is to thread emails\r
 804 itself.  If you want <emphasis>git format-patch</emphasis> to take care of threading, you\r
 805 will want to ensure that threading is disabled for <emphasis>git send-email</emphasis>.</simpara>\r
 806 </listitem>\r
 807 </varlistentry>\r
 808 <varlistentry>\r
 809 <term>\r
 810 --in-reply-to=Message-Id\r
 811 </term>\r
 812 <listitem>\r
 813 <simpara>\r
 814         Make the first mail (or all the mails with <emphasis>--no-thread</emphasis>) appear as a\r
 815         reply to the given Message-Id, which avoids breaking threads to\r
 816         provide a new patch series.\r
 817 </simpara>\r
 818 </listitem>\r
 819 </varlistentry>\r
 820 <varlistentry>\r
 821 <term>\r
 822 --ignore-if-in-upstream\r
 823 </term>\r
 824 <listitem>\r
 825 <simpara>\r
 826         Do not include a patch that matches a commit in\r
 827         &lt;until&gt;..&lt;since&gt;.  This will examine all patches reachable\r
 828         from &lt;since&gt; but not from &lt;until&gt; and compare them with the\r
 829         patches being generated, and any patch that matches is\r
 830         ignored.\r
 831 </simpara>\r
 832 </listitem>\r
 833 </varlistentry>\r
 834 <varlistentry>\r
 835 <term>\r
 836 --subject-prefix=&lt;Subject-Prefix&gt;\r
 837 </term>\r
 838 <listitem>\r
 839 <simpara>\r
 840         Instead of the standard <emphasis>[PATCH]</emphasis> prefix in the subject\r
 841         line, instead use <emphasis>[&lt;Subject-Prefix&gt;]</emphasis>. This\r
 842         allows for useful naming of a patch series, and can be\r
 843         combined with the <emphasis>--numbered</emphasis> option.\r
 844 </simpara>\r
 845 </listitem>\r
 846 </varlistentry>\r
 847 <varlistentry>\r
 848 <term>\r
 849 --to=&lt;email&gt;\r
 850 </term>\r
 851 <listitem>\r
 852 <simpara>\r
 853         Add a <emphasis>To:</emphasis> header to the email headers. This is in addition\r
 854         to any configured headers, and may be used multiple times.\r
 855         The negated form <emphasis>--no-to</emphasis> discards all <emphasis>To:</emphasis> headers added so\r
 856         far (from config or command line).\r
 857 </simpara>\r
 858 </listitem>\r
 859 </varlistentry>\r
 860 <varlistentry>\r
 861 <term>\r
 862 --cc=&lt;email&gt;\r
 863 </term>\r
 864 <listitem>\r
 865 <simpara>\r
 866         Add a <emphasis>Cc:</emphasis> header to the email headers. This is in addition\r
 867         to any configured headers, and may be used multiple times.\r
 868         The negated form <emphasis>--no-cc</emphasis> discards all <emphasis>Cc:</emphasis> headers added so\r
 869         far (from config or command line).\r
 870 </simpara>\r
 871 </listitem>\r
 872 </varlistentry>\r
 873 <varlistentry>\r
 874 <term>\r
 875 --add-header=&lt;header&gt;\r
 876 </term>\r
 877 <listitem>\r
 878 <simpara>\r
 879         Add an arbitrary header to the email headers.  This is in addition\r
 880         to any configured headers, and may be used multiple times.\r
 881         For example, <emphasis>--add-header="Organization: git-foo"</emphasis>.\r
 882         The negated form <emphasis>--no-add-header</emphasis> discards <emphasis role="strong">all</emphasis> (<emphasis>To:</emphasis>,\r
 883         <emphasis>Cc:</emphasis>, and custom) headers added so far from config or command\r
 884         line.\r
 885 </simpara>\r
 886 </listitem>\r
 887 </varlistentry>\r
 888 <varlistentry>\r
 889 <term>\r
 890 --cover-letter\r
 891 </term>\r
 892 <listitem>\r
 893 <simpara>\r
 894         In addition to the patches, generate a cover letter file\r
 895         containing the shortlog and the overall diffstat.  You can\r
 896         fill in a description in the file before sending it out.\r
 897 </simpara>\r
 898 </listitem>\r
 899 </varlistentry>\r
 900 <varlistentry>\r
 901 <term>\r
 902 --[no]-signature=&lt;signature&gt;\r
 903 </term>\r
 904 <listitem>\r
 905 <simpara>\r
 906         Add a signature to each message produced. Per RFC 3676 the signature\r
 907         is separated from the body by a line with '-- ' on it. If the\r
 908         signature option is omitted the signature defaults to the git version\r
 909         number.\r
 910 </simpara>\r
 911 </listitem>\r
 912 </varlistentry>\r
 913 <varlistentry>\r
 914 <term>\r
 915 --suffix=.&lt;sfx&gt;\r
 916 </term>\r
 917 <listitem>\r
 918 <simpara>\r
 919         Instead of using <emphasis>.patch</emphasis> as the suffix for generated\r
 920         filenames, use specified suffix.  A common alternative is\r
 921         <emphasis>--suffix=.txt</emphasis>.  Leaving this empty will remove the <emphasis>.patch</emphasis>\r
 922         suffix.\r
 923 </simpara>\r
 924 <simpara>Note that the leading character does not have to be a dot; for example,\r
 925 you can use <emphasis>--suffix=-patch</emphasis> to get <emphasis>0001-description-of-my-change-patch</emphasis>.</simpara>\r
 926 </listitem>\r
 927 </varlistentry>\r
 928 <varlistentry>\r
 929 <term>\r
 930 --quiet\r
 931 </term>\r
 932 <listitem>\r
 933 <simpara>\r
 934         Do not print the names of the generated files to standard output.\r
 935 </simpara>\r
 936 </listitem>\r
 937 </varlistentry>\r
 938 <varlistentry>\r
 939 <term>\r
 940 --no-binary\r
 941 </term>\r
 942 <listitem>\r
 943 <simpara>\r
 944         Do not output contents of changes in binary files, instead\r
 945         display a notice that those files changed.  Patches generated\r
 946         using this option cannot be applied properly, but they are\r
 947         still useful for code review.\r
 948 </simpara>\r
 949 </listitem>\r
 950 </varlistentry>\r
 951 <varlistentry>\r
 952 <term>\r
 953 --root\r
 954 </term>\r
 955 <listitem>\r
 956 <simpara>\r
 957         Treat the revision argument as a &lt;revision range&gt;, even if it\r
 958         is just a single commit (that would normally be treated as a\r
 959         &lt;since&gt;).  Note that root commits included in the specified\r
 960         range are always formatted as creation patches, independently\r
 961         of this flag.\r
 962 </simpara>\r
 963 </listitem>\r
 964 </varlistentry>\r
 965 </variablelist>\r
 966 </simplesect>\r
 967 <simplesect id="_configuration">\r
 968 <title>CONFIGURATION</title>\r
 969 <simpara>You can specify extra mail header lines to be added to each message,\r
 970 defaults for the subject prefix and file suffix, number patches when\r
 971 outputting more than one patch, add "To" or "Cc:" headers, configure\r
 972 attachments, and sign off patches with configuration variables.</simpara>\r
 973 <screen>[format]\r
 974         headers = "Organization: git-foo\n"\r
 975         subjectprefix = CHANGE\r
 976         suffix = .txt\r
 977         numbered = auto\r
 978         to = &lt;email&gt;\r
 979         cc = &lt;email&gt;\r
 980         attach [ = mime-boundary-string ]\r
 981         signoff = true</screen>\r
 982 </simplesect>\r
 983 <simplesect id="_discussion">\r
 984 <title>DISCUSSION</title>\r
 985 <simpara>The patch produced by <emphasis>git format-patch</emphasis> is in UNIX mailbox format,\r
 986 with a fixed "magic" time stamp to indicate that the file is output\r
 987 from format-patch rather than a real mailbox, like so:</simpara>\r
 988 <screen>From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001\r
 989 From: Tony Luck &lt;tony.luck@intel.com&gt;\r
 990 Date: Tue, 13 Jul 2010 11:42:54 -0700\r
 991 Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=\r
 992  =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=\r
 993 MIME-Version: 1.0\r
 994 Content-Type: text/plain; charset=UTF-8\r
 995 Content-Transfer-Encoding: 8bit\r
 996 \r
 997 arch/arm config files were slimmed down using a python script\r
 998 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)\r
 999 \r
1000 Do the same for ia64 so we can have sleek &amp; trim looking\r
1001 ...</screen>\r
1002 <simpara>Typically it will be placed in a MUA's drafts folder, edited to add\r
1003 timely commentary that should not go in the changelog after the three\r
1004 dashes, and then sent as a message whose body, in our example, starts\r
1005 with "arch/arm config files were&#8230;".  On the receiving end, readers\r
1006 can save interesting patches in a UNIX mailbox and apply them with\r
1007 <xref linkend="git-am(1)" />.</simpara>\r
1008 <simpara>When a patch is part of an ongoing discussion, the patch generated by\r
1009 <emphasis>git format-patch</emphasis> can be tweaked to take advantage of the <emphasis>git am\r
1010 --scissors</emphasis> feature.  After your response to the discussion comes a\r
1011 line that consists solely of "<emphasis>-- &gt;8 --</emphasis>" (scissors and perforation),\r
1012 followed by the patch with unnecessary header fields removed:</simpara>\r
1013 <screen>...\r
1014 &gt; So we should do such-and-such.\r
1015 \r
1016 Makes sense to me.  How about this patch?\r
1017 \r
1018 -- &gt;8 --\r
1019 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet\r
1020 \r
1021 arch/arm config files were slimmed down using a python script\r
1022 ...</screen>\r
1023 <simpara>When sending a patch this way, most often you are sending your own\r
1024 patch, so in addition to the "<emphasis>From $SHA1 $magic_timestamp</emphasis>" marker you\r
1025 should omit <emphasis>From:</emphasis> and <emphasis>Date:</emphasis> lines from the patch file.  The patch\r
1026 title is likely to be different from the subject of the discussion the\r
1027 patch is in response to, so it is likely that you would want to keep\r
1028 the Subject: line, like the example above.</simpara>\r
1029 <section id="_checking_for_patch_corruption">\r
1030 <title>Checking for patch corruption</title>\r
1031 <simpara>Many mailers if not set up properly will corrupt whitespace.  Here are\r
1032 two common types of corruption:</simpara>\r
1033 <itemizedlist>\r
1034 <listitem>\r
1035 <simpara>\r
1036 Empty context lines that do not have <emphasis>any</emphasis> whitespace.\r
1037 </simpara>\r
1038 </listitem>\r
1039 <listitem>\r
1040 <simpara>\r
1041 Non-empty context lines that have one extra whitespace at the\r
1042   beginning.\r
1043 </simpara>\r
1044 </listitem>\r
1045 </itemizedlist>\r
1046 <simpara>One way to test if your MUA is set up correctly is:</simpara>\r
1047 <itemizedlist>\r
1048 <listitem>\r
1049 <simpara>\r
1050 Send the patch to yourself, exactly the way you would, except\r
1051   with To: and Cc: lines that do not contain the list and\r
1052   maintainer address.\r
1053 </simpara>\r
1054 </listitem>\r
1055 <listitem>\r
1056 <simpara>\r
1057 Save that patch to a file in UNIX mailbox format.  Call it a.patch,\r
1058   say.\r
1059 </simpara>\r
1060 </listitem>\r
1061 <listitem>\r
1062 <simpara>\r
1063 Apply it:\r
1064 </simpara>\r
1065 <literallayout class="monospaced">$ git fetch &lt;project&gt; master:test-apply\r
1066 $ git checkout test-apply\r
1067 $ git reset --hard\r
1068 $ git am a.patch</literallayout>\r
1069 </listitem>\r
1070 </itemizedlist>\r
1071 <simpara>If it does not apply correctly, there can be various reasons.</simpara>\r
1072 <itemizedlist>\r
1073 <listitem>\r
1074 <simpara>\r
1075 The patch itself does not apply cleanly.  That is <emphasis>bad</emphasis> but\r
1076   does not have much to do with your MUA.  You might want to rebase\r
1077   the patch with <xref linkend="git-rebase(1)" /> before regenerating it in\r
1078   this case.\r
1079 </simpara>\r
1080 </listitem>\r
1081 <listitem>\r
1082 <simpara>\r
1083 The MUA corrupted your patch; "am" would complain that\r
1084   the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and\r
1085   see what <emphasis>patch</emphasis> file contains and check for the common\r
1086   corruption patterns mentioned above.\r
1087 </simpara>\r
1088 </listitem>\r
1089 <listitem>\r
1090 <simpara>\r
1091 While at it, check the <emphasis>info</emphasis> and <emphasis>final-commit</emphasis> files as well.\r
1092   If what is in <emphasis>final-commit</emphasis> is not exactly what you would want to\r
1093   see in the commit log message, it is very likely that the\r
1094   receiver would end up hand editing the log message when applying\r
1095   your patch.  Things like "Hi, this is my first patch.\n" in the\r
1096   patch e-mail should come after the three-dash line that signals\r
1097   the end of the commit message.\r
1098 </simpara>\r
1099 </listitem>\r
1100 </itemizedlist>\r
1101 </section>\r
1102 </simplesect>\r
1103 <simplesect id="_mua_specific_hints">\r
1104 <title>MUA-SPECIFIC HINTS</title>\r
1105 <simpara>Here are some hints on how to successfully submit patches inline using\r
1106 various mailers.</simpara>\r
1107 <section id="_gmail">\r
1108 <title>GMail</title>\r
1109 <simpara>GMail does not have any way to turn off line wrapping in the web\r
1110 interface, so it will mangle any emails that you send.  You can however\r
1111 use "git send-email" and send your patches through the GMail SMTP server, or\r
1112 use any IMAP email client to connect to the google IMAP server and forward\r
1113 the emails through that.</simpara>\r
1114 <simpara>For hints on using <emphasis>git send-email</emphasis> to send your patches through the\r
1115 GMail SMTP server, see the EXAMPLE section of <xref linkend="git-send-email(1)" />.</simpara>\r
1116 <simpara>For hints on submission using the IMAP interface, see the EXAMPLE\r
1117 section of <xref linkend="git-imap-send(1)" />.</simpara>\r
1118 </section>\r
1119 <section id="_thunderbird">\r
1120 <title>Thunderbird</title>\r
1121 <simpara>By default, Thunderbird will both wrap emails as well as flag\r
1122 them as being <emphasis>format=flowed</emphasis>, both of which will make the\r
1123 resulting email unusable by git.</simpara>\r
1124 <simpara>There are three different approaches: use an add-on to turn off line wraps,\r
1125 configure Thunderbird to not mangle patches, or use\r
1126 an external editor to keep Thunderbird from mangling the patches.</simpara>\r
1127 <section id="_approach_1_add_on">\r
1128 <title>Approach #1 (add-on)</title>\r
1129 <simpara>Install the Toggle Word Wrap add-on that is available from\r
1130 <ulink url="https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/">https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/</ulink>\r
1131 It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu\r
1132 that you can tick off. Now you can compose the message as you otherwise do\r
1133 (cut + paste, <emphasis>git format-patch</emphasis> | <emphasis>git imap-send</emphasis>, etc), but you have to\r
1134 insert line breaks manually in any text that you type.</simpara>\r
1135 </section>\r
1136 <section id="_approach_2_configuration">\r
1137 <title>Approach #2 (configuration)</title>\r
1138 <simpara>Three steps:</simpara>\r
1139 <orderedlist numeration="arabic">\r
1140 <listitem>\r
1141 <simpara>\r
1142 Configure your mail server composition as plain text:\r
1143    Edit&#8230;Account Settings&#8230;Composition &amp; Addressing,\r
1144    uncheck "Compose Messages in HTML".\r
1145 </simpara>\r
1146 </listitem>\r
1147 <listitem>\r
1148 <simpara>\r
1149 Configure your general composition window to not wrap.\r
1150 </simpara>\r
1151 <simpara>In Thunderbird 2:\r
1152 Edit..Preferences..Composition, wrap plain text messages at 0</simpara>\r
1153 <simpara>In Thunderbird 3:\r
1154 Edit..Preferences..Advanced..Config Editor.  Search for\r
1155 "mail.wrap_long_lines".\r
1156 Toggle it to make sure it is set to <emphasis>false</emphasis>.</simpara>\r
1157 </listitem>\r
1158 <listitem>\r
1159 <simpara>\r
1160 Disable the use of format=flowed:\r
1161 Edit..Preferences..Advanced..Config Editor.  Search for\r
1162 "mailnews.send_plaintext_flowed".\r
1163 Toggle it to make sure it is set to <emphasis>false</emphasis>.\r
1164 </simpara>\r
1165 </listitem>\r
1166 </orderedlist>\r
1167 <simpara>After that is done, you should be able to compose email as you\r
1168 otherwise would (cut + paste, <emphasis>git format-patch</emphasis> | <emphasis>git imap-send</emphasis>, etc),\r
1169 and the patches will not be mangled.</simpara>\r
1170 </section>\r
1171 <section id="_approach_3_external_editor">\r
1172 <title>Approach #3 (external editor)</title>\r
1173 <simpara>The following Thunderbird extensions are needed:\r
1174 AboutConfig from <ulink url="http://aboutconfig.mozdev.org/">http://aboutconfig.mozdev.org/</ulink> and\r
1175 External Editor from <ulink url="http://globs.org/articles.php?lng=en&amp;pg=8">http://globs.org/articles.php?lng=en&amp;pg=8</ulink></simpara>\r
1176 <orderedlist numeration="arabic">\r
1177 <listitem>\r
1178 <simpara>\r
1179 Prepare the patch as a text file using your method of choice.\r
1180 </simpara>\r
1181 </listitem>\r
1182 <listitem>\r
1183 <simpara>\r
1184 Before opening a compose window, use Edit&#8594;Account Settings to\r
1185    uncheck the "Compose messages in HTML format" setting in the\r
1186    "Composition &amp; Addressing" panel of the account to be used to\r
1187    send the patch.\r
1188 </simpara>\r
1189 </listitem>\r
1190 <listitem>\r
1191 <simpara>\r
1192 In the main Thunderbird window, <emphasis>before</emphasis> you open the compose\r
1193    window for the patch, use Tools&#8594;about:config to set the\r
1194    following to the indicated values:\r
1195 </simpara>\r
1196 <screen>        mailnews.send_plaintext_flowed  =&gt; false\r
1197         mailnews.wraplength             =&gt; 0</screen>\r
1198 </listitem>\r
1199 <listitem>\r
1200 <simpara>\r
1201 Open a compose window and click the external editor icon.\r
1202 </simpara>\r
1203 </listitem>\r
1204 <listitem>\r
1205 <simpara>\r
1206 In the external editor window, read in the patch file and exit\r
1207    the editor normally.\r
1208 </simpara>\r
1209 </listitem>\r
1210 </orderedlist>\r
1211 <simpara>Side note: it may be possible to do step 2 with\r
1212 about:config and the following settings but no one's tried yet.</simpara>\r
1213 <screen>        mail.html_compose                       =&gt; false\r
1214         mail.identity.default.compose_html      =&gt; false\r
1215         mail.identity.id?.compose_html          =&gt; false</screen>\r
1216 <simpara>There is a script in contrib/thunderbird-patch-inline which can help\r
1217 you include patches with Thunderbird in an easy way. To use it, do the\r
1218 steps above and then use the script as the external editor.</simpara>\r
1219 </section>\r
1220 </section>\r
1221 <section id="_kmail">\r
1222 <title>KMail</title>\r
1223 <simpara>This should help you to submit patches inline using KMail.</simpara>\r
1224 <orderedlist numeration="arabic">\r
1225 <listitem>\r
1226 <simpara>\r
1227 Prepare the patch as a text file.\r
1228 </simpara>\r
1229 </listitem>\r
1230 <listitem>\r
1231 <simpara>\r
1232 Click on New Mail.\r
1233 </simpara>\r
1234 </listitem>\r
1235 <listitem>\r
1236 <simpara>\r
1237 Go under "Options" in the Composer window and be sure that\r
1238    "Word wrap" is not set.\r
1239 </simpara>\r
1240 </listitem>\r
1241 <listitem>\r
1242 <simpara>\r
1243 Use Message &#8594; Insert file&#8230; and insert the patch.\r
1244 </simpara>\r
1245 </listitem>\r
1246 <listitem>\r
1247 <simpara>\r
1248 Back in the compose window: add whatever other text you wish to the\r
1249    message, complete the addressing and subject fields, and press send.\r
1250 </simpara>\r
1251 </listitem>\r
1252 </orderedlist>\r
1253 </section>\r
1254 </simplesect>\r
1255 <simplesect id="_examples">\r
1256 <title>EXAMPLES</title>\r
1257 <itemizedlist>\r
1258 <listitem>\r
1259 <simpara>\r
1260 Extract commits between revisions R1 and R2, and apply them on top of\r
1261 the current branch using <emphasis>git am</emphasis> to cherry-pick them:\r
1262 </simpara>\r
1263 <screen>$ git format-patch -k --stdout R1..R2 | git am -3 -k</screen>\r
1264 </listitem>\r
1265 <listitem>\r
1266 <simpara>\r
1267 Extract all commits which are in the current branch but not in the\r
1268 origin branch:\r
1269 </simpara>\r
1270 <screen>$ git format-patch origin</screen>\r
1271 <simpara>For each commit a separate file is created in the current directory.</simpara>\r
1272 </listitem>\r
1273 <listitem>\r
1274 <simpara>\r
1275 Extract all commits that lead to <emphasis>origin</emphasis> since the inception of the\r
1276 project:\r
1277 </simpara>\r
1278 <screen>$ git format-patch --root origin</screen>\r
1279 </listitem>\r
1280 <listitem>\r
1281 <simpara>\r
1282 The same as the previous one:\r
1283 </simpara>\r
1284 <screen>$ git format-patch -M -B origin</screen>\r
1285 <simpara>Additionally, it detects and handles renames and complete rewrites\r
1286 intelligently to produce a renaming patch.  A renaming patch reduces\r
1287 the amount of text output, and generally makes it easier to review.\r
1288 Note that non-git "patch" programs won't understand renaming patches, so\r
1289 use it only when you know the recipient uses git to apply your patch.</simpara>\r
1290 </listitem>\r
1291 <listitem>\r
1292 <simpara>\r
1293 Extract three topmost commits from the current branch and format them\r
1294 as e-mailable patches:\r
1295 </simpara>\r
1296 <screen>$ git format-patch -3</screen>\r
1297 </listitem>\r
1298 </itemizedlist>\r
1299 </simplesect>\r
1300 <simplesect id="_see_also">\r
1301 <title>SEE ALSO</title>\r
1302 <simpara><xref linkend="git-am(1)" />, <xref linkend="git-send-email(1)" /></simpara>\r
1303 </simplesect>\r
1304 <simplesect id="_git">\r
1305 <title>GIT</title>\r
1306 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
1307 </simplesect>\r
1308 </article>\r