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