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