1git-format-patch(1) 2=================== 3 4NAME 5---- 6git-format-patch - Prepare patches for e-mail submission 7 8 9SYNOPSIS 10-------- 11[verse] 12'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout] 13 [--no-thread | --thread[=<style>]] 14 [(--attach|--inline)[=<boundary>] | --no-attach] 15 [-s | --signoff] 16 [--signature=<signature> | --no-signature] 17 [--signature-file=<file>] 18 [-n | --numbered | -N | --no-numbered] 19 [--start-number <n>] [--numbered-files] 20 [--in-reply-to=Message-Id] [--suffix=.<sfx>] 21 [--ignore-if-in-upstream] 22 [--subject-prefix=Subject-Prefix] [(--reroll-count|-v) <n>] 23 [--to=<email>] [--cc=<email>] 24 [--[no-]cover-letter] [--quiet] [--notes[=<ref>]] 25 [<common diff options>] 26 [ <since> | <revision range> ] 27 28DESCRIPTION 29----------- 30 31Prepare each commit with its patch in 32one file per commit, formatted to resemble UNIX mailbox format. 33The output of this command is convenient for e-mail submission or 34for use with 'git am'. 35 36There are two ways to specify which commits to operate on. 37 381. A single commit, <since>, specifies that the commits leading 39 to the tip of the current branch that are not in the history 40 that leads to the <since> to be output. 41 422. Generic <revision range> expression (see "SPECIFYING 43 REVISIONS" section in linkgit:gitrevisions[7]) means the 44 commits in the specified range. 45 46The first rule takes precedence in the case of a single <commit>. To 47apply the second rule, i.e., format everything since the beginning of 48history up until <commit>, use the '\--root' option: `git format-patch 49--root <commit>`. If you want to format only <commit> itself, you 50can do this with `git format-patch -1 <commit>`. 51 52By default, each output file is numbered sequentially from 1, and uses the 53first line of the commit message (massaged for pathname safety) as 54the filename. With the `--numbered-files` option, the output file names 55will only be numbers, without the first line of the commit appended. 56The names of the output files are printed to standard 57output, unless the `--stdout` option is specified. 58 59If `-o` is specified, output files are created in <dir>. Otherwise 60they are created in the current working directory. 61 62By default, the subject of a single patch is "[PATCH] " followed by 63the concatenation of lines from the commit message up to the first blank 64line (see the DISCUSSION section of linkgit:git-commit[1]). 65 66When multiple patches are output, the subject prefix will instead be 67"[PATCH n/m] ". To force 1/1 to be added for a single patch, use `-n`. 68To omit patch numbers from the subject, use `-N`. 69 70If given `--thread`, `git-format-patch` will generate `In-Reply-To` and 71`References` headers to make the second and subsequent patch mails appear 72as replies to the first mail; this also generates a `Message-Id` header to 73reference. 74 75OPTIONS 76------- 77:git-format-patch: 1 78include::diff-options.txt[] 79 80-<n>:: 81 Prepare patches from the topmost <n> commits. 82 83-o <dir>:: 84--output-directory <dir>:: 85 Use <dir> to store the resulting files, instead of the 86 current working directory. 87 88-n:: 89--numbered:: 90 Name output in '[PATCH n/m]' format, even with a single patch. 91 92-N:: 93--no-numbered:: 94 Name output in '[PATCH]' format. 95 96--start-number <n>:: 97 Start numbering the patches at <n> instead of 1. 98 99--numbered-files:: 100 Output file names will be a simple number sequence 101 without the default first line of the commit appended. 102 103-k:: 104--keep-subject:: 105 Do not strip/add '[PATCH]' from the first line of the 106 commit log message. 107 108-s:: 109--signoff:: 110 Add `Signed-off-by:` line to the commit message, using 111 the committer identity of yourself. 112 See the signoff option in linkgit:git-commit[1] for more information. 113 114--stdout:: 115 Print all commits to the standard output in mbox format, 116 instead of creating a file for each one. 117 118--attach[=<boundary>]:: 119 Create multipart/mixed attachment, the first part of 120 which is the commit message and the patch itself in the 121 second part, with `Content-Disposition: attachment`. 122 123--no-attach:: 124 Disable the creation of an attachment, overriding the 125 configuration setting. 126 127--inline[=<boundary>]:: 128 Create multipart/mixed attachment, the first part of 129 which is the commit message and the patch itself in the 130 second part, with `Content-Disposition: inline`. 131 132--thread[=<style>]:: 133--no-thread:: 134 Controls addition of `In-Reply-To` and `References` headers to 135 make the second and subsequent mails appear as replies to the 136 first. Also controls generation of the `Message-Id` header to 137 reference. 138+ 139The optional <style> argument can be either `shallow` or `deep`. 140'shallow' threading makes every mail a reply to the head of the 141series, where the head is chosen from the cover letter, the 142`--in-reply-to`, and the first patch mail, in this order. 'deep' 143threading makes every mail a reply to the previous one. 144+ 145The default is `--no-thread`, unless the 'format.thread' configuration 146is set. If `--thread` is specified without a style, it defaults to the 147style specified by 'format.thread' if any, or else `shallow`. 148+ 149Beware that the default for 'git send-email' is to thread emails 150itself. If you want `git format-patch` to take care of threading, you 151will want to ensure that threading is disabled for `git send-email`. 152 153--in-reply-to=Message-Id:: 154 Make the first mail (or all the mails with `--no-thread`) appear as a 155 reply to the given Message-Id, which avoids breaking threads to 156 provide a new patch series. 157 158--ignore-if-in-upstream:: 159 Do not include a patch that matches a commit in 160 <until>..<since>. This will examine all patches reachable 161 from <since> but not from <until> and compare them with the 162 patches being generated, and any patch that matches is 163 ignored. 164 165--subject-prefix=<Subject-Prefix>:: 166 Instead of the standard '[PATCH]' prefix in the subject 167 line, instead use '[<Subject-Prefix>]'. This 168 allows for useful naming of a patch series, and can be 169 combined with the `--numbered` option. 170 171-v <n>:: 172--reroll-count=<n>:: 173 Mark the series as the <n>-th iteration of the topic. The 174 output filenames have `v<n>` prepended to them, and the 175 subject prefix ("PATCH" by default, but configurable via the 176 `--subject-prefix` option) has ` v<n>` appended to it. E.g. 177 `--reroll-count=4` may produce `v4-0001-add-makefile.patch` 178 file that has "Subject: [PATCH v4 1/20] Add makefile" in it. 179 180--to=<email>:: 181 Add a `To:` header to the email headers. This is in addition 182 to any configured headers, and may be used multiple times. 183 The negated form `--no-to` discards all `To:` headers added so 184 far (from config or command line). 185 186--cc=<email>:: 187 Add a `Cc:` header to the email headers. This is in addition 188 to any configured headers, and may be used multiple times. 189 The negated form `--no-cc` discards all `Cc:` headers added so 190 far (from config or command line). 191 192--from:: 193--from=<ident>:: 194 Use `ident` in the `From:` header of each commit email. If the 195 author ident of the commit is not textually identical to the 196 provided `ident`, place a `From:` header in the body of the 197 message with the original author. If no `ident` is given, use 198 the committer ident. 199+ 200Note that this option is only useful if you are actually sending the 201emails and want to identify yourself as the sender, but retain the 202original author (and `git am` will correctly pick up the in-body 203header). Note also that `git send-email` already handles this 204transformation for you, and this option should not be used if you are 205feeding the result to `git send-email`. 206 207--add-header=<header>:: 208 Add an arbitrary header to the email headers. This is in addition 209 to any configured headers, and may be used multiple times. 210 For example, `--add-header="Organization: git-foo"`. 211 The negated form `--no-add-header` discards *all* (`To:`, 212 `Cc:`, and custom) headers added so far from config or command 213 line. 214 215--[no-]cover-letter:: 216 In addition to the patches, generate a cover letter file 217 containing the branch description, shortlog and the overall diffstat. You can 218 fill in a description in the file before sending it out. 219 220--notes[=<ref>]:: 221 Append the notes (see linkgit:git-notes[1]) for the commit 222 after the three-dash line. 223+ 224The expected use case of this is to write supporting explanation for 225the commit that does not belong to the commit log message proper, 226and include it with the patch submission. While one can simply write 227these explanations after `format-patch` has run but before sending, 228keeping them as Git notes allows them to be maintained between versions 229of the patch series (but see the discussion of the `notes.rewrite` 230configuration options in linkgit:git-notes[1] to use this workflow). 231 232--[no]-signature=<signature>:: 233 Add a signature to each message produced. Per RFC 3676 the signature 234 is separated from the body by a line with '-- ' on it. If the 235 signature option is omitted the signature defaults to the Git version 236 number. 237 238--signature-file=<file>:: 239 Works just like --signature except the signature is read from a file. 240 241--suffix=.<sfx>:: 242 Instead of using `.patch` as the suffix for generated 243 filenames, use specified suffix. A common alternative is 244 `--suffix=.txt`. Leaving this empty will remove the `.patch` 245 suffix. 246+ 247Note that the leading character does not have to be a dot; for example, 248you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. 249 250-q:: 251--quiet:: 252 Do not print the names of the generated files to standard output. 253 254--no-binary:: 255 Do not output contents of changes in binary files, instead 256 display a notice that those files changed. Patches generated 257 using this option cannot be applied properly, but they are 258 still useful for code review. 259 260--root:: 261 Treat the revision argument as a <revision range>, even if it 262 is just a single commit (that would normally be treated as a 263 <since>). Note that root commits included in the specified 264 range are always formatted as creation patches, independently 265 of this flag. 266 267CONFIGURATION 268------------- 269You can specify extra mail header lines to be added to each message, 270defaults for the subject prefix and file suffix, number patches when 271outputting more than one patch, add "To" or "Cc:" headers, configure 272attachments, and sign off patches with configuration variables. 273 274------------ 275[format] 276 headers = "Organization: git-foo\n" 277 subjectPrefix = CHANGE 278 suffix = .txt 279 numbered = auto 280 to = <email> 281 cc = <email> 282 attach [ = mime-boundary-string ] 283 signOff = true 284 coverletter = auto 285------------ 286 287 288DISCUSSION 289---------- 290 291The patch produced by 'git format-patch' is in UNIX mailbox format, 292with a fixed "magic" time stamp to indicate that the file is output 293from format-patch rather than a real mailbox, like so: 294 295------------ 296From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001 297From: Tony Luck <tony.luck@intel.com> 298Date: Tue, 13 Jul 2010 11:42:54 -0700 299Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?= 300 =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?= 301MIME-Version: 1.0 302Content-Type: text/plain; charset=UTF-8 303Content-Transfer-Encoding: 8bit 304 305arch/arm config files were slimmed down using a python script 306(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment) 307 308Do the same for ia64 so we can have sleek & trim looking 309... 310------------ 311 312Typically it will be placed in a MUA's drafts folder, edited to add 313timely commentary that should not go in the changelog after the three 314dashes, and then sent as a message whose body, in our example, starts 315with "arch/arm config files were...". On the receiving end, readers 316can save interesting patches in a UNIX mailbox and apply them with 317linkgit:git-am[1]. 318 319When a patch is part of an ongoing discussion, the patch generated by 320'git format-patch' can be tweaked to take advantage of the 'git am 321--scissors' feature. After your response to the discussion comes a 322line that consists solely of "`-- >8 --`" (scissors and perforation), 323followed by the patch with unnecessary header fields removed: 324 325------------ 326... 327> So we should do such-and-such. 328 329Makes sense to me. How about this patch? 330 331-- >8 -- 332Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet 333 334arch/arm config files were slimmed down using a python script 335... 336------------ 337 338When sending a patch this way, most often you are sending your own 339patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you 340should omit `From:` and `Date:` lines from the patch file. The patch 341title is likely to be different from the subject of the discussion the 342patch is in response to, so it is likely that you would want to keep 343the Subject: line, like the example above. 344 345Checking for patch corruption 346~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 347Many mailers if not set up properly will corrupt whitespace. Here are 348two common types of corruption: 349 350* Empty context lines that do not have _any_ whitespace. 351 352* Non-empty context lines that have one extra whitespace at the 353 beginning. 354 355One way to test if your MUA is set up correctly is: 356 357* Send the patch to yourself, exactly the way you would, except 358 with To: and Cc: lines that do not contain the list and 359 maintainer address. 360 361* Save that patch to a file in UNIX mailbox format. Call it a.patch, 362 say. 363 364* Apply it: 365 366 $ git fetch <project> master:test-apply 367 $ git checkout test-apply 368 $ git reset --hard 369 $ git am a.patch 370 371If it does not apply correctly, there can be various reasons. 372 373* The patch itself does not apply cleanly. That is _bad_ but 374 does not have much to do with your MUA. You might want to rebase 375 the patch with linkgit:git-rebase[1] before regenerating it in 376 this case. 377 378* The MUA corrupted your patch; "am" would complain that 379 the patch does not apply. Look in the .git/rebase-apply/ subdirectory and 380 see what 'patch' file contains and check for the common 381 corruption patterns mentioned above. 382 383* While at it, check the 'info' and 'final-commit' files as well. 384 If what is in 'final-commit' is not exactly what you would want to 385 see in the commit log message, it is very likely that the 386 receiver would end up hand editing the log message when applying 387 your patch. Things like "Hi, this is my first patch.\n" in the 388 patch e-mail should come after the three-dash line that signals 389 the end of the commit message. 390 391MUA-SPECIFIC HINTS 392------------------ 393Here are some hints on how to successfully submit patches inline using 394various mailers. 395 396GMail 397~~~~~ 398GMail does not have any way to turn off line wrapping in the web 399interface, so it will mangle any emails that you send. You can however 400use "git send-email" and send your patches through the GMail SMTP server, or 401use any IMAP email client to connect to the google IMAP server and forward 402the emails through that. 403 404For hints on using 'git send-email' to send your patches through the 405GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1]. 406 407For hints on submission using the IMAP interface, see the EXAMPLE 408section of linkgit:git-imap-send[1]. 409 410Thunderbird 411~~~~~~~~~~~ 412By default, Thunderbird will both wrap emails as well as flag 413them as being 'format=flowed', both of which will make the 414resulting email unusable by Git. 415 416There are three different approaches: use an add-on to turn off line wraps, 417configure Thunderbird to not mangle patches, or use 418an external editor to keep Thunderbird from mangling the patches. 419 420Approach #1 (add-on) 421^^^^^^^^^^^^^^^^^^^^ 422 423Install the Toggle Word Wrap add-on that is available from 424https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ 425It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu 426that you can tick off. Now you can compose the message as you otherwise do 427(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to 428insert line breaks manually in any text that you type. 429 430Approach #2 (configuration) 431^^^^^^^^^^^^^^^^^^^^^^^^^^^ 432Three steps: 433 4341. Configure your mail server composition as plain text: 435 Edit...Account Settings...Composition & Addressing, 436 uncheck "Compose Messages in HTML". 437 4382. Configure your general composition window to not wrap. 439+ 440In Thunderbird 2: 441Edit..Preferences..Composition, wrap plain text messages at 0 442+ 443In Thunderbird 3: 444Edit..Preferences..Advanced..Config Editor. Search for 445"mail.wrap_long_lines". 446Toggle it to make sure it is set to `false`. Also, search for 447"mailnews.wraplength" and set the value to 0. 448 4493. Disable the use of format=flowed: 450Edit..Preferences..Advanced..Config Editor. Search for 451"mailnews.send_plaintext_flowed". 452Toggle it to make sure it is set to `false`. 453 454After that is done, you should be able to compose email as you 455otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc), 456and the patches will not be mangled. 457 458Approach #3 (external editor) 459^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 460 461The following Thunderbird extensions are needed: 462AboutConfig from http://aboutconfig.mozdev.org/ and 463External Editor from http://globs.org/articles.php?lng=en&pg=8 464 4651. Prepare the patch as a text file using your method of choice. 466 4672. Before opening a compose window, use Edit->Account Settings to 468 uncheck the "Compose messages in HTML format" setting in the 469 "Composition & Addressing" panel of the account to be used to 470 send the patch. 471 4723. In the main Thunderbird window, 'before' you open the compose 473 window for the patch, use Tools->about:config to set the 474 following to the indicated values: 475+ 476---------- 477 mailnews.send_plaintext_flowed => false 478 mailnews.wraplength => 0 479---------- 480 4814. Open a compose window and click the external editor icon. 482 4835. In the external editor window, read in the patch file and exit 484 the editor normally. 485 486Side note: it may be possible to do step 2 with 487about:config and the following settings but no one's tried yet. 488 489---------- 490 mail.html_compose => false 491 mail.identity.default.compose_html => false 492 mail.identity.id?.compose_html => false 493---------- 494 495There is a script in contrib/thunderbird-patch-inline which can help 496you include patches with Thunderbird in an easy way. To use it, do the 497steps above and then use the script as the external editor. 498 499KMail 500~~~~~ 501This should help you to submit patches inline using KMail. 502 5031. Prepare the patch as a text file. 504 5052. Click on New Mail. 506 5073. Go under "Options" in the Composer window and be sure that 508 "Word wrap" is not set. 509 5104. Use Message -> Insert file... and insert the patch. 511 5125. Back in the compose window: add whatever other text you wish to the 513 message, complete the addressing and subject fields, and press send. 514 515 516EXAMPLES 517-------- 518 519* Extract commits between revisions R1 and R2, and apply them on top of 520the current branch using 'git am' to cherry-pick them: 521+ 522------------ 523$ git format-patch -k --stdout R1..R2 | git am -3 -k 524------------ 525 526* Extract all commits which are in the current branch but not in the 527origin branch: 528+ 529------------ 530$ git format-patch origin 531------------ 532+ 533For each commit a separate file is created in the current directory. 534 535* Extract all commits that lead to 'origin' since the inception of the 536project: 537+ 538------------ 539$ git format-patch --root origin 540------------ 541 542* The same as the previous one: 543+ 544------------ 545$ git format-patch -M -B origin 546------------ 547+ 548Additionally, it detects and handles renames and complete rewrites 549intelligently to produce a renaming patch. A renaming patch reduces 550the amount of text output, and generally makes it easier to review. 551Note that non-Git "patch" programs won't understand renaming patches, so 552use it only when you know the recipient uses Git to apply your patch. 553 554* Extract three topmost commits from the current branch and format them 555as e-mailable patches: 556+ 557------------ 558$ git format-patch -3 559------------ 560 561SEE ALSO 562-------- 563linkgit:git-am[1], linkgit:git-send-email[1] 564 565GIT 566--- 567Part of the linkgit:git[1] suite