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]
23 [--no-notes | --notes[=<ref>]]
24 [--interdiff=<previous>]
25 [--range-diff=<previous> [--creation-factor=<percent>]]
26 [--progress]
27 [<common diff options>]
28 [ <since> | <revision range> ]
29
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 --subject-prefix=<subject prefix>
519 Instead of the standard [PATCH] prefix in the subject line, instead
520 use [<subject prefix>]. This allows for useful naming of a patch
521 series, and can be combined with the --numbered option.
522 --rfc
524 Alias for --subject-prefix="RFC PATCH". RFC means "Request For
525 Comments"; use this when sending an experimental patch for
526 discussion rather than application.
527 -v <n>, --reroll-count=<n>
529 Mark the series as the <n>-th iteration of the topic. The output
530 filenames have v<n> prepended to them, and the subject prefix
531 ("PATCH" by default, but configurable via the --subject-prefix
532 option) has ` v<n>` appended to it. E.g. --reroll-count=4 may
533 produce v4-0001-add-makefile.patch file that has "Subject: [PATCH
534 v4 1/20] Add makefile" in it.
535 --to=<email>
537 Add a To: header to the email headers. This is in addition to any
538 configured headers, and may be used multiple times. The negated
539 form --no-to discards all To: headers added so far (from config or
540 command line).
541 --cc=<email>
543 Add a Cc: header to the email headers. This is in addition to any
544 configured headers, and may be used multiple times. The negated
545 form --no-cc discards all Cc: headers added so far (from config or
546 command line).
547 --from, --from=<ident>
549 Use ident in the From: header of each commit email. If the author
550 ident of the commit is not textually identical to the provided
551 ident, place a From: header in the body of the message with the
552 original author. If no ident is given, use the committer ident.
553 Note that this option is only useful if you are actually sending
555 the emails and want to identify yourself as the sender, but retain
556 the original author (and git am will correctly pick up the in-body
557 header). Note also that git send-email already handles this
558 transformation for you, and this option should not be used if you
559 are feeding the result to git send-email.
560 --add-header=<header>
562 Add an arbitrary header to the email headers. This is in addition
563 to any configured headers, and may be used multiple times. For
564 example, --add-header="Organization: git-foo". The negated form
565 --no-add-header discards all (To:, Cc:, and custom) headers added
566 so far from config or command line.
567 --[no-]cover-letter
569 In addition to the patches, generate a cover letter file containing
570 the branch description, shortlog and the overall diffstat. You can
571 fill in a description in the file before sending it out.
572 --interdiff=<previous>
574 As a reviewer aid, insert an interdiff into the cover letter, or as
575 commentary of the lone patch of a 1-patch series, showing the
576 differences between the previous version of the patch series and
577 the series currently being formatted. previous is a single
578 revision naming the tip of the previous series which shares a
579 common base with the series being formatted (for example git
580 format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2).
581 --range-diff=<previous>
583 As a reviewer aid, insert a range-diff (see git-range-diff(1)) into
584 the cover letter, or as commentary of the lone patch of a 1-patch
585 series, showing the differences between the previous version of the
586 patch series and the series currently being formatted. previous
587 can be a single revision naming the tip of the previous series if
588 it shares a common base with the series being formatted (for
589 example git format-patch --cover-letter --range-diff=feature/v1 -3
590 feature/v2), or a revision range if the two versions of the series
591 are disjoint (for example git format-patch --cover-letter
592 --range-diff=feature/v1~3..feature/v1 -3 feature/v2).
593 Note that diff options passed to the command affect how the primary
595 product of format-patch is generated, and they are not passed to
596 the underlying range-diff machinery used to generate the
597 cover-letter material (this may change in the future).
598 --creation-factor=<percent>
600 Used with --range-diff, tweak the heuristic which matches up
601 commits between the previous and current series of patches by
602 adjusting the creation/deletion cost fudge factor. See git-range-
603 diff(1)) for details.
604 --notes[=<ref>], --no-notes
606 Append the notes (see git-notes(1)) for the commit after the
607 three-dash line.
608 The expected use case of this is to write supporting explanation
610 for the commit that does not belong to the commit log message
611 proper, and include it with the patch submission. While one can
612 simply write these explanations after format-patch has run but
613 before sending, keeping them as Git notes allows them to be
614 maintained between versions of the patch series (but see the
615 discussion of the notes.rewrite configuration options in git-
616 notes(1) to use this workflow).
617 The default is --no-notes, unless the format.notes configuration is
619 set.
620 --[no-]signature=<signature>
622 Add a signature to each message produced. Per RFC 3676 the
623 signature is separated from the body by a line with '-- ' on it. If
624 the signature option is omitted the signature defaults to the Git
625 version number.
626 --signature-file=<file>
628 Works just like --signature except the signature is read from a
629 file.
630 --suffix=.<sfx>
632 Instead of using .patch as the suffix for generated filenames, use
633 specified suffix. A common alternative is --suffix=.txt. Leaving
634 this empty will remove the .patch suffix.
635 Note that the leading character does not have to be a dot; for
637 example, you can use --suffix=-patch to get
638 0001-description-of-my-change-patch.
639 -q, --quiet
641 Do not print the names of the generated files to standard output.
642 --no-binary
644 Do not output contents of changes in binary files, instead display
645 a notice that those files changed. Patches generated using this
646 option cannot be applied properly, but they are still useful for
647 code review.
648 --zero-commit
650 Output an all-zero hash in each patch’s From header instead of the
651 hash of the commit.
652 --base=<commit>
654 Record the base tree information to identify the state the patch
655 series applies to. See the BASE TREE INFORMATION section below for
656 details. If <commit> is "auto", a base commit is automatically
657 chosen.
658 --root
660 Treat the revision argument as a <revision range>, even if it is
661 just a single commit (that would normally be treated as a <since>).
662 Note that root commits included in the specified range are always
663 formatted as creation patches, independently of this flag.
664 --progress
666 Show progress reports on stderr as patches are generated.
667
669 You can specify extra mail header lines to be added to each message,
670 defaults for the subject prefix and file suffix, number patches when
671 outputting more than one patch, add "To:" or "Cc:" headers, configure
672 attachments, change the patch output directory, and sign off patches
673 with configuration variables.
674 [format]
676 headers = "Organization: git-foo\n"
677 subjectPrefix = CHANGE
678 suffix = .txt
679 numbered = auto
680 to = <email>
681 cc = <email>
682 attach [ = mime-boundary-string ]
683 signOff = true
684 outputDirectory = <directory>
685 coverLetter = auto
686
689 The patch produced by git format-patch is in UNIX mailbox format, with
690 a fixed "magic" time stamp to indicate that the file is output from
691 format-patch rather than a real mailbox, like so:
692 From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
694 From: Tony Luck <tony.luck@intel.com>
695 Date: Tue, 13 Jul 2010 11:42:54 -0700
696 Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
697 =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
698 MIME-Version: 1.0
699 Content-Type: text/plain; charset=UTF-8
700 Content-Transfer-Encoding: 8bit
701 arch/arm config files were slimmed down using a python script
703 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
704 Do the same for ia64 so we can have sleek & trim looking
706 ...
707 Typically it will be placed in a MUA’s drafts folder, edited to add
710 timely commentary that should not go in the changelog after the three
711 dashes, and then sent as a message whose body, in our example, starts
712 with "arch/arm config files were...". On the receiving end, readers can
713 save interesting patches in a UNIX mailbox and apply them with git-
714 am(1).
715 When a patch is part of an ongoing discussion, the patch generated by
717 git format-patch can be tweaked to take advantage of the git am
718 --scissors feature. After your response to the discussion comes a line
719 that consists solely of "-- >8 --" (scissors and perforation), followed
720 by the patch with unnecessary header fields removed:
721 ...
723 > So we should do such-and-such.
724 Makes sense to me. How about this patch?
726 -- >8 --
728 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
729 arch/arm config files were slimmed down using a python script
731 ...
732 When sending a patch this way, most often you are sending your own
735 patch, so in addition to the "From $SHA1 $magic_timestamp" marker you
736 should omit From: and Date: lines from the patch file. The patch title
737 is likely to be different from the subject of the discussion the patch
738 is in response to, so it is likely that you would want to keep the
739 Subject: line, like the example above.
740 Checking for patch corruption
742 Many mailers if not set up properly will corrupt whitespace. Here are
743 two common types of corruption:
744 · Empty context lines that do not have any whitespace.
746 · Non-empty context lines that have one extra whitespace at the
748 beginning.
749 One way to test if your MUA is set up correctly is:
751 · Send the patch to yourself, exactly the way you would, except with
753 To: and Cc: lines that do not contain the list and maintainer
754 address.
755 · Save that patch to a file in UNIX mailbox format. Call it a.patch,
757 say.
758 · Apply it:
760 $ git fetch <project> master:test-apply
762 $ git switch test-apply
763 $ git restore --source=HEAD --staged --worktree :/
764 $ git am a.patch
765 If it does not apply correctly, there can be various reasons.
767 · The patch itself does not apply cleanly. That is bad but does not
769 have much to do with your MUA. You might want to rebase the patch
770 with git-rebase(1) before regenerating it in this case.
771 · The MUA corrupted your patch; "am" would complain that the patch
773 does not apply. Look in the .git/rebase-apply/ subdirectory and see
774 what patch file contains and check for the common corruption
775 patterns mentioned above.
776 · While at it, check the info and final-commit files as well. If what
778 is in final-commit is not exactly what you would want to see in the
779 commit log message, it is very likely that the receiver would end
780 up hand editing the log message when applying your patch. Things
781 like "Hi, this is my first patch.\n" in the patch e-mail should
782 come after the three-dash line that signals the end of the commit
783 message.
784
786 Here are some hints on how to successfully submit patches inline using
787 various mailers.
788 GMail
790 GMail does not have any way to turn off line wrapping in the web
791 interface, so it will mangle any emails that you send. You can however
792 use "git send-email" and send your patches through the GMail SMTP
793 server, or use any IMAP email client to connect to the google IMAP
794 server and forward the emails through that.
795 For hints on using git send-email to send your patches through the
797 GMail SMTP server, see the EXAMPLE section of git-send-email(1).
798 For hints on submission using the IMAP interface, see the EXAMPLE
800 section of git-imap-send(1).
801 Thunderbird
803 By default, Thunderbird will both wrap emails as well as flag them as
804 being format=flowed, both of which will make the resulting email
805 unusable by Git.
806 There are three different approaches: use an add-on to turn off line
808 wraps, configure Thunderbird to not mangle patches, or use an external
809 editor to keep Thunderbird from mangling the patches.
810 Approach #1 (add-on)
812 Install the Toggle Word Wrap add-on that is available from
813 https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ It
814 adds a menu entry "Enable Word Wrap" in the composer’s "Options"
815 menu that you can tick off. Now you can compose the message as you
816 otherwise do (cut + paste, git format-patch | git imap-send, etc),
817 but you have to insert line breaks manually in any text that you
818 type.
819 Approach #2 (configuration)
821 Three steps:
822 1. Configure your mail server composition as plain text:
824 Edit...Account Settings...Composition & Addressing, uncheck
825 "Compose Messages in HTML".
826 2. Configure your general composition window to not wrap.
828 In Thunderbird 2: Edit..Preferences..Composition, wrap plain
830 text messages at 0
831 In Thunderbird 3: Edit..Preferences..Advanced..Config Editor.
833 Search for "mail.wrap_long_lines". Toggle it to make sure it is
834 set to false. Also, search for "mailnews.wraplength" and set
835 the value to 0.
836 3. Disable the use of format=flowed:
838 Edit..Preferences..Advanced..Config Editor. Search for
839 "mailnews.send_plaintext_flowed". Toggle it to make sure it is
840 set to false.
841 After that is done, you should be able to compose email as you
843 otherwise would (cut + paste, git format-patch | git imap-send,
844 etc), and the patches will not be mangled.
845 Approach #3 (external editor)
847 The following Thunderbird extensions are needed: AboutConfig from
848 http://aboutconfig.mozdev.org/ and External Editor from
849 http://globs.org/articles.php?lng=en&pg=8
850 1. Prepare the patch as a text file using your method of choice.
852 2. Before opening a compose window, use Edit→Account Settings to
854 uncheck the "Compose messages in HTML format" setting in the
855 "Composition & Addressing" panel of the account to be used to
856 send the patch.
857 3. In the main Thunderbird window, before you open the compose
859 window for the patch, use Tools→about:config to set the
860 following to the indicated values:
861 mailnews.send_plaintext_flowed => false
863 mailnews.wraplength => 0
864 4. Open a compose window and click the external editor icon.
867 5. In the external editor window, read in the patch file and exit
869 the editor normally.
870 Side note: it may be possible to do step 2 with about:config and
872 the following settings but no one’s tried yet.
873 mail.html_compose => false
875 mail.identity.default.compose_html => false
876 mail.identity.id?.compose_html => false
877 There is a script in contrib/thunderbird-patch-inline which can
880 help you include patches with Thunderbird in an easy way. To use
881 it, do the steps above and then use the script as the external
882 editor.
883 KMail
885 This should help you to submit patches inline using KMail.
886 1. Prepare the patch as a text file.
888 2. Click on New Mail.
890 3. Go under "Options" in the Composer window and be sure that "Word
892 wrap" is not set.
893 4. Use Message → Insert file... and insert the patch.
895 5. Back in the compose window: add whatever other text you wish to the
897 message, complete the addressing and subject fields, and press
898 send.
899
901 The base tree information block is used for maintainers or third party
902 testers to know the exact state the patch series applies to. It
903 consists of the base commit, which is a well-known commit that is part
904 of the stable part of the project history everybody else works off of,
905 and zero or more prerequisite patches, which are well-known patches in
906 flight that is not yet part of the base commit that need to be applied
907 on top of base commit in topological order before the patches can be
908 applied.
909 The base commit is shown as "base-commit: " followed by the 40-hex of
911 the commit object name. A prerequisite patch is shown as
912 "prerequisite-patch-id: " followed by the 40-hex patch id, which can be
913 obtained by passing the patch through the git patch-id --stable
914 command.
915 Imagine that on top of the public commit P, you applied well-known
917 patches X, Y and Z from somebody else, and then built your three-patch
918 series A, B, C, the history would be like:
919 ---P---X---Y---Z---A---B---C
921 With git format-patch --base=P -3 C (or variants thereof, e.g. with
923 --cover-letter or using Z..C instead of -3 C to specify the range), the
924 base tree information block is shown at the end of the first message
925 the command outputs (either the first patch, or the cover letter), like
926 this:
927 base-commit: P
929 prerequisite-patch-id: X
930 prerequisite-patch-id: Y
931 prerequisite-patch-id: Z
932 For non-linear topology, such as
935 ---P---X---A---M---C
937 \ /
938 Y---Z---B
939 You can also use git format-patch --base=P -3 C to generate patches for
941 A, B and C, and the identifiers for P, X, Y, Z are appended at the end
942 of the first message.
943 If set --base=auto in cmdline, it will track base commit automatically,
945 the base commit will be the merge base of tip commit of the
946 remote-tracking branch and revision-range specified in cmdline. For a
947 local branch, you need to track a remote branch by git branch
948 --set-upstream-to before using this option.
949
951 · Extract commits between revisions R1 and R2, and apply them on top
952 of the current branch using git am to cherry-pick them:
953 $ git format-patch -k --stdout R1..R2 | git am -3 -k
955 · Extract all commits which are in the current branch but not in the
958 origin branch:
959 $ git format-patch origin
961 For each commit a separate file is created in the current
963 directory.
964 · Extract all commits that lead to origin since the inception of the
966 project:
967 $ git format-patch --root origin
969 · The same as the previous one:
972 $ git format-patch -M -B origin
974 Additionally, it detects and handles renames and complete rewrites
976 intelligently to produce a renaming patch. A renaming patch reduces
977 the amount of text output, and generally makes it easier to review.
978 Note that non-Git "patch" programs won’t understand renaming
979 patches, so use it only when you know the recipient uses Git to
980 apply your patch.
981 · Extract three topmost commits from the current branch and format
983 them as e-mailable patches:
984 $ git format-patch -3
986
989 git-am(1), git-send-email(1)
990
992 Part of the git(1) suite
993Git 2.24.1 12/10/2019 GIT-FORMAT-PATCH(1)