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                          [--cover-from-description=<mode>]
20                          [--rfc] [--subject-prefix=<subject prefix>]
21                          [(--reroll-count|-v) <n>]
22                          [--to=<email>] [--cc=<email>]
23                          [--[no-]cover-letter] [--quiet]
24                          [--[no-]encode-email-headers]
25                          [--no-notes | --notes[=<ref>]]
26                          [--interdiff=<previous>]
27                          [--range-diff=<previous> [--creation-factor=<percent>]]
28                          [--filename-max-length=<n>]
29                          [--progress]
30                          [<common diff options>]
31                          [ <since> | <revision range> ]
32

DESCRIPTION

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

OPTIONS

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

CONFIGURATION

723       You can specify extra mail header lines to be added to each message,
724       defaults for the subject prefix and file suffix, number patches when
725       outputting more than one patch, add "To:" or "Cc:" headers, configure
726       attachments, change the patch output directory, and sign off patches
727       with configuration variables.
728
729           [format]
730                   headers = "Organization: git-foo\n"
731                   subjectPrefix = CHANGE
732                   suffix = .txt
733                   numbered = auto
734                   to = <email>
735                   cc = <email>
736                   attach [ = mime-boundary-string ]
737                   signOff = true
738                   outputDirectory = <directory>
739                   coverLetter = auto
740                   coverFromDescription = auto
741

DISCUSSION

743       The patch produced by git format-patch is in UNIX mailbox format, with
744       a fixed "magic" time stamp to indicate that the file is output from
745       format-patch rather than a real mailbox, like so:
746
747           From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
748           From: Tony Luck <tony.luck@intel.com>
749           Date: Tue, 13 Jul 2010 11:42:54 -0700
750           Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
751            =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
752           MIME-Version: 1.0
753           Content-Type: text/plain; charset=UTF-8
754           Content-Transfer-Encoding: 8bit
755
756           arch/arm config files were slimmed down using a python script
757           (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
758
759           Do the same for ia64 so we can have sleek & trim looking
760           ...
761
762       Typically it will be placed in a MUA’s drafts folder, edited to add
763       timely commentary that should not go in the changelog after the three
764       dashes, and then sent as a message whose body, in our example, starts
765       with "arch/arm config files were...". On the receiving end, readers can
766       save interesting patches in a UNIX mailbox and apply them with git-
767       am(1).
768
769       When a patch is part of an ongoing discussion, the patch generated by
770       git format-patch can be tweaked to take advantage of the git am
771       --scissors feature. After your response to the discussion comes a line
772       that consists solely of "-- >8 --" (scissors and perforation), followed
773       by the patch with unnecessary header fields removed:
774
775           ...
776           > So we should do such-and-such.
777
778           Makes sense to me.  How about this patch?
779
780           -- >8 --
781           Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
782
783           arch/arm config files were slimmed down using a python script
784           ...
785
786       When sending a patch this way, most often you are sending your own
787       patch, so in addition to the "From $SHA1 $magic_timestamp" marker you
788       should omit From: and Date: lines from the patch file. The patch title
789       is likely to be different from the subject of the discussion the patch
790       is in response to, so it is likely that you would want to keep the
791       Subject: line, like the example above.
792
793   Checking for patch corruption
794       Many mailers if not set up properly will corrupt whitespace. Here are
795       two common types of corruption:
796
797       ·   Empty context lines that do not have any whitespace.
798
799       ·   Non-empty context lines that have one extra whitespace at the
800           beginning.
801
802       One way to test if your MUA is set up correctly is:
803
804       ·   Send the patch to yourself, exactly the way you would, except with
805           To: and Cc: lines that do not contain the list and maintainer
806           address.
807
808       ·   Save that patch to a file in UNIX mailbox format. Call it a.patch,
809           say.
810
811       ·   Apply it:
812
813               $ git fetch <project> master:test-apply
814               $ git switch test-apply
815               $ git restore --source=HEAD --staged --worktree :/
816               $ git am a.patch
817
818       If it does not apply correctly, there can be various reasons.
819
820       ·   The patch itself does not apply cleanly. That is bad but does not
821           have much to do with your MUA. You might want to rebase the patch
822           with git-rebase(1) before regenerating it in this case.
823
824       ·   The MUA corrupted your patch; "am" would complain that the patch
825           does not apply. Look in the .git/rebase-apply/ subdirectory and see
826           what patch file contains and check for the common corruption
827           patterns mentioned above.
828
829       ·   While at it, check the info and final-commit files as well. If what
830           is in final-commit is not exactly what you would want to see in the
831           commit log message, it is very likely that the receiver would end
832           up hand editing the log message when applying your patch. Things
833           like "Hi, this is my first patch.\n" in the patch e-mail should
834           come after the three-dash line that signals the end of the commit
835           message.
836

MUA-SPECIFIC HINTS

838       Here are some hints on how to successfully submit patches inline using
839       various mailers.
840
841   GMail
842       GMail does not have any way to turn off line wrapping in the web
843       interface, so it will mangle any emails that you send. You can however
844       use "git send-email" and send your patches through the GMail SMTP
845       server, or use any IMAP email client to connect to the google IMAP
846       server and forward the emails through that.
847
848       For hints on using git send-email to send your patches through the
849       GMail SMTP server, see the EXAMPLE section of git-send-email(1).
850
851       For hints on submission using the IMAP interface, see the EXAMPLE
852       section of git-imap-send(1).
853
854   Thunderbird
855       By default, Thunderbird will both wrap emails as well as flag them as
856       being format=flowed, both of which will make the resulting email
857       unusable by Git.
858
859       There are three different approaches: use an add-on to turn off line
860       wraps, configure Thunderbird to not mangle patches, or use an external
861       editor to keep Thunderbird from mangling the patches.
862
863       Approach #1 (add-on)
864           Install the Toggle Word Wrap add-on that is available from
865           https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ It
866           adds a menu entry "Enable Word Wrap" in the composer’s "Options"
867           menu that you can tick off. Now you can compose the message as you
868           otherwise do (cut + paste, git format-patch | git imap-send, etc),
869           but you have to insert line breaks manually in any text that you
870           type.
871
872       Approach #2 (configuration)
873           Three steps:
874
875            1. Configure your mail server composition as plain text: Edit...
876               Account Settings...Composition & Addressing, uncheck "Compose
877               Messages in HTML".
878
879            2. Configure your general composition window to not wrap.
880
881               In Thunderbird 2: Edit..Preferences..Composition, wrap plain
882               text messages at 0
883
884               In Thunderbird 3: Edit..Preferences..Advanced..Config Editor.
885               Search for "mail.wrap_long_lines". Toggle it to make sure it is
886               set to false. Also, search for "mailnews.wraplength" and set
887               the value to 0.
888
889            3. Disable the use of format=flowed:
890               Edit..Preferences..Advanced..Config Editor. Search for
891               "mailnews.send_plaintext_flowed". Toggle it to make sure it is
892               set to false.
893
894           After that is done, you should be able to compose email as you
895           otherwise would (cut + paste, git format-patch | git imap-send,
896           etc), and the patches will not be mangled.
897
898       Approach #3 (external editor)
899           The following Thunderbird extensions are needed: AboutConfig from
900           http://aboutconfig.mozdev.org/ and External Editor from
901           http://globs.org/articles.php?lng=en&pg=8
902
903            1. Prepare the patch as a text file using your method of choice.
904
905            2. Before opening a compose window, use Edit→Account Settings to
906               uncheck the "Compose messages in HTML format" setting in the
907               "Composition & Addressing" panel of the account to be used to
908               send the patch.
909
910            3. In the main Thunderbird window, before you open the compose
911               window for the patch, use Tools→about:config to set the
912               following to the indicated values:
913
914                           mailnews.send_plaintext_flowed  => false
915                           mailnews.wraplength             => 0
916
917            4. Open a compose window and click the external editor icon.
918
919            5. In the external editor window, read in the patch file and exit
920               the editor normally.
921
922           Side note: it may be possible to do step 2 with about:config and
923           the following settings but no one’s tried yet.
924
925                       mail.html_compose                       => false
926                       mail.identity.default.compose_html      => false
927                       mail.identity.id?.compose_html          => false
928
929           There is a script in contrib/thunderbird-patch-inline which can
930           help you include patches with Thunderbird in an easy way. To use
931           it, do the steps above and then use the script as the external
932           editor.
933
934   KMail
935       This should help you to submit patches inline using KMail.
936
937        1. Prepare the patch as a text file.
938
939        2. Click on New Mail.
940
941        3. Go under "Options" in the Composer window and be sure that "Word
942           wrap" is not set.
943
944        4. Use Message → Insert file... and insert the patch.
945
946        5. Back in the compose window: add whatever other text you wish to the
947           message, complete the addressing and subject fields, and press
948           send.
949

BASE TREE INFORMATION

951       The base tree information block is used for maintainers or third party
952       testers to know the exact state the patch series applies to. It
953       consists of the base commit, which is a well-known commit that is part
954       of the stable part of the project history everybody else works off of,
955       and zero or more prerequisite patches, which are well-known patches in
956       flight that is not yet part of the base commit that need to be applied
957       on top of base commit in topological order before the patches can be
958       applied.
959
960       The base commit is shown as "base-commit: " followed by the 40-hex of
961       the commit object name. A prerequisite patch is shown as
962       "prerequisite-patch-id: " followed by the 40-hex patch id, which can be
963       obtained by passing the patch through the git patch-id --stable
964       command.
965
966       Imagine that on top of the public commit P, you applied well-known
967       patches X, Y and Z from somebody else, and then built your three-patch
968       series A, B, C, the history would be like:
969
970           ---P---X---Y---Z---A---B---C
971
972       With git format-patch --base=P -3 C (or variants thereof, e.g. with
973       --cover-letter or using Z..C instead of -3 C to specify the range), the
974       base tree information block is shown at the end of the first message
975       the command outputs (either the first patch, or the cover letter), like
976       this:
977
978           base-commit: P
979           prerequisite-patch-id: X
980           prerequisite-patch-id: Y
981           prerequisite-patch-id: Z
982
983       For non-linear topology, such as
984
985           ---P---X---A---M---C
986               \         /
987                Y---Z---B
988
989       You can also use git format-patch --base=P -3 C to generate patches for
990       A, B and C, and the identifiers for P, X, Y, Z are appended at the end
991       of the first message.
992
993       If set --base=auto in cmdline, it will track base commit automatically,
994       the base commit will be the merge base of tip commit of the
995       remote-tracking branch and revision-range specified in cmdline. For a
996       local branch, you need to track a remote branch by git branch
997       --set-upstream-to before using this option.
998

EXAMPLES

1000       ·   Extract commits between revisions R1 and R2, and apply them on top
1001           of the current branch using git am to cherry-pick them:
1002
1003               $ git format-patch -k --stdout R1..R2 | git am -3 -k
1004
1005       ·   Extract all commits which are in the current branch but not in the
1006           origin branch:
1007
1008               $ git format-patch origin
1009
1010           For each commit a separate file is created in the current
1011           directory.
1012
1013       ·   Extract all commits that lead to origin since the inception of the
1014           project:
1015
1016               $ git format-patch --root origin
1017
1018       ·   The same as the previous one:
1019
1020               $ git format-patch -M -B origin
1021
1022           Additionally, it detects and handles renames and complete rewrites
1023           intelligently to produce a renaming patch. A renaming patch reduces
1024           the amount of text output, and generally makes it easier to review.
1025           Note that non-Git "patch" programs won’t understand renaming
1026           patches, so use it only when you know the recipient uses Git to
1027           apply your patch.
1028
1029       ·   Extract three topmost commits from the current branch and format
1030           them as e-mailable patches:
1031
1032               $ git format-patch -3
1033

SEE ALSO

1035       git-am(1), git-send-email(1)
1036

GIT

1038       Part of the git(1) suite
1039
1040
1041
1042Git 2.30.2                        2021-03-08               GIT-FORMAT-PATCH(1)
Impressum