1GIT-FORMAT-PATCH(1)               Git Manual               GIT-FORMAT-PATCH(1)
2
3
4

NAME

6       git-format-patch - Prepare patches for e-mail submission
7

SYNOPSIS

9       git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
10                          [--no-thread | --thread[=<style>]]
11                          [(--attach|--inline)[=<boundary>] | --no-attach]
12                          [-s | --signoff]
13                          [--signature=<signature> | --no-signature]
14                          [--signature-file=<file>]
15                          [-n | --numbered | -N | --no-numbered]
16                          [--start-number <n>] [--numbered-files]
17                          [--in-reply-to=Message-Id] [--suffix=.<sfx>]
18                          [--ignore-if-in-upstream]
19                          [--rfc] [--subject-prefix=Subject-Prefix]
20                          [(--reroll-count|-v) <n>]
21                          [--to=<email>] [--cc=<email>]
22                          [--[no-]cover-letter] [--quiet] [--notes[=<ref>]]
23                          [--interdiff=<previous>]
24                          [--range-diff=<previous> [--creation-factor=<percent>]]
25                          [--progress]
26                          [<common diff options>]
27                          [ <since> | <revision range> ]
28
29

DESCRIPTION

31       Prepare each commit with its patch in one file per commit, formatted to
32       resemble UNIX mailbox format. The output of this command is convenient
33       for e-mail submission or for use with git am.
34
35       There are two ways to specify which commits to operate on.
36
37        1. A single commit, <since>, specifies that the commits leading to the
38           tip of the current branch that are not in the history that leads to
39           the <since> to be output.
40
41        2. Generic <revision range> expression (see "SPECIFYING REVISIONS"
42           section in gitrevisions(7)) means the commits in the specified
43           range.
44
45       The first rule takes precedence in the case of a single <commit>. To
46       apply the second rule, i.e., format everything since the beginning of
47       history up until <commit>, use the --root option: git format-patch
48       --root <commit>. If you want to format only <commit> itself, you can do
49       this with git format-patch -1 <commit>.
50
51       By default, each output file is numbered sequentially from 1, and uses
52       the first line of the commit message (massaged for pathname safety) as
53       the filename. With the --numbered-files option, the output file names
54       will only be numbers, without the first line of the commit appended.
55       The names of the output files are printed to standard output, unless
56       the --stdout option is specified.
57
58       If -o is specified, output files are created in <dir>. Otherwise they
59       are created in the current working directory. The default path can be
60       set with the format.outputDirectory configuration option. The -o option
61       takes precedence over format.outputDirectory. To store patches in the
62       current working directory even when format.outputDirectory points
63       elsewhere, use -o ..
64
65       By default, the subject of a single patch is "[PATCH] " followed by the
66       concatenation of lines from the commit message up to the first blank
67       line (see the DISCUSSION section of git-commit(1)).
68
69       When multiple patches are output, the subject prefix will instead be
70       "[PATCH n/m] ". To force 1/1 to be added for a single patch, use -n. To
71       omit patch numbers from the subject, use -N.
72
73       If given --thread, git-format-patch will generate In-Reply-To and
74       References headers to make the second and subsequent patch mails appear
75       as replies to the first mail; this also generates a Message-Id header
76       to reference.
77

OPTIONS

79       -p, --no-stat
80           Generate plain patches without any diffstats.
81
82       -U<n>, --unified=<n>
83           Generate diffs with <n> lines of context instead of the usual
84           three.
85
86       --indent-heuristic
87           Enable the heuristic that shifts diff hunk boundaries to make
88           patches easier to read. This is the default.
89
90       --no-indent-heuristic
91           Disable the indent heuristic.
92
93       --minimal
94           Spend extra time to make sure the smallest possible diff is
95           produced.
96
97       --patience
98           Generate a diff using the "patience diff" algorithm.
99
100       --histogram
101           Generate a diff using the "histogram diff" algorithm.
102
103       --anchored=<text>
104           Generate a diff using the "anchored diff" algorithm.
105
106           This option may be specified more than once.
107
108           If a line exists in both the source and destination, exists only
109           once, and starts with this text, this algorithm attempts to prevent
110           it from appearing as a deletion or addition in the output. It uses
111           the "patience diff" algorithm internally.
112
113       --diff-algorithm={patience|minimal|histogram|myers}
114           Choose a diff algorithm. The variants are as follows:
115
116           default, myers
117               The basic greedy diff algorithm. Currently, this is the
118               default.
119
120           minimal
121               Spend extra time to make sure the smallest possible diff is
122               produced.
123
124           patience
125               Use "patience diff" algorithm when generating patches.
126
127           histogram
128               This algorithm extends the patience algorithm to "support
129               low-occurrence common elements".
130
131           For instance, if you configured the diff.algorithm variable to a
132           non-default value and want to use the default one, then you have to
133           use --diff-algorithm=default option.
134
135       --stat[=<width>[,<name-width>[,<count>]]]
136           Generate a diffstat. By default, as much space as necessary will be
137           used for the filename part, and the rest for the graph part.
138           Maximum width defaults to terminal width, or 80 columns if not
139           connected to a terminal, and can be overridden by <width>. The
140           width of the filename part can be limited by giving another width
141           <name-width> after a comma. The width of the graph part can be
142           limited by using --stat-graph-width=<width> (affects all commands
143           generating a stat graph) or by setting diff.statGraphWidth=<width>
144           (does not affect git format-patch). By giving a third parameter
145           <count>, you can limit the output to the first <count> lines,
146           followed by ...  if there are more.
147
148           These parameters can also be set individually with
149           --stat-width=<width>, --stat-name-width=<name-width> and
150           --stat-count=<count>.
151
152       --compact-summary
153           Output a condensed summary of extended header information such as
154           file creations or deletions ("new" or "gone", optionally "+l" if
155           it’s a symlink) and mode changes ("+x" or "-x" for adding or
156           removing executable bit respectively) in diffstat. The information
157           is put between the filename part and the graph part. Implies
158           --stat.
159
160       --numstat
161           Similar to --stat, but shows number of added and deleted lines in
162           decimal notation and pathname without abbreviation, to make it more
163           machine friendly. For binary files, outputs two - instead of saying
164           0 0.
165
166       --shortstat
167           Output only the last line of the --stat format containing total
168           number of modified files, as well as number of added and deleted
169           lines.
170
171       --dirstat[=<param1,param2,...>]
172           Output the distribution of relative amount of changes for each
173           sub-directory. The behavior of --dirstat can be customized by
174           passing it a comma separated list of parameters. The defaults are
175           controlled by the diff.dirstat configuration variable (see git-
176           config(1)). The following parameters are available:
177
178           changes
179               Compute the dirstat numbers by counting the lines that have
180               been removed from the source, or added to the destination. This
181               ignores the amount of pure code movements within a file. In
182               other words, rearranging lines in a file is not counted as much
183               as other changes. This is the default behavior when no
184               parameter is given.
185
186           lines
187               Compute the dirstat numbers by doing the regular line-based
188               diff analysis, and summing the removed/added line counts. (For
189               binary files, count 64-byte chunks instead, since binary files
190               have no natural concept of lines). This is a more expensive
191               --dirstat behavior than the changes behavior, but it does count
192               rearranged lines within a file as much as other changes. The
193               resulting output is consistent with what you get from the other
194               --*stat options.
195
196           files
197               Compute the dirstat numbers by counting the number of files
198               changed. Each changed file counts equally in the dirstat
199               analysis. This is the computationally cheapest --dirstat
200               behavior, since it does not have to look at the file contents
201               at all.
202
203           cumulative
204               Count changes in a child directory for the parent directory as
205               well. Note that when using cumulative, the sum of the
206               percentages reported may exceed 100%. The default
207               (non-cumulative) behavior can be specified with the
208               noncumulative parameter.
209
210           <limit>
211               An integer parameter specifies a cut-off percent (3% by
212               default). Directories contributing less than this percentage of
213               the changes are not shown in the output.
214
215           Example: The following will count changed files, while ignoring
216           directories with less than 10% of the total amount of changed
217           files, and accumulating child directory counts in the parent
218           directories: --dirstat=files,10,cumulative.
219
220       --summary
221           Output a condensed summary of extended header information such as
222           creations, renames and mode changes.
223
224       --no-renames
225           Turn off rename detection, even when the configuration file gives
226           the default to do so.
227
228       --full-index
229           Instead of the first handful of characters, show the full pre- and
230           post-image blob object names on the "index" line when generating
231           patch format output.
232
233       --binary
234           In addition to --full-index, output a binary diff that can be
235           applied with git-apply.
236
237       --abbrev[=<n>]
238           Instead of showing the full 40-byte hexadecimal object name in
239           diff-raw format output and diff-tree header lines, show only a
240           partial prefix. This is independent of the --full-index option
241           above, which controls the diff-patch output format. Non default
242           number of digits can be specified with --abbrev=<n>.
243
244       -B[<n>][/<m>], --break-rewrites[=[<n>][/<m>]]
245           Break complete rewrite changes into pairs of delete and create.
246           This serves two purposes:
247
248           It affects the way a change that amounts to a total rewrite of a
249           file not as a series of deletion and insertion mixed together with
250           a very few lines that happen to match textually as the context, but
251           as a single deletion of everything old followed by a single
252           insertion of everything new, and the number m controls this aspect
253           of the -B option (defaults to 60%).  -B/70% specifies that less
254           than 30% of the original should remain in the result for Git to
255           consider it a total rewrite (i.e. otherwise the resulting patch
256           will be a series of deletion and insertion mixed together with
257           context lines).
258
259           When used with -M, a totally-rewritten file is also considered as
260           the source of a rename (usually -M only considers a file that
261           disappeared as the source of a rename), and the number n controls
262           this aspect of the -B option (defaults to 50%).  -B20% specifies
263           that a change with addition and deletion compared to 20% or more of
264           the file’s size are eligible for being picked up as a possible
265           source of a rename to another file.
266
267       -M[<n>], --find-renames[=<n>]
268           Detect renames. If n is specified, it is a threshold on the
269           similarity index (i.e. amount of addition/deletions compared to the
270           file’s size). For example, -M90% means Git should consider a
271           delete/add pair to be a rename if more than 90% of the file hasn’t
272           changed. Without a % sign, the number is to be read as a fraction,
273           with a decimal point before it. I.e., -M5 becomes 0.5, and is thus
274           the same as -M50%. Similarly, -M05 is the same as -M5%. To limit
275           detection to exact renames, use -M100%. The default similarity
276           index is 50%.
277
278       -C[<n>], --find-copies[=<n>]
279           Detect copies as well as renames. See also --find-copies-harder. If
280           n is specified, it has the same meaning as for -M<n>.
281
282       --find-copies-harder
283           For performance reasons, by default, -C option finds copies only if
284           the original file of the copy was modified in the same changeset.
285           This flag makes the command inspect unmodified files as candidates
286           for the source of copy. This is a very expensive operation for
287           large projects, so use it with caution. Giving more than one -C
288           option has the same effect.
289
290       -D, --irreversible-delete
291           Omit the preimage for deletes, i.e. print only the header but not
292           the diff between the preimage and /dev/null. The resulting patch is
293           not meant to be applied with patch or git apply; this is solely for
294           people who want to just concentrate on reviewing the text after the
295           change. In addition, the output obviously lacks enough information
296           to apply such a patch in reverse, even manually, hence the name of
297           the option.
298
299           When used together with -B, omit also the preimage in the deletion
300           part of a delete/create pair.
301
302       -l<num>
303           The -M and -C options require O(n^2) processing time where n is the
304           number of potential rename/copy targets. This option prevents
305           rename/copy detection from running if the number of rename/copy
306           targets exceeds the specified number.
307
308       -O<orderfile>
309           Control the order in which files appear in the output. This
310           overrides the diff.orderFile configuration variable (see git-
311           config(1)). To cancel diff.orderFile, use -O/dev/null.
312
313           The output order is determined by the order of glob patterns in
314           <orderfile>. All files with pathnames that match the first pattern
315           are output first, all files with pathnames that match the second
316           pattern (but not the first) are output next, and so on. All files
317           with pathnames that do not match any pattern are output last, as if
318           there was an implicit match-all pattern at the end of the file. If
319           multiple pathnames have the same rank (they match the same pattern
320           but no earlier patterns), their output order relative to each other
321           is the normal order.
322
323           <orderfile> is parsed as follows:
324
325           ·   Blank lines are ignored, so they can be used as separators for
326               readability.
327
328           ·   Lines starting with a hash ("#") are ignored, so they can be
329               used for comments. Add a backslash ("\") to the beginning of
330               the pattern if it starts with a hash.
331
332           ·   Each other line contains a single pattern.
333
334           Patterns have the same syntax and semantics as patterns used for
335           fnmatch(3) without the FNM_PATHNAME flag, except a pathname also
336           matches a pattern if removing any number of the final pathname
337           components matches the pattern. For example, the pattern "foo*bar"
338           matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".
339
340       -a, --text
341           Treat all files as text.
342
343       --ignore-cr-at-eol
344           Ignore carriage-return at the end of line when doing a comparison.
345
346       --ignore-space-at-eol
347           Ignore changes in whitespace at EOL.
348
349       -b, --ignore-space-change
350           Ignore changes in amount of whitespace. This ignores whitespace at
351           line end, and considers all other sequences of one or more
352           whitespace characters to be equivalent.
353
354       -w, --ignore-all-space
355           Ignore whitespace when comparing lines. This ignores differences
356           even if one line has whitespace where the other line has none.
357
358       --ignore-blank-lines
359           Ignore changes whose lines are all blank.
360
361       --inter-hunk-context=<lines>
362           Show the context between diff hunks, up to the specified number of
363           lines, thereby fusing hunks that are close to each other. Defaults
364           to diff.interHunkContext or 0 if the config option is unset.
365
366       -W, --function-context
367           Show whole surrounding functions of changes.
368
369       --ext-diff
370           Allow an external diff helper to be executed. If you set an
371           external diff driver with gitattributes(5), you need to use this
372           option with git-log(1) and friends.
373
374       --no-ext-diff
375           Disallow external diff drivers.
376
377       --textconv, --no-textconv
378           Allow (or disallow) external text conversion filters to be run when
379           comparing binary files. See gitattributes(5) for details. Because
380           textconv filters are typically a one-way conversion, the resulting
381           diff is suitable for human consumption, but cannot be applied. For
382           this reason, textconv filters are enabled by default only for git-
383           diff(1) and git-log(1), but not for git-format-patch(1) or diff
384           plumbing commands.
385
386       --ignore-submodules[=<when>]
387           Ignore changes to submodules in the diff generation. <when> can be
388           either "none", "untracked", "dirty" or "all", which is the default.
389           Using "none" will consider the submodule modified when it either
390           contains untracked or modified files or its HEAD differs from the
391           commit recorded in the superproject and can be used to override any
392           settings of the ignore option in git-config(1) or gitmodules(5).
393           When "untracked" is used submodules are not considered dirty when
394           they only contain untracked content (but they are still scanned for
395           modified content). Using "dirty" ignores all changes to the work
396           tree of submodules, only changes to the commits stored in the
397           superproject are shown (this was the behavior until 1.7.0). Using
398           "all" hides all changes to submodules.
399
400       --src-prefix=<prefix>
401           Show the given source prefix instead of "a/".
402
403       --dst-prefix=<prefix>
404           Show the given destination prefix instead of "b/".
405
406       --no-prefix
407           Do not show any source or destination prefix.
408
409       --line-prefix=<prefix>
410           Prepend an additional prefix to every line of output.
411
412       --ita-invisible-in-index
413           By default entries added by "git add -N" appear as an existing
414           empty file in "git diff" and a new file in "git diff --cached".
415           This option makes the entry appear as a new file in "git diff" and
416           non-existent in "git diff --cached". This option could be reverted
417           with --ita-visible-in-index. Both options are experimental and
418           could be removed in future.
419
420       For more detailed explanation on these common options, see also
421       gitdiffcore(7).
422
423       -<n>
424           Prepare patches from the topmost <n> commits.
425
426       -o <dir>, --output-directory <dir>
427           Use <dir> to store the resulting files, instead of the current
428           working directory.
429
430       -n, --numbered
431           Name output in [PATCH n/m] format, even with a single patch.
432
433       -N, --no-numbered
434           Name output in [PATCH] format.
435
436       --start-number <n>
437           Start numbering the patches at <n> instead of 1.
438
439       --numbered-files
440           Output file names will be a simple number sequence without the
441           default first line of the commit appended.
442
443       -k, --keep-subject
444           Do not strip/add [PATCH] from the first line of the commit log
445           message.
446
447       -s, --signoff
448           Add Signed-off-by: line to the commit message, using the committer
449           identity of yourself. See the signoff option in git-commit(1) for
450           more information.
451
452       --stdout
453           Print all commits to the standard output in mbox format, instead of
454           creating a file for each one.
455
456       --attach[=<boundary>]
457           Create multipart/mixed attachment, the first part of which is the
458           commit message and the patch itself in the second part, with
459           Content-Disposition: attachment.
460
461       --no-attach
462           Disable the creation of an attachment, overriding the configuration
463           setting.
464
465       --inline[=<boundary>]
466           Create multipart/mixed attachment, the first part of which is the
467           commit message and the patch itself in the second part, with
468           Content-Disposition: inline.
469
470       --thread[=<style>], --no-thread
471           Controls addition of In-Reply-To and References headers to make the
472           second and subsequent mails appear as replies to the first. Also
473           controls generation of the Message-Id header to reference.
474
475           The optional <style> argument can be either shallow or deep.
476           shallow threading makes every mail a reply to the head of the
477           series, where the head is chosen from the cover letter, the
478           --in-reply-to, and the first patch mail, in this order.  deep
479           threading makes every mail a reply to the previous one.
480
481           The default is --no-thread, unless the format.thread configuration
482           is set. If --thread is specified without a style, it defaults to
483           the style specified by format.thread if any, or else shallow.
484
485           Beware that the default for git send-email is to thread emails
486           itself. If you want git format-patch to take care of threading, you
487           will want to ensure that threading is disabled for git send-email.
488
489       --in-reply-to=Message-Id
490           Make the first mail (or all the mails with --no-thread) appear as a
491           reply to the given Message-Id, which avoids breaking threads to
492           provide a new patch series.
493
494       --ignore-if-in-upstream
495           Do not include a patch that matches a commit in <until>..<since>.
496           This will examine all patches reachable from <since> but not from
497           <until> and compare them with the patches being generated, and any
498           patch that matches is ignored.
499
500       --subject-prefix=<Subject-Prefix>
501           Instead of the standard [PATCH] prefix in the subject line, instead
502           use [<Subject-Prefix>]. This allows for useful naming of a patch
503           series, and can be combined with the --numbered option.
504
505       --rfc
506           Alias for --subject-prefix="RFC PATCH". RFC means "Request For
507           Comments"; use this when sending an experimental patch for
508           discussion rather than application.
509
510       -v <n>, --reroll-count=<n>
511           Mark the series as the <n>-th iteration of the topic. The output
512           filenames have v<n> prepended to them, and the subject prefix
513           ("PATCH" by default, but configurable via the --subject-prefix
514           option) has ` v<n>` appended to it. E.g.  --reroll-count=4 may
515           produce v4-0001-add-makefile.patch file that has "Subject: [PATCH
516           v4 1/20] Add makefile" in it.
517
518       --to=<email>
519           Add a To: header to the email headers. This is in addition to any
520           configured headers, and may be used multiple times. The negated
521           form --no-to discards all To: headers added so far (from config or
522           command line).
523
524       --cc=<email>
525           Add a Cc: header to the email headers. This is in addition to any
526           configured headers, and may be used multiple times. The negated
527           form --no-cc discards all Cc: headers added so far (from config or
528           command line).
529
530       --from, --from=<ident>
531           Use ident in the From: header of each commit email. If the author
532           ident of the commit is not textually identical to the provided
533           ident, place a From: header in the body of the message with the
534           original author. If no ident is given, use the committer ident.
535
536           Note that this option is only useful if you are actually sending
537           the emails and want to identify yourself as the sender, but retain
538           the original author (and git am will correctly pick up the in-body
539           header). Note also that git send-email already handles this
540           transformation for you, and this option should not be used if you
541           are feeding the result to git send-email.
542
543       --add-header=<header>
544           Add an arbitrary header to the email headers. This is in addition
545           to any configured headers, and may be used multiple times. For
546           example, --add-header="Organization: git-foo". The negated form
547           --no-add-header discards all (To:, Cc:, and custom) headers added
548           so far from config or command line.
549
550       --[no-]cover-letter
551           In addition to the patches, generate a cover letter file containing
552           the branch description, shortlog and the overall diffstat. You can
553           fill in a description in the file before sending it out.
554
555       --interdiff=<previous>
556           As a reviewer aid, insert an interdiff into the cover letter, or as
557           commentary of the lone patch of a 1-patch series, showing the
558           differences between the previous version of the patch series and
559           the series currently being formatted.  previous is a single
560           revision naming the tip of the previous series which shares a
561           common base with the series being formatted (for example git
562           format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2).
563
564       --range-diff=<previous>
565           As a reviewer aid, insert a range-diff (see git-range-diff(1)) into
566           the cover letter, or as commentary of the lone patch of a 1-patch
567           series, showing the differences between the previous version of the
568           patch series and the series currently being formatted.  previous
569           can be a single revision naming the tip of the previous series if
570           it shares a common base with the series being formatted (for
571           example git format-patch --cover-letter --range-diff=feature/v1 -3
572           feature/v2), or a revision range if the two versions of the series
573           are disjoint (for example git format-patch --cover-letter
574           --range-diff=feature/v1~3..feature/v1 -3 feature/v2).
575
576           Note that diff options passed to the command affect how the primary
577           product of format-patch is generated, and they are not passed to
578           the underlying range-diff machinery used to generate the
579           cover-letter material (this may change in the future).
580
581       --creation-factor=<percent>
582           Used with --range-diff, tweak the heuristic which matches up
583           commits between the previous and current series of patches by
584           adjusting the creation/deletion cost fudge factor. See git-range-
585           diff(1)) for details.
586
587       --notes[=<ref>]
588           Append the notes (see git-notes(1)) for the commit after the
589           three-dash line.
590
591           The expected use case of this is to write supporting explanation
592           for the commit that does not belong to the commit log message
593           proper, and include it with the patch submission. While one can
594           simply write these explanations after format-patch has run but
595           before sending, keeping them as Git notes allows them to be
596           maintained between versions of the patch series (but see the
597           discussion of the notes.rewrite configuration options in git-
598           notes(1) to use this workflow).
599
600       --[no-]signature=<signature>
601           Add a signature to each message produced. Per RFC 3676 the
602           signature is separated from the body by a line with '-- ' on it. If
603           the signature option is omitted the signature defaults to the Git
604           version number.
605
606       --signature-file=<file>
607           Works just like --signature except the signature is read from a
608           file.
609
610       --suffix=.<sfx>
611           Instead of using .patch as the suffix for generated filenames, use
612           specified suffix. A common alternative is --suffix=.txt. Leaving
613           this empty will remove the .patch suffix.
614
615           Note that the leading character does not have to be a dot; for
616           example, you can use --suffix=-patch to get
617           0001-description-of-my-change-patch.
618
619       -q, --quiet
620           Do not print the names of the generated files to standard output.
621
622       --no-binary
623           Do not output contents of changes in binary files, instead display
624           a notice that those files changed. Patches generated using this
625           option cannot be applied properly, but they are still useful for
626           code review.
627
628       --zero-commit
629           Output an all-zero hash in each patch’s From header instead of the
630           hash of the commit.
631
632       --base=<commit>
633           Record the base tree information to identify the state the patch
634           series applies to. See the BASE TREE INFORMATION section below for
635           details.
636
637       --root
638           Treat the revision argument as a <revision range>, even if it is
639           just a single commit (that would normally be treated as a <since>).
640           Note that root commits included in the specified range are always
641           formatted as creation patches, independently of this flag.
642
643       --progress
644           Show progress reports on stderr as patches are generated.
645

CONFIGURATION

647       You can specify extra mail header lines to be added to each message,
648       defaults for the subject prefix and file suffix, number patches when
649       outputting more than one patch, add "To" or "Cc:" headers, configure
650       attachments, and sign off patches with configuration variables.
651
652           [format]
653                   headers = "Organization: git-foo\n"
654                   subjectPrefix = CHANGE
655                   suffix = .txt
656                   numbered = auto
657                   to = <email>
658                   cc = <email>
659                   attach [ = mime-boundary-string ]
660                   signOff = true
661                   coverletter = auto
662
663

DISCUSSION

665       The patch produced by git format-patch is in UNIX mailbox format, with
666       a fixed "magic" time stamp to indicate that the file is output from
667       format-patch rather than a real mailbox, like so:
668
669           From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
670           From: Tony Luck <tony.luck@intel.com>
671           Date: Tue, 13 Jul 2010 11:42:54 -0700
672           Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
673            =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
674           MIME-Version: 1.0
675           Content-Type: text/plain; charset=UTF-8
676           Content-Transfer-Encoding: 8bit
677
678           arch/arm config files were slimmed down using a python script
679           (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
680
681           Do the same for ia64 so we can have sleek & trim looking
682           ...
683
684
685       Typically it will be placed in a MUA’s drafts folder, edited to add
686       timely commentary that should not go in the changelog after the three
687       dashes, and then sent as a message whose body, in our example, starts
688       with "arch/arm config files were...". On the receiving end, readers can
689       save interesting patches in a UNIX mailbox and apply them with git-
690       am(1).
691
692       When a patch is part of an ongoing discussion, the patch generated by
693       git format-patch can be tweaked to take advantage of the git am
694       --scissors feature. After your response to the discussion comes a line
695       that consists solely of "-- >8 --" (scissors and perforation), followed
696       by the patch with unnecessary header fields removed:
697
698           ...
699           > So we should do such-and-such.
700
701           Makes sense to me.  How about this patch?
702
703           -- >8 --
704           Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
705
706           arch/arm config files were slimmed down using a python script
707           ...
708
709
710       When sending a patch this way, most often you are sending your own
711       patch, so in addition to the "From $SHA1 $magic_timestamp" marker you
712       should omit From: and Date: lines from the patch file. The patch title
713       is likely to be different from the subject of the discussion the patch
714       is in response to, so it is likely that you would want to keep the
715       Subject: line, like the example above.
716
717   Checking for patch corruption
718       Many mailers if not set up properly will corrupt whitespace. Here are
719       two common types of corruption:
720
721       ·   Empty context lines that do not have any whitespace.
722
723       ·   Non-empty context lines that have one extra whitespace at the
724           beginning.
725
726       One way to test if your MUA is set up correctly is:
727
728       ·   Send the patch to yourself, exactly the way you would, except with
729           To: and Cc: lines that do not contain the list and maintainer
730           address.
731
732       ·   Save that patch to a file in UNIX mailbox format. Call it a.patch,
733           say.
734
735       ·   Apply it:
736
737               $ git fetch <project> master:test-apply
738               $ git checkout test-apply
739               $ git reset --hard
740               $ git am a.patch
741
742       If it does not apply correctly, there can be various reasons.
743
744       ·   The patch itself does not apply cleanly. That is bad but does not
745           have much to do with your MUA. You might want to rebase the patch
746           with git-rebase(1) before regenerating it in this case.
747
748       ·   The MUA corrupted your patch; "am" would complain that the patch
749           does not apply. Look in the .git/rebase-apply/ subdirectory and see
750           what patch file contains and check for the common corruption
751           patterns mentioned above.
752
753       ·   While at it, check the info and final-commit files as well. If what
754           is in final-commit is not exactly what you would want to see in the
755           commit log message, it is very likely that the receiver would end
756           up hand editing the log message when applying your patch. Things
757           like "Hi, this is my first patch.\n" in the patch e-mail should
758           come after the three-dash line that signals the end of the commit
759           message.
760

MUA-SPECIFIC HINTS

762       Here are some hints on how to successfully submit patches inline using
763       various mailers.
764
765   GMail
766       GMail does not have any way to turn off line wrapping in the web
767       interface, so it will mangle any emails that you send. You can however
768       use "git send-email" and send your patches through the GMail SMTP
769       server, or use any IMAP email client to connect to the google IMAP
770       server and forward the emails through that.
771
772       For hints on using git send-email to send your patches through the
773       GMail SMTP server, see the EXAMPLE section of git-send-email(1).
774
775       For hints on submission using the IMAP interface, see the EXAMPLE
776       section of git-imap-send(1).
777
778   Thunderbird
779       By default, Thunderbird will both wrap emails as well as flag them as
780       being format=flowed, both of which will make the resulting email
781       unusable by Git.
782
783       There are three different approaches: use an add-on to turn off line
784       wraps, configure Thunderbird to not mangle patches, or use an external
785       editor to keep Thunderbird from mangling the patches.
786
787       Approach #1 (add-on)
788           Install the Toggle Word Wrap add-on that is available from
789           https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ It
790           adds a menu entry "Enable Word Wrap" in the composer’s "Options"
791           menu that you can tick off. Now you can compose the message as you
792           otherwise do (cut + paste, git format-patch | git imap-send, etc),
793           but you have to insert line breaks manually in any text that you
794           type.
795
796       Approach #2 (configuration)
797           Three steps:
798
799            1. Configure your mail server composition as plain text:
800               Edit...Account Settings...Composition & Addressing, uncheck
801               "Compose Messages in HTML".
802
803            2. Configure your general composition window to not wrap.
804
805               In Thunderbird 2: Edit..Preferences..Composition, wrap plain
806               text messages at 0
807
808               In Thunderbird 3: Edit..Preferences..Advanced..Config Editor.
809               Search for "mail.wrap_long_lines". Toggle it to make sure it is
810               set to false. Also, search for "mailnews.wraplength" and set
811               the value to 0.
812
813            3. Disable the use of format=flowed:
814               Edit..Preferences..Advanced..Config Editor. Search for
815               "mailnews.send_plaintext_flowed". Toggle it to make sure it is
816               set to false.
817
818           After that is done, you should be able to compose email as you
819           otherwise would (cut + paste, git format-patch | git imap-send,
820           etc), and the patches will not be mangled.
821
822       Approach #3 (external editor)
823           The following Thunderbird extensions are needed: AboutConfig from
824           http://aboutconfig.mozdev.org/ and External Editor from
825           http://globs.org/articles.php?lng=en&pg=8
826
827            1. Prepare the patch as a text file using your method of choice.
828
829            2. Before opening a compose window, use Edit→Account Settings to
830               uncheck the "Compose messages in HTML format" setting in the
831               "Composition & Addressing" panel of the account to be used to
832               send the patch.
833
834            3. In the main Thunderbird window, before you open the compose
835               window for the patch, use Tools→about:config to set the
836               following to the indicated values:
837
838                           mailnews.send_plaintext_flowed  => false
839                           mailnews.wraplength             => 0
840
841
842            4. Open a compose window and click the external editor icon.
843
844            5. In the external editor window, read in the patch file and exit
845               the editor normally.
846
847           Side note: it may be possible to do step 2 with about:config and
848           the following settings but no one’s tried yet.
849
850                       mail.html_compose                       => false
851                       mail.identity.default.compose_html      => false
852                       mail.identity.id?.compose_html          => false
853
854
855           There is a script in contrib/thunderbird-patch-inline which can
856           help you include patches with Thunderbird in an easy way. To use
857           it, do the steps above and then use the script as the external
858           editor.
859
860   KMail
861       This should help you to submit patches inline using KMail.
862
863        1. Prepare the patch as a text file.
864
865        2. Click on New Mail.
866
867        3. Go under "Options" in the Composer window and be sure that "Word
868           wrap" is not set.
869
870        4. Use Message → Insert file... and insert the patch.
871
872        5. Back in the compose window: add whatever other text you wish to the
873           message, complete the addressing and subject fields, and press
874           send.
875

BASE TREE INFORMATION

877       The base tree information block is used for maintainers or third party
878       testers to know the exact state the patch series applies to. It
879       consists of the base commit, which is a well-known commit that is part
880       of the stable part of the project history everybody else works off of,
881       and zero or more prerequisite patches, which are well-known patches in
882       flight that is not yet part of the base commit that need to be applied
883       on top of base commit in topological order before the patches can be
884       applied.
885
886       The base commit is shown as "base-commit: " followed by the 40-hex of
887       the commit object name. A prerequisite patch is shown as
888       "prerequisite-patch-id: " followed by the 40-hex patch id, which can be
889       obtained by passing the patch through the git patch-id --stable
890       command.
891
892       Imagine that on top of the public commit P, you applied well-known
893       patches X, Y and Z from somebody else, and then built your three-patch
894       series A, B, C, the history would be like:
895
896           ---P---X---Y---Z---A---B---C
897
898       With git format-patch --base=P -3 C (or variants thereof, e.g. with
899       --cover-letter or using Z..C instead of -3 C to specify the range), the
900       base tree information block is shown at the end of the first message
901       the command outputs (either the first patch, or the cover letter), like
902       this:
903
904           base-commit: P
905           prerequisite-patch-id: X
906           prerequisite-patch-id: Y
907           prerequisite-patch-id: Z
908
909
910       For non-linear topology, such as
911
912           ---P---X---A---M---C
913               \         /
914                Y---Z---B
915
916       You can also use git format-patch --base=P -3 C to generate patches for
917       A, B and C, and the identifiers for P, X, Y, Z are appended at the end
918       of the first message.
919
920       If set --base=auto in cmdline, it will track base commit automatically,
921       the base commit will be the merge base of tip commit of the
922       remote-tracking branch and revision-range specified in cmdline. For a
923       local branch, you need to track a remote branch by git branch
924       --set-upstream-to before using this option.
925

EXAMPLES

927       ·   Extract commits between revisions R1 and R2, and apply them on top
928           of the current branch using git am to cherry-pick them:
929
930               $ git format-patch -k --stdout R1..R2 | git am -3 -k
931
932
933       ·   Extract all commits which are in the current branch but not in the
934           origin branch:
935
936               $ git format-patch origin
937
938           For each commit a separate file is created in the current
939           directory.
940
941       ·   Extract all commits that lead to origin since the inception of the
942           project:
943
944               $ git format-patch --root origin
945
946
947       ·   The same as the previous one:
948
949               $ git format-patch -M -B origin
950
951           Additionally, it detects and handles renames and complete rewrites
952           intelligently to produce a renaming patch. A renaming patch reduces
953           the amount of text output, and generally makes it easier to review.
954           Note that non-Git "patch" programs won’t understand renaming
955           patches, so use it only when you know the recipient uses Git to
956           apply your patch.
957
958       ·   Extract three topmost commits from the current branch and format
959           them as e-mailable patches:
960
961               $ git format-patch -3
962
963

SEE ALSO

965       git-am(1), git-send-email(1)
966

GIT

968       Part of the git(1) suite
969
970
971
972Git 2.21.0                        02/24/2019               GIT-FORMAT-PATCH(1)
Impressum