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