Documentation/git-format-patch.txt

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