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