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