1GIT-FORMAT-PATCH(1) Git Manual GIT-FORMAT-PATCH(1)
2
6 git-format-patch - Prepare patches for e-mail submission
7
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
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 There are two ways to specify which commits to operate on.
39 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 2. Generic <revision range> expression (see "SPECIFYING REVISIONS"
45 section in gitrevisions(7)) means the commits in the specified
46 range.
47 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 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 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 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 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 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
82 -p, --no-stat
83 Generate plain patches without any diffstats.
84 -U<n>, --unified=<n>
86 Generate diffs with <n> lines of context instead of the usual
87 three.
88 --output=<file>
90 Output to a specific file instead of stdout.
91 --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 --indent-heuristic
98 Enable the heuristic that shifts diff hunk boundaries to make
99 patches easier to read. This is the default.
100 --no-indent-heuristic
102 Disable the indent heuristic.
103 --minimal
105 Spend extra time to make sure the smallest possible diff is
106 produced.
107 --patience
109 Generate a diff using the "patience diff" algorithm.
110 --histogram
112 Generate a diff using the "histogram diff" algorithm.
113 --anchored=<text>
115 Generate a diff using the "anchored diff" algorithm.
116 This option may be specified more than once.
118 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 --diff-algorithm={patience|minimal|histogram|myers}
125 Choose a diff algorithm. The variants are as follows:
126 default, myers
128 The basic greedy diff algorithm. Currently, this is the
129 default.
130 minimal
132 Spend extra time to make sure the smallest possible diff is
133 produced.
134 patience
136 Use "patience diff" algorithm when generating patches.
137 histogram
139 This algorithm extends the patience algorithm to "support
140 low-occurrence common elements".
141 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 --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 These parameters can also be set individually with
160 --stat-width=<width>, --stat-name-width=<name-width> and
161 --stat-count=<count>.
162 --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 --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 --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 -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 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 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 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 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 <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 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 --cumulative
232 Synonym for --dirstat=cumulative
233 --dirstat-by-file[=<param1,param2>...]
235 Synonym for --dirstat=files,param1,param2...
236 --summary
238 Output a condensed summary of extended header information such as
239 creations, renames and mode changes.
240 --no-renames
242 Turn off rename detection, even when the configuration file gives
243 the default to do so.
244 --[no-]rename-empty
246 Whether to use empty blobs as rename source.
247 --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 --binary
254 In addition to --full-index, output a binary diff that can be
255 applied with git-apply.
256 --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 -B[<n>][/<m>], --break-rewrites[=[<n>][/<m>]]
267 Break complete rewrite changes into pairs of delete and create.
268 This serves two purposes:
269 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 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 -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 -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 --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 -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 When used together with -B, omit also the preimage in the deletion
322 part of a delete/create pair.
323 -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 -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 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 <orderfile> is parsed as follows:
346 · Blank lines are ignored, so they can be used as separators for
348 readability.
349 · 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 · Each other line contains a single pattern.
355 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 --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 -a, --text
372 Treat all files as text.
373 --ignore-cr-at-eol
375 Ignore carriage-return at the end of line when doing a comparison.
376 --ignore-space-at-eol
378 Ignore changes in whitespace at EOL.
379 -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 -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 --ignore-blank-lines
390 Ignore changes whose lines are all blank.
391 -I<regex>, --ignore-matching-lines=<regex>
393 Ignore changes whose all lines match <regex>. This option may be
394 specified more than once.
395 --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 -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 --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 --no-ext-diff
413 Disallow external diff drivers.
414 --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 --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 --src-prefix=<prefix>
439 Show the given source prefix instead of "a/".
440 --dst-prefix=<prefix>
442 Show the given destination prefix instead of "b/".
443 --no-prefix
445 Do not show any source or destination prefix.
446 --line-prefix=<prefix>
448 Prepend an additional prefix to every line of output.
449 --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 For more detailed explanation on these common options, see also
459 gitdiffcore(7).
460 -<n>
462 Prepare patches from the topmost <n> commits.
463 -o <dir>, --output-directory <dir>
465 Use <dir> to store the resulting files, instead of the current
466 working directory.
467 -n, --numbered
469 Name output in [PATCH n/m] format, even with a single patch.
470 -N, --no-numbered
472 Name output in [PATCH] format.
473 --start-number <n>
475 Start numbering the patches at <n> instead of 1.
476 --numbered-files
478 Output file names will be a simple number sequence without the
479 default first line of the commit appended.
480 -k, --keep-subject
482 Do not strip/add [PATCH] from the first line of the commit log
483 message.
484 -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 --stdout
491 Print all commits to the standard output in mbox format, instead of
492 creating a file for each one.
493 --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 --no-attach
500 Disable the creation of an attachment, overriding the configuration
501 setting.
502 --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 --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 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 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 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 --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 --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 --cover-from-description=<mode>
539 Controls which parts of the cover letter will be automatically
540 populated using the branch’s description.
541 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 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 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 If <mode> is none, both the cover letter subject and body will be
556 populated with placeholder text.
557 --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 --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 --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 -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 --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 --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 --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 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 --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 --[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 --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 --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 --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 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 --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 --notes[=<ref>], --no-notes
659 Append the notes (see git-notes(1)) for the commit after the
660 three-dash line.
661 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 The default is --no-notes, unless the format.notes configuration is
672 set.
673 --[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 --signature-file=<file>
681 Works just like --signature except the signature is read from a
682 file.
683 --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 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 -q, --quiet
694 Do not print the names of the generated files to standard output.
695 --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 --zero-commit
703 Output an all-zero hash in each patch’s From header instead of the
704 hash of the commit.
705 --[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 --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 --progress
720 Show progress reports on stderr as patches are generated.
721
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 [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
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 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 arch/arm config files were slimmed down using a python script
757 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
758 Do the same for ia64 so we can have sleek & trim looking
760 ...
761 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 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 ...
776 > So we should do such-and-such.
777 Makes sense to me. How about this patch?
779 -- >8 --
781 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
782 arch/arm config files were slimmed down using a python script
784 ...
785 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 Checking for patch corruption
794 Many mailers if not set up properly will corrupt whitespace. Here are
795 two common types of corruption:
796 · Empty context lines that do not have any whitespace.
798 · Non-empty context lines that have one extra whitespace at the
800 beginning.
801 One way to test if your MUA is set up correctly is:
803 · 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 · Save that patch to a file in UNIX mailbox format. Call it a.patch,
809 say.
810 · Apply it:
812 $ git fetch <project> master:test-apply
814 $ git switch test-apply
815 $ git restore --source=HEAD --staged --worktree :/
816 $ git am a.patch
817 If it does not apply correctly, there can be various reasons.
819 · 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 · 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 · 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
838 Here are some hints on how to successfully submit patches inline using
839 various mailers.
840 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 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 For hints on submission using the IMAP interface, see the EXAMPLE
852 section of git-imap-send(1).
853 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 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 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 Approach #2 (configuration)
873 Three steps:
874 1. Configure your mail server composition as plain text: Edit...
876 Account Settings...Composition & Addressing, uncheck "Compose
877 Messages in HTML".
878 2. Configure your general composition window to not wrap.
880 In Thunderbird 2: Edit..Preferences..Composition, wrap plain
882 text messages at 0
883 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 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 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 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 1. Prepare the patch as a text file using your method of choice.
904 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 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 mailnews.send_plaintext_flowed => false
915 mailnews.wraplength => 0
916 4. Open a compose window and click the external editor icon.
918 5. In the external editor window, read in the patch file and exit
920 the editor normally.
921 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 mail.html_compose => false
926 mail.identity.default.compose_html => false
927 mail.identity.id?.compose_html => false
928 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 KMail
935 This should help you to submit patches inline using KMail.
936 1. Prepare the patch as a text file.
938 2. Click on New Mail.
940 3. Go under "Options" in the Composer window and be sure that "Word
942 wrap" is not set.
943 4. Use Message → Insert file... and insert the patch.
945 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
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 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 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 ---P---X---Y---Z---A---B---C
971 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 base-commit: P
979 prerequisite-patch-id: X
980 prerequisite-patch-id: Y
981 prerequisite-patch-id: Z
982 For non-linear topology, such as
984 ---P---X---A---M---C
986 \ /
987 Y---Z---B
988 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 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
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 $ git format-patch -k --stdout R1..R2 | git am -3 -k
1004 · Extract all commits which are in the current branch but not in the
1006 origin branch:
1007 $ git format-patch origin
1009 For each commit a separate file is created in the current
1011 directory.
1012 · Extract all commits that lead to origin since the inception of the
1014 project:
1015 $ git format-patch --root origin
1017 · The same as the previous one:
1019 $ git format-patch -M -B origin
1021 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 · Extract three topmost commits from the current branch and format
1030 them as e-mailable patches:
1031 $ git format-patch -3
1033
1035 git-am(1), git-send-email(1)
1036
1038 Part of the git(1) suite
1039Git 2.30.2 2021-03-08 GIT-FORMAT-PATCH(1)