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-notes | --notes[=<ref>]]
25 [--interdiff=<previous>]
26 [--range-diff=<previous> [--creation-factor=<percent>]]
27 [--progress]
28 [<common diff options>]
29 [ <since> | <revision range> ]
30
32 Prepare each commit with its patch in one file per commit, formatted to
33 resemble UNIX mailbox format. The output of this command is convenient
34 for e-mail submission or for use with git am.
35 There are two ways to specify which commits to operate on.
37 1. A single commit, <since>, specifies that the commits leading to the
39 tip of the current branch that are not in the history that leads to
40 the <since> to be output.
41 2. Generic <revision range> expression (see "SPECIFYING REVISIONS"
43 section in gitrevisions(7)) means the commits in the specified
44 range.
45 The first rule takes precedence in the case of a single <commit>. To
47 apply the second rule, i.e., format everything since the beginning of
48 history up until <commit>, use the --root option: git format-patch
49 --root <commit>. If you want to format only <commit> itself, you can do
50 this with git format-patch -1 <commit>.
51 By default, each output file is numbered sequentially from 1, and uses
53 the first line of the commit message (massaged for pathname safety) as
54 the filename. With the --numbered-files option, the output file names
55 will only be numbers, without the first line of the commit appended.
56 The names of the output files are printed to standard output, unless
57 the --stdout option is specified.
58 If -o is specified, output files are created in <dir>. Otherwise they
60 are created in the current working directory. The default path can be
61 set with the format.outputDirectory configuration option. The -o option
62 takes precedence over format.outputDirectory. To store patches in the
63 current working directory even when format.outputDirectory points
64 elsewhere, use -o .. All directory components will be created.
65 By default, the subject of a single patch is "[PATCH] " followed by the
67 concatenation of lines from the commit message up to the first blank
68 line (see the DISCUSSION section of git-commit(1)).
69 When multiple patches are output, the subject prefix will instead be
71 "[PATCH n/m] ". To force 1/1 to be added for a single patch, use -n. To
72 omit patch numbers from the subject, use -N.
73 If given --thread, git-format-patch will generate In-Reply-To and
75 References headers to make the second and subsequent patch mails appear
76 as replies to the first mail; this also generates a Message-Id header
77 to reference.
78
80 -p, --no-stat
81 Generate plain patches without any diffstats.
82 -U<n>, --unified=<n>
84 Generate diffs with <n> lines of context instead of the usual
85 three. Implies --patch.
86 --output=<file>
88 Output to a specific file instead of stdout.
89 --output-indicator-new=<char>, --output-indicator-old=<char>,
91 --output-indicator-context=<char>
92 Specify the character used to indicate new, old or context lines in
93 the generated patch. Normally they are +, - and ' ' respectively.
94 --indent-heuristic
96 Enable the heuristic that shifts diff hunk boundaries to make
97 patches easier to read. This is the default.
98 --no-indent-heuristic
100 Disable the indent heuristic.
101 --minimal
103 Spend extra time to make sure the smallest possible diff is
104 produced.
105 --patience
107 Generate a diff using the "patience diff" algorithm.
108 --histogram
110 Generate a diff using the "histogram diff" algorithm.
111 --anchored=<text>
113 Generate a diff using the "anchored diff" algorithm.
114 This option may be specified more than once.
116 If a line exists in both the source and destination, exists only
118 once, and starts with this text, this algorithm attempts to prevent
119 it from appearing as a deletion or addition in the output. It uses
120 the "patience diff" algorithm internally.
121 --diff-algorithm={patience|minimal|histogram|myers}
123 Choose a diff algorithm. The variants are as follows:
124 default, myers
126 The basic greedy diff algorithm. Currently, this is the
127 default.
128 minimal
130 Spend extra time to make sure the smallest possible diff is
131 produced.
132 patience
134 Use "patience diff" algorithm when generating patches.
135 histogram
137 This algorithm extends the patience algorithm to "support
138 low-occurrence common elements".
139 For instance, if you configured the diff.algorithm variable to a
141 non-default value and want to use the default one, then you have to
142 use --diff-algorithm=default option.
143 --stat[=<width>[,<name-width>[,<count>]]]
145 Generate a diffstat. By default, as much space as necessary will be
146 used for the filename part, and the rest for the graph part.
147 Maximum width defaults to terminal width, or 80 columns if not
148 connected to a terminal, and can be overridden by <width>. The
149 width of the filename part can be limited by giving another width
150 <name-width> after a comma. The width of the graph part can be
151 limited by using --stat-graph-width=<width> (affects all commands
152 generating a stat graph) or by setting diff.statGraphWidth=<width>
153 (does not affect git format-patch). By giving a third parameter
154 <count>, you can limit the output to the first <count> lines,
155 followed by ... if there are more.
156 These parameters can also be set individually with
158 --stat-width=<width>, --stat-name-width=<name-width> and
159 --stat-count=<count>.
160 --compact-summary
162 Output a condensed summary of extended header information such as
163 file creations or deletions ("new" or "gone", optionally "+l" if
164 it’s a symlink) and mode changes ("+x" or "-x" for adding or
165 removing executable bit respectively) in diffstat. The information
166 is put between the filename part and the graph part. Implies
167 --stat.
168 --numstat
170 Similar to --stat, but shows number of added and deleted lines in
171 decimal notation and pathname without abbreviation, to make it more
172 machine friendly. For binary files, outputs two - instead of saying
173 0 0.
174 --shortstat
176 Output only the last line of the --stat format containing total
177 number of modified files, as well as number of added and deleted
178 lines.
179 -X[<param1,param2,...>], --dirstat[=<param1,param2,...>]
181 Output the distribution of relative amount of changes for each
182 sub-directory. The behavior of --dirstat can be customized by
183 passing it a comma separated list of parameters. The defaults are
184 controlled by the diff.dirstat configuration variable (see git-
185 config(1)). The following parameters are available:
186 changes
188 Compute the dirstat numbers by counting the lines that have
189 been removed from the source, or added to the destination. This
190 ignores the amount of pure code movements within a file. In
191 other words, rearranging lines in a file is not counted as much
192 as other changes. This is the default behavior when no
193 parameter is given.
194 lines
196 Compute the dirstat numbers by doing the regular line-based
197 diff analysis, and summing the removed/added line counts. (For
198 binary files, count 64-byte chunks instead, since binary files
199 have no natural concept of lines). This is a more expensive
200 --dirstat behavior than the changes behavior, but it does count
201 rearranged lines within a file as much as other changes. The
202 resulting output is consistent with what you get from the other
203 --*stat options.
204 files
206 Compute the dirstat numbers by counting the number of files
207 changed. Each changed file counts equally in the dirstat
208 analysis. This is the computationally cheapest --dirstat
209 behavior, since it does not have to look at the file contents
210 at all.
211 cumulative
213 Count changes in a child directory for the parent directory as
214 well. Note that when using cumulative, the sum of the
215 percentages reported may exceed 100%. The default
216 (non-cumulative) behavior can be specified with the
217 noncumulative parameter.
218 <limit>
220 An integer parameter specifies a cut-off percent (3% by
221 default). Directories contributing less than this percentage of
222 the changes are not shown in the output.
223 Example: The following will count changed files, while ignoring
225 directories with less than 10% of the total amount of changed
226 files, and accumulating child directory counts in the parent
227 directories: --dirstat=files,10,cumulative.
228 --cumulative
230 Synonym for --dirstat=cumulative
231 --dirstat-by-file[=<param1,param2>...]
233 Synonym for --dirstat=files,param1,param2...
234 --summary
236 Output a condensed summary of extended header information such as
237 creations, renames and mode changes.
238 --no-renames
240 Turn off rename detection, even when the configuration file gives
241 the default to do so.
242 --[no-]rename-empty
244 Whether to use empty blobs as rename source.
245 --full-index
247 Instead of the first handful of characters, show the full pre- and
248 post-image blob object names on the "index" line when generating
249 patch format output.
250 --binary
252 In addition to --full-index, output a binary diff that can be
253 applied with git-apply. Implies --patch.
254 --abbrev[=<n>]
256 Instead of showing the full 40-byte hexadecimal object name in
257 diff-raw format output and diff-tree header lines, show only a
258 partial prefix. This is independent of the --full-index option
259 above, which controls the diff-patch output format. Non default
260 number of digits can be specified with --abbrev=<n>.
261 -B[<n>][/<m>], --break-rewrites[=[<n>][/<m>]]
263 Break complete rewrite changes into pairs of delete and create.
264 This serves two purposes:
265 It affects the way a change that amounts to a total rewrite of a
267 file not as a series of deletion and insertion mixed together with
268 a very few lines that happen to match textually as the context, but
269 as a single deletion of everything old followed by a single
270 insertion of everything new, and the number m controls this aspect
271 of the -B option (defaults to 60%). -B/70% specifies that less
272 than 30% of the original should remain in the result for Git to
273 consider it a total rewrite (i.e. otherwise the resulting patch
274 will be a series of deletion and insertion mixed together with
275 context lines).
276 When used with -M, a totally-rewritten file is also considered as
278 the source of a rename (usually -M only considers a file that
279 disappeared as the source of a rename), and the number n controls
280 this aspect of the -B option (defaults to 50%). -B20% specifies
281 that a change with addition and deletion compared to 20% or more of
282 the file’s size are eligible for being picked up as a possible
283 source of a rename to another file.
284 -M[<n>], --find-renames[=<n>]
286 Detect renames. If n is specified, it is a threshold on the
287 similarity index (i.e. amount of addition/deletions compared to the
288 file’s size). For example, -M90% means Git should consider a
289 delete/add pair to be a rename if more than 90% of the file hasn’t
290 changed. Without a % sign, the number is to be read as a fraction,
291 with a decimal point before it. I.e., -M5 becomes 0.5, and is thus
292 the same as -M50%. Similarly, -M05 is the same as -M5%. To limit
293 detection to exact renames, use -M100%. The default similarity
294 index is 50%.
295 -C[<n>], --find-copies[=<n>]
297 Detect copies as well as renames. See also --find-copies-harder. If
298 n is specified, it has the same meaning as for -M<n>.
299 --find-copies-harder
301 For performance reasons, by default, -C option finds copies only if
302 the original file of the copy was modified in the same changeset.
303 This flag makes the command inspect unmodified files as candidates
304 for the source of copy. This is a very expensive operation for
305 large projects, so use it with caution. Giving more than one -C
306 option has the same effect.
307 -D, --irreversible-delete
309 Omit the preimage for deletes, i.e. print only the header but not
310 the diff between the preimage and /dev/null. The resulting patch is
311 not meant to be applied with patch or git apply; this is solely for
312 people who want to just concentrate on reviewing the text after the
313 change. In addition, the output obviously lacks enough information
314 to apply such a patch in reverse, even manually, hence the name of
315 the option.
316 When used together with -B, omit also the preimage in the deletion
318 part of a delete/create pair.
319 -l<num>
321 The -M and -C options require O(n^2) processing time where n is the
322 number of potential rename/copy targets. This option prevents
323 rename/copy detection from running if the number of rename/copy
324 targets exceeds the specified number.
325 -O<orderfile>
327 Control the order in which files appear in the output. This
328 overrides the diff.orderFile configuration variable (see git-
329 config(1)). To cancel diff.orderFile, use -O/dev/null.
330 The output order is determined by the order of glob patterns in
332 <orderfile>. All files with pathnames that match the first pattern
333 are output first, all files with pathnames that match the second
334 pattern (but not the first) are output next, and so on. All files
335 with pathnames that do not match any pattern are output last, as if
336 there was an implicit match-all pattern at the end of the file. If
337 multiple pathnames have the same rank (they match the same pattern
338 but no earlier patterns), their output order relative to each other
339 is the normal order.
340 <orderfile> is parsed as follows:
342 · Blank lines are ignored, so they can be used as separators for
344 readability.
345 · Lines starting with a hash ("#") are ignored, so they can be
347 used for comments. Add a backslash ("\") to the beginning of
348 the pattern if it starts with a hash.
349 · Each other line contains a single pattern.
351 Patterns have the same syntax and semantics as patterns used for
353 fnmatch(3) without the FNM_PATHNAME flag, except a pathname also
354 matches a pattern if removing any number of the final pathname
355 components matches the pattern. For example, the pattern "foo*bar"
356 matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".
357 -a, --text
359 Treat all files as text.
360 --ignore-cr-at-eol
362 Ignore carriage-return at the end of line when doing a comparison.
363 --ignore-space-at-eol
365 Ignore changes in whitespace at EOL.
366 -b, --ignore-space-change
368 Ignore changes in amount of whitespace. This ignores whitespace at
369 line end, and considers all other sequences of one or more
370 whitespace characters to be equivalent.
371 -w, --ignore-all-space
373 Ignore whitespace when comparing lines. This ignores differences
374 even if one line has whitespace where the other line has none.
375 --ignore-blank-lines
377 Ignore changes whose lines are all blank.
378 --inter-hunk-context=<lines>
380 Show the context between diff hunks, up to the specified number of
381 lines, thereby fusing hunks that are close to each other. Defaults
382 to diff.interHunkContext or 0 if the config option is unset.
383 -W, --function-context
385 Show whole surrounding functions of changes.
386 --ext-diff
388 Allow an external diff helper to be executed. If you set an
389 external diff driver with gitattributes(5), you need to use this
390 option with git-log(1) and friends.
391 --no-ext-diff
393 Disallow external diff drivers.
394 --textconv, --no-textconv
396 Allow (or disallow) external text conversion filters to be run when
397 comparing binary files. See gitattributes(5) for details. Because
398 textconv filters are typically a one-way conversion, the resulting
399 diff is suitable for human consumption, but cannot be applied. For
400 this reason, textconv filters are enabled by default only for git-
401 diff(1) and git-log(1), but not for git-format-patch(1) or diff
402 plumbing commands.
403 --ignore-submodules[=<when>]
405 Ignore changes to submodules in the diff generation. <when> can be
406 either "none", "untracked", "dirty" or "all", which is the default.
407 Using "none" will consider the submodule modified when it either
408 contains untracked or modified files or its HEAD differs from the
409 commit recorded in the superproject and can be used to override any
410 settings of the ignore option in git-config(1) or gitmodules(5).
411 When "untracked" is used submodules are not considered dirty when
412 they only contain untracked content (but they are still scanned for
413 modified content). Using "dirty" ignores all changes to the work
414 tree of submodules, only changes to the commits stored in the
415 superproject are shown (this was the behavior until 1.7.0). Using
416 "all" hides all changes to submodules.
417 --src-prefix=<prefix>
419 Show the given source prefix instead of "a/".
420 --dst-prefix=<prefix>
422 Show the given destination prefix instead of "b/".
423 --no-prefix
425 Do not show any source or destination prefix.
426 --line-prefix=<prefix>
428 Prepend an additional prefix to every line of output.
429 --ita-invisible-in-index
431 By default entries added by "git add -N" appear as an existing
432 empty file in "git diff" and a new file in "git diff --cached".
433 This option makes the entry appear as a new file in "git diff" and
434 non-existent in "git diff --cached". This option could be reverted
435 with --ita-visible-in-index. Both options are experimental and
436 could be removed in future.
437 For more detailed explanation on these common options, see also
439 gitdiffcore(7).
440 -<n>
442 Prepare patches from the topmost <n> commits.
443 -o <dir>, --output-directory <dir>
445 Use <dir> to store the resulting files, instead of the current
446 working directory.
447 -n, --numbered
449 Name output in [PATCH n/m] format, even with a single patch.
450 -N, --no-numbered
452 Name output in [PATCH] format.
453 --start-number <n>
455 Start numbering the patches at <n> instead of 1.
456 --numbered-files
458 Output file names will be a simple number sequence without the
459 default first line of the commit appended.
460 -k, --keep-subject
462 Do not strip/add [PATCH] from the first line of the commit log
463 message.
464 -s, --signoff
466 Add Signed-off-by: line to the commit message, using the committer
467 identity of yourself. See the signoff option in git-commit(1) for
468 more information.
469 --stdout
471 Print all commits to the standard output in mbox format, instead of
472 creating a file for each one.
473 --attach[=<boundary>]
475 Create multipart/mixed attachment, the first part of which is the
476 commit message and the patch itself in the second part, with
477 Content-Disposition: attachment.
478 --no-attach
480 Disable the creation of an attachment, overriding the configuration
481 setting.
482 --inline[=<boundary>]
484 Create multipart/mixed attachment, the first part of which is the
485 commit message and the patch itself in the second part, with
486 Content-Disposition: inline.
487 --thread[=<style>], --no-thread
489 Controls addition of In-Reply-To and References headers to make the
490 second and subsequent mails appear as replies to the first. Also
491 controls generation of the Message-Id header to reference.
492 The optional <style> argument can be either shallow or deep.
494 shallow threading makes every mail a reply to the head of the
495 series, where the head is chosen from the cover letter, the
496 --in-reply-to, and the first patch mail, in this order. deep
497 threading makes every mail a reply to the previous one.
498 The default is --no-thread, unless the format.thread configuration
500 is set. If --thread is specified without a style, it defaults to
501 the style specified by format.thread if any, or else shallow.
502 Beware that the default for git send-email is to thread emails
504 itself. If you want git format-patch to take care of threading, you
505 will want to ensure that threading is disabled for git send-email.
506 --in-reply-to=<message id>
508 Make the first mail (or all the mails with --no-thread) appear as a
509 reply to the given <message id>, which avoids breaking threads to
510 provide a new patch series.
511 --ignore-if-in-upstream
513 Do not include a patch that matches a commit in <until>..<since>.
514 This will examine all patches reachable from <since> but not from
515 <until> and compare them with the patches being generated, and any
516 patch that matches is ignored.
517 --cover-from-description=<mode>
519 Controls which parts of the cover letter will be automatically
520 populated using the branch’s description.
521 If <mode> is message or default, the cover letter subject will be
523 populated with placeholder text. The body of the cover letter will
524 be populated with the branch’s description. This is the default
525 mode when no configuration nor command line option is specified.
526 If <mode> is subject, the first paragraph of the branch description
528 will populate the cover letter subject. The remainder of the
529 description will populate the body of the cover letter.
530 If <mode> is auto, if the first paragraph of the branch description
532 is greater than 100 bytes, then the mode will be message, otherwise
533 subject will be used.
534 If <mode> is none, both the cover letter subject and body will be
536 populated with placeholder text.
537 --subject-prefix=<subject prefix>
539 Instead of the standard [PATCH] prefix in the subject line, instead
540 use [<subject prefix>]. This allows for useful naming of a patch
541 series, and can be combined with the --numbered option.
542 --rfc
544 Alias for --subject-prefix="RFC PATCH". RFC means "Request For
545 Comments"; use this when sending an experimental patch for
546 discussion rather than application.
547 -v <n>, --reroll-count=<n>
549 Mark the series as the <n>-th iteration of the topic. The output
550 filenames have v<n> prepended to them, and the subject prefix
551 ("PATCH" by default, but configurable via the --subject-prefix
552 option) has ` v<n>` appended to it. E.g. --reroll-count=4 may
553 produce v4-0001-add-makefile.patch file that has "Subject: [PATCH
554 v4 1/20] Add makefile" in it.
555 --to=<email>
557 Add a To: header to the email headers. This is in addition to any
558 configured headers, and may be used multiple times. The negated
559 form --no-to discards all To: headers added so far (from config or
560 command line).
561 --cc=<email>
563 Add a Cc: header to the email headers. This is in addition to any
564 configured headers, and may be used multiple times. The negated
565 form --no-cc discards all Cc: headers added so far (from config or
566 command line).
567 --from, --from=<ident>
569 Use ident in the From: header of each commit email. If the author
570 ident of the commit is not textually identical to the provided
571 ident, place a From: header in the body of the message with the
572 original author. If no ident is given, use the committer ident.
573 Note that this option is only useful if you are actually sending
575 the emails and want to identify yourself as the sender, but retain
576 the original author (and git am will correctly pick up the in-body
577 header). Note also that git send-email already handles this
578 transformation for you, and this option should not be used if you
579 are feeding the result to git send-email.
580 --add-header=<header>
582 Add an arbitrary header to the email headers. This is in addition
583 to any configured headers, and may be used multiple times. For
584 example, --add-header="Organization: git-foo". The negated form
585 --no-add-header discards all (To:, Cc:, and custom) headers added
586 so far from config or command line.
587 --[no-]cover-letter
589 In addition to the patches, generate a cover letter file containing
590 the branch description, shortlog and the overall diffstat. You can
591 fill in a description in the file before sending it out.
592 --interdiff=<previous>
594 As a reviewer aid, insert an interdiff into the cover letter, or as
595 commentary of the lone patch of a 1-patch series, showing the
596 differences between the previous version of the patch series and
597 the series currently being formatted. previous is a single
598 revision naming the tip of the previous series which shares a
599 common base with the series being formatted (for example git
600 format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2).
601 --range-diff=<previous>
603 As a reviewer aid, insert a range-diff (see git-range-diff(1)) into
604 the cover letter, or as commentary of the lone patch of a 1-patch
605 series, showing the differences between the previous version of the
606 patch series and the series currently being formatted. previous
607 can be a single revision naming the tip of the previous series if
608 it shares a common base with the series being formatted (for
609 example git format-patch --cover-letter --range-diff=feature/v1 -3
610 feature/v2), or a revision range if the two versions of the series
611 are disjoint (for example git format-patch --cover-letter
612 --range-diff=feature/v1~3..feature/v1 -3 feature/v2).
613 Note that diff options passed to the command affect how the primary
615 product of format-patch is generated, and they are not passed to
616 the underlying range-diff machinery used to generate the
617 cover-letter material (this may change in the future).
618 --creation-factor=<percent>
620 Used with --range-diff, tweak the heuristic which matches up
621 commits between the previous and current series of patches by
622 adjusting the creation/deletion cost fudge factor. See git-range-
623 diff(1)) for details.
624 --notes[=<ref>], --no-notes
626 Append the notes (see git-notes(1)) for the commit after the
627 three-dash line.
628 The expected use case of this is to write supporting explanation
630 for the commit that does not belong to the commit log message
631 proper, and include it with the patch submission. While one can
632 simply write these explanations after format-patch has run but
633 before sending, keeping them as Git notes allows them to be
634 maintained between versions of the patch series (but see the
635 discussion of the notes.rewrite configuration options in git-
636 notes(1) to use this workflow).
637 The default is --no-notes, unless the format.notes configuration is
639 set.
640 --[no-]signature=<signature>
642 Add a signature to each message produced. Per RFC 3676 the
643 signature is separated from the body by a line with '-- ' on it. If
644 the signature option is omitted the signature defaults to the Git
645 version number.
646 --signature-file=<file>
648 Works just like --signature except the signature is read from a
649 file.
650 --suffix=.<sfx>
652 Instead of using .patch as the suffix for generated filenames, use
653 specified suffix. A common alternative is --suffix=.txt. Leaving
654 this empty will remove the .patch suffix.
655 Note that the leading character does not have to be a dot; for
657 example, you can use --suffix=-patch to get
658 0001-description-of-my-change-patch.
659 -q, --quiet
661 Do not print the names of the generated files to standard output.
662 --no-binary
664 Do not output contents of changes in binary files, instead display
665 a notice that those files changed. Patches generated using this
666 option cannot be applied properly, but they are still useful for
667 code review.
668 --zero-commit
670 Output an all-zero hash in each patch’s From header instead of the
671 hash of the commit.
672 --[no-]base[=<commit>]
674 Record the base tree information to identify the state the patch
675 series applies to. See the BASE TREE INFORMATION section below for
676 details. If <commit> is "auto", a base commit is automatically
677 chosen. The --no-base option overrides a format.useAutoBase
678 configuration.
679 --root
681 Treat the revision argument as a <revision range>, even if it is
682 just a single commit (that would normally be treated as a <since>).
683 Note that root commits included in the specified range are always
684 formatted as creation patches, independently of this flag.
685 --progress
687 Show progress reports on stderr as patches are generated.
688
690 You can specify extra mail header lines to be added to each message,
691 defaults for the subject prefix and file suffix, number patches when
692 outputting more than one patch, add "To:" or "Cc:" headers, configure
693 attachments, change the patch output directory, and sign off patches
694 with configuration variables.
695 [format]
697 headers = "Organization: git-foo\n"
698 subjectPrefix = CHANGE
699 suffix = .txt
700 numbered = auto
701 to = <email>
702 cc = <email>
703 attach [ = mime-boundary-string ]
704 signOff = true
705 outputDirectory = <directory>
706 coverLetter = auto
707 coverFromDescription = auto
708
710 The patch produced by git format-patch is in UNIX mailbox format, with
711 a fixed "magic" time stamp to indicate that the file is output from
712 format-patch rather than a real mailbox, like so:
713 From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
715 From: Tony Luck <tony.luck@intel.com>
716 Date: Tue, 13 Jul 2010 11:42:54 -0700
717 Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
718 =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
719 MIME-Version: 1.0
720 Content-Type: text/plain; charset=UTF-8
721 Content-Transfer-Encoding: 8bit
722 arch/arm config files were slimmed down using a python script
724 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
725 Do the same for ia64 so we can have sleek & trim looking
727 ...
728 Typically it will be placed in a MUA’s drafts folder, edited to add
730 timely commentary that should not go in the changelog after the three
731 dashes, and then sent as a message whose body, in our example, starts
732 with "arch/arm config files were...". On the receiving end, readers can
733 save interesting patches in a UNIX mailbox and apply them with git-
734 am(1).
735 When a patch is part of an ongoing discussion, the patch generated by
737 git format-patch can be tweaked to take advantage of the git am
738 --scissors feature. After your response to the discussion comes a line
739 that consists solely of "-- >8 --" (scissors and perforation), followed
740 by the patch with unnecessary header fields removed:
741 ...
743 > So we should do such-and-such.
744 Makes sense to me. How about this patch?
746 -- >8 --
748 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
749 arch/arm config files were slimmed down using a python script
751 ...
752 When sending a patch this way, most often you are sending your own
754 patch, so in addition to the "From $SHA1 $magic_timestamp" marker you
755 should omit From: and Date: lines from the patch file. The patch title
756 is likely to be different from the subject of the discussion the patch
757 is in response to, so it is likely that you would want to keep the
758 Subject: line, like the example above.
759 Checking for patch corruption
761 Many mailers if not set up properly will corrupt whitespace. Here are
762 two common types of corruption:
763 · Empty context lines that do not have any whitespace.
765 · Non-empty context lines that have one extra whitespace at the
767 beginning.
768 One way to test if your MUA is set up correctly is:
770 · Send the patch to yourself, exactly the way you would, except with
772 To: and Cc: lines that do not contain the list and maintainer
773 address.
774 · Save that patch to a file in UNIX mailbox format. Call it a.patch,
776 say.
777 · Apply it:
779 $ git fetch <project> master:test-apply
781 $ git switch test-apply
782 $ git restore --source=HEAD --staged --worktree :/
783 $ git am a.patch
784 If it does not apply correctly, there can be various reasons.
786 · The patch itself does not apply cleanly. That is bad but does not
788 have much to do with your MUA. You might want to rebase the patch
789 with git-rebase(1) before regenerating it in this case.
790 · The MUA corrupted your patch; "am" would complain that the patch
792 does not apply. Look in the .git/rebase-apply/ subdirectory and see
793 what patch file contains and check for the common corruption
794 patterns mentioned above.
795 · While at it, check the info and final-commit files as well. If what
797 is in final-commit is not exactly what you would want to see in the
798 commit log message, it is very likely that the receiver would end
799 up hand editing the log message when applying your patch. Things
800 like "Hi, this is my first patch.\n" in the patch e-mail should
801 come after the three-dash line that signals the end of the commit
802 message.
803
805 Here are some hints on how to successfully submit patches inline using
806 various mailers.
807 GMail
809 GMail does not have any way to turn off line wrapping in the web
810 interface, so it will mangle any emails that you send. You can however
811 use "git send-email" and send your patches through the GMail SMTP
812 server, or use any IMAP email client to connect to the google IMAP
813 server and forward the emails through that.
814 For hints on using git send-email to send your patches through the
816 GMail SMTP server, see the EXAMPLE section of git-send-email(1).
817 For hints on submission using the IMAP interface, see the EXAMPLE
819 section of git-imap-send(1).
820 Thunderbird
822 By default, Thunderbird will both wrap emails as well as flag them as
823 being format=flowed, both of which will make the resulting email
824 unusable by Git.
825 There are three different approaches: use an add-on to turn off line
827 wraps, configure Thunderbird to not mangle patches, or use an external
828 editor to keep Thunderbird from mangling the patches.
829 Approach #1 (add-on)
831 Install the Toggle Word Wrap add-on that is available from
832 https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ It
833 adds a menu entry "Enable Word Wrap" in the composer’s "Options"
834 menu that you can tick off. Now you can compose the message as you
835 otherwise do (cut + paste, git format-patch | git imap-send, etc),
836 but you have to insert line breaks manually in any text that you
837 type.
838 Approach #2 (configuration)
840 Three steps:
841 1. Configure your mail server composition as plain text: Edit...
843 Account Settings...Composition & Addressing, uncheck "Compose
844 Messages in HTML".
845 2. Configure your general composition window to not wrap.
847 In Thunderbird 2: Edit..Preferences..Composition, wrap plain
849 text messages at 0
850 In Thunderbird 3: Edit..Preferences..Advanced..Config Editor.
852 Search for "mail.wrap_long_lines". Toggle it to make sure it is
853 set to false. Also, search for "mailnews.wraplength" and set
854 the value to 0.
855 3. Disable the use of format=flowed:
857 Edit..Preferences..Advanced..Config Editor. Search for
858 "mailnews.send_plaintext_flowed". Toggle it to make sure it is
859 set to false.
860 After that is done, you should be able to compose email as you
862 otherwise would (cut + paste, git format-patch | git imap-send,
863 etc), and the patches will not be mangled.
864 Approach #3 (external editor)
866 The following Thunderbird extensions are needed: AboutConfig from
867 http://aboutconfig.mozdev.org/ and External Editor from
868 http://globs.org/articles.php?lng=en&pg=8
869 1. Prepare the patch as a text file using your method of choice.
871 2. Before opening a compose window, use Edit→Account Settings to
873 uncheck the "Compose messages in HTML format" setting in the
874 "Composition & Addressing" panel of the account to be used to
875 send the patch.
876 3. In the main Thunderbird window, before you open the compose
878 window for the patch, use Tools→about:config to set the
879 following to the indicated values:
880 mailnews.send_plaintext_flowed => false
882 mailnews.wraplength => 0
883 4. Open a compose window and click the external editor icon.
885 5. In the external editor window, read in the patch file and exit
887 the editor normally.
888 Side note: it may be possible to do step 2 with about:config and
890 the following settings but no one’s tried yet.
891 mail.html_compose => false
893 mail.identity.default.compose_html => false
894 mail.identity.id?.compose_html => false
895 There is a script in contrib/thunderbird-patch-inline which can
897 help you include patches with Thunderbird in an easy way. To use
898 it, do the steps above and then use the script as the external
899 editor.
900 KMail
902 This should help you to submit patches inline using KMail.
903 1. Prepare the patch as a text file.
905 2. Click on New Mail.
907 3. Go under "Options" in the Composer window and be sure that "Word
909 wrap" is not set.
910 4. Use Message → Insert file... and insert the patch.
912 5. Back in the compose window: add whatever other text you wish to the
914 message, complete the addressing and subject fields, and press
915 send.
916
918 The base tree information block is used for maintainers or third party
919 testers to know the exact state the patch series applies to. It
920 consists of the base commit, which is a well-known commit that is part
921 of the stable part of the project history everybody else works off of,
922 and zero or more prerequisite patches, which are well-known patches in
923 flight that is not yet part of the base commit that need to be applied
924 on top of base commit in topological order before the patches can be
925 applied.
926 The base commit is shown as "base-commit: " followed by the 40-hex of
928 the commit object name. A prerequisite patch is shown as
929 "prerequisite-patch-id: " followed by the 40-hex patch id, which can be
930 obtained by passing the patch through the git patch-id --stable
931 command.
932 Imagine that on top of the public commit P, you applied well-known
934 patches X, Y and Z from somebody else, and then built your three-patch
935 series A, B, C, the history would be like:
936 ---P---X---Y---Z---A---B---C
938 With git format-patch --base=P -3 C (or variants thereof, e.g. with
940 --cover-letter or using Z..C instead of -3 C to specify the range), the
941 base tree information block is shown at the end of the first message
942 the command outputs (either the first patch, or the cover letter), like
943 this:
944 base-commit: P
946 prerequisite-patch-id: X
947 prerequisite-patch-id: Y
948 prerequisite-patch-id: Z
949 For non-linear topology, such as
951 ---P---X---A---M---C
953 \ /
954 Y---Z---B
955 You can also use git format-patch --base=P -3 C to generate patches for
957 A, B and C, and the identifiers for P, X, Y, Z are appended at the end
958 of the first message.
959 If set --base=auto in cmdline, it will track base commit automatically,
961 the base commit will be the merge base of tip commit of the
962 remote-tracking branch and revision-range specified in cmdline. For a
963 local branch, you need to track a remote branch by git branch
964 --set-upstream-to before using this option.
965
967 · Extract commits between revisions R1 and R2, and apply them on top
968 of the current branch using git am to cherry-pick them:
969 $ git format-patch -k --stdout R1..R2 | git am -3 -k
971 · Extract all commits which are in the current branch but not in the
973 origin branch:
974 $ git format-patch origin
976 For each commit a separate file is created in the current
978 directory.
979 · Extract all commits that lead to origin since the inception of the
981 project:
982 $ git format-patch --root origin
984 · The same as the previous one:
986 $ git format-patch -M -B origin
988 Additionally, it detects and handles renames and complete rewrites
990 intelligently to produce a renaming patch. A renaming patch reduces
991 the amount of text output, and generally makes it easier to review.
992 Note that non-Git "patch" programs won’t understand renaming
993 patches, so use it only when you know the recipient uses Git to
994 apply your patch.
995 · Extract three topmost commits from the current branch and format
997 them as e-mailable patches:
998 $ git format-patch -3
1000
1002 git-am(1), git-send-email(1)
1003
1005 Part of the git(1) suite
1006Git 2.26.2 2020-04-20 GIT-FORMAT-PATCH(1)