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