1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.5.2" />
7 <title>git-format-patch(
1)
</title>
8 <style type=
"text/css">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.5em;
116 margin-bottom: 1.5em;
118 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
119 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
120 div
.admonitionblock
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.0em;
131 div
.content
{ /* Block element content. */
135 /* Block element titles. */
136 div
.title
, caption
.title
{
138 font-family: sans-serif
;
142 margin-bottom: 0.5em;
148 td div
.title:first-child
{
151 div
.content div
.title:first-child
{
154 div
.content
+ div
.title
{
158 div
.sidebarblock
> div
.content
{
160 border: 1px solid silver
;
164 div
.listingblock
> div
.content
{
165 border: 1px solid silver
;
170 div
.quoteblock
, div
.verseblock
{
174 border-left: 5px solid
#dddddd;
178 div
.quoteblock
> div
.attribution
{
183 div
.verseblock
> div
.content
{
186 div
.verseblock
> div
.attribution
{
190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 div
.verseblock
+ div
.attribution
{
195 div
.admonitionblock
.icon
{
199 text-decoration: underline
;
201 padding-right: 0.5em;
203 div
.admonitionblock td
.content
{
205 border-left: 3px solid
#dddddd;
208 div
.exampleblock
> div
.content
{
209 border-left: 3px solid
#dddddd;
213 div
.imageblock div
.content
{ padding-left: 0; }
214 span
.image img
{ border-style: none
; }
215 a
.image:visited
{ color: white
; }
219 margin-bottom: 0.8em;
232 list-style-position: outside
;
235 list-style-type: decimal
;
238 list-style-type: lower-alpha
;
241 list-style-type: upper-alpha
;
244 list-style-type: lower-roman
;
247 list-style-type: upper-roman
;
250 div
.compact ul
, div
.compact ol
,
251 div
.compact p
, div
.compact p
,
252 div
.compact div
, div
.compact div
{
254 margin-bottom: 0.1em;
257 div
.tableblock
> table
{
258 border: 3px solid
#527bbd;
260 thead
, p
.table
.header
{
261 font-family: sans-serif
;
273 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 div
.tableblock
> table
[frame
="void"] {
277 div
.tableblock
> table
[frame
="hsides"] {
278 border-left-style: none
;
279 border-right-style: none
;
281 div
.tableblock
> table
[frame
="vsides"] {
282 border-top-style: none
;
283 border-bottom-style: none
;
289 margin-bottom: 0.8em;
292 padding-bottom: 15px;
294 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
300 padding-right: 0.8em;
306 div
.hdlist
.compact tr
{
315 .footnote, .footnoteref {
319 span
.footnote
, span
.footnoteref
{
320 vertical-align: super
;
324 margin: 20px 0 20px 0;
328 #footnotes div
.footnote
{
334 border-top: 1px solid silver
;
344 div#footer-badges
{ display: none
; }
348 margin-bottom: 2.5em;
353 font-family: sans-serif
;
357 margin-bottom: 0.1em;
360 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
376 /* Overrides for manpage documents */
379 padding-bottom: 0.5em;
380 border-top: 2px solid silver
;
381 border-bottom: 2px solid silver
;
391 div#toc
{ display: none
; }
394 /* Workarounds for IE6's broken and incomplete CSS2. */
396 div
.sidebar-content
{
398 border: 1px solid silver
;
401 div
.sidebar-title
, div
.image-title
{
403 font-family: sans-serif
;
406 margin-bottom: 0.5em;
409 div
.listingblock div
.content
{
410 border: 1px solid silver
;
415 div
.quoteblock-attribution
{
420 div
.verseblock-content
{
423 div
.verseblock-attribution
{
428 div
.exampleblock-content
{
429 border-left: 3px solid
#dddddd;
433 /* IE6 sets dynamically generated links as visited. */
434 div#toc
a:visited
{ color: blue
; }
436 <script type=
"text/javascript">
438 window
.onload = function(){asciidoc
.footnotes();}
439 var asciidoc
= { // Namespace.
441 /////////////////////////////////////////////////////////////////////
442 // Table Of Contents generator
443 /////////////////////////////////////////////////////////////////////
445 /* Author: Mihai Bazon, September 2002
446 * http://students.infoiasi.ro/~mishoo
448 * Table Of Content generator
451 * Feel free to use this script under the terms of the GNU General Public
452 * License, as long as you do not remove or alter this notice.
455 /* modified by Troy D. Hanson, September 2006. License: GPL */
456 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
459 toc: function (toclevels
) {
461 function getText(el
) {
463 for (var i
= el
.firstChild
; i
!= null; i
= i
.nextSibling
) {
464 if (i
.nodeType
== 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
466 else if (i
.firstChild
!= null)
472 function TocEntry(el
, text
, toclevel
) {
475 this.toclevel
= toclevel
;
478 function tocEntries(el
, toclevels
) {
479 var result
= new Array
;
480 var re
= new RegExp('[hH]([2-'+(toclevels
+1)+'])');
481 // Function that scans the DOM tree for header elements (the DOM2
482 // nodeIterator API would be a better technique but not supported by all
484 var iterate = function (el
) {
485 for (var i
= el
.firstChild
; i
!= null; i
= i
.nextSibling
) {
486 if (i
.nodeType
== 1 /* Node.ELEMENT_NODE */) {
487 var mo
= re
.exec(i
.tagName
);
488 if (mo
&& (i
.getAttribute("class") || i
.getAttribute("className")) != "float") {
489 result
[result
.length
] = new TocEntry(i
, getText(i
), mo
[1]-1);
499 var toc
= document
.getElementById("toc");
500 var entries
= tocEntries(document
.getElementById("content"), toclevels
);
501 for (var i
= 0; i
< entries
.length
; ++i
) {
502 var entry
= entries
[i
];
503 if (entry
.element
.id
== "")
504 entry
.element
.id
= "_toc_" + i
;
505 var a
= document
.createElement("a");
506 a
.href
= "#" + entry
.element
.id
;
507 a
.appendChild(document
.createTextNode(entry
.text
));
508 var div
= document
.createElement("div");
510 div
.className
= "toclevel" + entry
.toclevel
;
511 toc
.appendChild(div
);
513 if (entries
.length
== 0)
514 toc
.parentNode
.removeChild(toc
);
518 /////////////////////////////////////////////////////////////////////
519 // Footnotes generator
520 /////////////////////////////////////////////////////////////////////
522 /* Based on footnote generation code from:
523 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
526 footnotes: function () {
527 var cont
= document
.getElementById("content");
528 var noteholder
= document
.getElementById("footnotes");
529 var spans
= cont
.getElementsByTagName("span");
532 for (i
=0; i
<spans
.length
; i
++) {
533 if (spans
[i
].className
== "footnote") {
535 // Use [\s\S] in place of . so multi-line matches work.
536 // Because JavaScript has no s (dotall) regex flag.
537 note
= spans
[i
].innerHTML
.match(/\s*\[([\s\S]*)]\s*/)[1];
538 noteholder
.innerHTML
+=
539 "<div class='footnote' id='_footnote_" + n
+ "'>" +
540 "<a href='#_footnoteref_" + n
+ "' title='Return to text'>" +
541 n
+ "</a>. " + note
+ "</div>";
543 "[<a id='_footnoteref_" + n
+ "' href='#_footnote_" + n
+
544 "' title='View footnote' class='footnote'>" + n
+ "</a>]";
545 var id
=spans
[i
].getAttribute("id");
546 if (id
!= null) refs
["#"+id
] = n
;
550 noteholder
.parentNode
.removeChild(noteholder
);
552 // Process footnoterefs.
553 for (i
=0; i
<spans
.length
; i
++) {
554 if (spans
[i
].className
== "footnoteref") {
555 var href
= spans
[i
].getElementsByTagName("a")[0].getAttribute("href");
556 href
= href
.match(/#.*/)[0]; // Because IE return full URL.
559 "[<a href='#_footnote_" + n
+
560 "' title='View footnote' class='footnote'>" + n
+ "</a>]";
573 git-format-patch(
1) Manual Page
576 <div class=
"sectionbody">
577 <p>git-format-patch -
578 Prepare patches for e-mail submission
583 <h2 id=
"_synopsis">SYNOPSIS
</h2>
584 <div class=
"sectionbody">
585 <div class=
"verseblock">
586 <div class=
"verseblock-content"><em>git format-patch
</em> [-k] [(-o|--output-directory)
<dir
> | --stdout]
587 [--no-thread | --thread[=
<style
>]]
588 [(--attach|--inline)[=
<boundary
>] | --no-attach]
590 [--signature=
<signature
> | --no-signature]
591 [-n | --numbered | -N | --no-numbered]
592 [--start-number
<n
>] [--numbered-files]
593 [--in-reply-to=Message-Id] [--suffix=.
<sfx
>]
594 [--ignore-if-in-upstream]
595 [--subject-prefix=Subject-Prefix]
596 [--to=
<email
>] [--cc=
<email
>]
597 [--cover-letter] [--quiet]
598 [
<common diff options
>]
599 [
<since
> |
<revision range
> ]
</div>
600 <div class=
"verseblock-attribution">
603 <h2 id=
"_description">DESCRIPTION
</h2>
604 <div class=
"sectionbody">
605 <div class=
"paragraph"><p>Prepare each commit with its patch in
606 one file per commit, formatted to resemble UNIX mailbox format.
607 The output of this command is convenient for e-mail submission or
608 for use with
<em>git am
</em>.
</p></div>
609 <div class=
"paragraph"><p>There are two ways to specify which commits to operate on.
</p></div>
610 <div class=
"olist arabic"><ol class=
"arabic">
613 A single commit,
<since
>, specifies that the commits leading
614 to the tip of the current branch that are not in the history
615 that leads to the
<since
> to be output.
620 Generic
<revision range
> expression (see
"SPECIFYING
621 REVISIONS" section in
<a href=
"gitrevisions.html">gitrevisions(
7)
</a>) means the
622 commits in the specified range.
626 <div class=
"paragraph"><p>The first rule takes precedence in the case of a single
<commit
>. To
627 apply the second rule, i.e., format everything since the beginning of
628 history up until
<commit
>, use the
<em>--root
</em> option:
<tt>git format-patch
629 --root
<commit
></tt>. If you want to format only
<commit
> itself, you
630 can do this with
<tt>git format-patch -
1 <commit
></tt>.
</p></div>
631 <div class=
"paragraph"><p>By default, each output file is numbered sequentially from
1, and uses the
632 first line of the commit message (massaged for pathname safety) as
633 the filename. With the
<tt>--numbered-files
</tt> option, the output file names
634 will only be numbers, without the first line of the commit appended.
635 The names of the output files are printed to standard
636 output, unless the
<tt>--stdout
</tt> option is specified.
</p></div>
637 <div class=
"paragraph"><p>If
<tt>-o
</tt> is specified, output files are created in
<dir
>. Otherwise
638 they are created in the current working directory.
</p></div>
639 <div class=
"paragraph"><p>By default, the subject of a single patch is
"[PATCH] First Line" and
640 the subject when multiple patches are output is
"[PATCH n/m] First
641 Line". To force
1/
1 to be added for a single patch, use
<tt>-n
</tt>. To omit
642 patch numbers from the subject, use
<tt>-N
</tt>.
</p></div>
643 <div class=
"paragraph"><p>If given
<tt>--thread
</tt>,
<tt>git-format-patch
</tt> will generate
<tt>In-Reply-To
</tt> and
644 <tt>References
</tt> headers to make the second and subsequent patch mails appear
645 as replies to the first mail; this also generates a
<tt>Message-Id
</tt> header to
648 <h2 id=
"_options">OPTIONS
</h2>
649 <div class=
"sectionbody">
650 <div class=
"dlist"><dl>
659 Generate plain patches without any diffstats.
670 Generate diffs with
<n
> lines of context instead of
679 Generate a diff using the
"patience diff" algorithm.
683 --stat[=
<width
>[,
<name-width
>[,
<count
>]]]
687 Generate a diffstat. You can override the default
688 output width for
80-column terminal by
<tt>--stat=
<width
></tt>.
689 The width of the filename part can be controlled by
690 giving another width to it separated by a comma.
691 By giving a third parameter
<tt><count
></tt>, you can limit the
692 output to the first
<tt><count
></tt> lines, followed by
693 <tt>…</tt> if there are more.
695 <div class=
"paragraph"><p>These parameters can also be set individually with
<tt>--stat-width=
<width
></tt>,
696 <tt>--stat-name-width=
<name-width
></tt> and
<tt>--stat-count=
<count
></tt>.
</p></div>
703 Similar to
<tt>--stat
</tt>, but shows number of added and
704 deleted lines in decimal notation and pathname without
705 abbreviation, to make it more machine friendly. For
706 binary files, outputs two
<tt>-
</tt> instead of saying
715 Output only the last line of the
<tt>--stat
</tt> format containing total
716 number of modified files, as well as number of added and deleted
721 --dirstat[=
<param1,param2,
…>]
725 Output the distribution of relative amount of changes for each
726 sub-directory. The behavior of
<tt>--dirstat
</tt> can be customized by
727 passing it a comma separated list of parameters.
728 The defaults are controlled by the
<tt>diff.dirstat
</tt> configuration
729 variable (see
<a href=
"git-config.html">git-config(
1)
</a>).
730 The following parameters are available:
732 <div class=
"dlist"><dl>
738 Compute the dirstat numbers by counting the lines that have been
739 removed from the source, or added to the destination. This ignores
740 the amount of pure code movements within a file. In other words,
741 rearranging lines in a file is not counted as much as other changes.
742 This is the default behavior when no parameter is given.
750 Compute the dirstat numbers by doing the regular line-based diff
751 analysis, and summing the removed/added line counts. (For binary
752 files, count
64-byte chunks instead, since binary files have no
753 natural concept of lines). This is a more expensive
<tt>--dirstat
</tt>
754 behavior than the
<tt>changes
</tt> behavior, but it does count rearranged
755 lines within a file as much as other changes. The resulting output
756 is consistent with what you get from the other
<tt>--*stat
</tt> options.
764 Compute the dirstat numbers by counting the number of files changed.
765 Each changed file counts equally in the dirstat analysis. This is
766 the computationally cheapest
<tt>--dirstat
</tt> behavior, since it does
767 not have to look at the file contents at all.
775 Count changes in a child directory for the parent directory as well.
776 Note that when using
<tt>cumulative
</tt>, the sum of the percentages
777 reported may exceed
100%. The default (non-cumulative) behavior can
778 be specified with the
<tt>noncumulative
</tt> parameter.
786 An integer parameter specifies a cut-off percent (
3% by default).
787 Directories contributing less than this percentage of the changes
788 are not shown in the output.
792 <div class=
"paragraph"><p>Example: The following will count changed files, while ignoring
793 directories with less than
10% of the total amount of changed files,
794 and accumulating child directory counts in the parent directories:
795 <tt>--dirstat=files,
10,cumulative
</tt>.
</p></div>
802 Output a condensed summary of extended header information
803 such as creations, renames and mode changes.
811 Turn off rename detection, even when the configuration
812 file gives the default to do so.
820 Instead of the first handful of characters, show the full
821 pre- and post-image blob object names on the
"index"
822 line when generating patch format output.
830 In addition to
<tt>--full-index
</tt>, output a binary diff that
831 can be applied with
<tt>git-apply
</tt>.
839 Instead of showing the full
40-byte hexadecimal object
840 name in diff-raw format output and diff-tree header
841 lines, show only a partial prefix. This is
842 independent of the
<tt>--full-index
</tt> option above, which controls
843 the diff-patch output format. Non default number of
844 digits can be specified with
<tt>--abbrev=
<n
></tt>.
848 -B[
<n
>][/
<m
>]
851 --break-rewrites[=[
<n
>][/
<m
>]]
855 Break complete rewrite changes into pairs of delete and
856 create. This serves two purposes:
858 <div class=
"paragraph"><p>It affects the way a change that amounts to a total rewrite of a file
859 not as a series of deletion and insertion mixed together with a very
860 few lines that happen to match textually as the context, but as a
861 single deletion of everything old followed by a single insertion of
862 everything new, and the number
<tt>m
</tt> controls this aspect of the -B
863 option (defaults to
60%).
<tt>-B/
70%
</tt> specifies that less than
30% of the
864 original should remain in the result for git to consider it a total
865 rewrite (i.e. otherwise the resulting patch will be a series of
866 deletion and insertion mixed together with context lines).
</p></div>
867 <div class=
"paragraph"><p>When used with -M, a totally-rewritten file is also considered as the
868 source of a rename (usually -M only considers a file that disappeared
869 as the source of a rename), and the number
<tt>n
</tt> controls this aspect of
870 the -B option (defaults to
50%).
<tt>-B20%
</tt> specifies that a change with
871 addition and deletion compared to
20% or more of the file
’s size are
872 eligible for being picked up as a possible source of a rename to
873 another file.
</p></div>
879 --find-renames[=
<n
>]
884 If
<tt>n
</tt> is specified, it is a threshold on the similarity
885 index (i.e. amount of addition/deletions compared to the
886 file
’s size). For example,
<tt>-M90%
</tt> means git should consider a
887 delete/add pair to be a rename if more than
90% of the file
888 hasn
’t changed.
895 --find-copies[=
<n
>]
899 Detect copies as well as renames. See also
<tt>--find-copies-harder
</tt>.
900 If
<tt>n
</tt> is specified, it has the same meaning as for
<tt>-M
<n
></tt>.
908 For performance reasons, by default,
<tt>-C
</tt> option finds copies only
909 if the original file of the copy was modified in the same
910 changeset. This flag makes the command
911 inspect unmodified files as candidates for the source of
912 copy. This is a very expensive operation for large
913 projects, so use it with caution. Giving more than one
914 <tt>-C
</tt> option has the same effect.
921 --irreversible-delete
925 Omit the preimage for deletes, i.e. print only the header but not
926 the diff between the preimage and
<tt>/dev/null
</tt>. The resulting patch
927 is not meant to be applied with
<tt>patch
</tt> nor
<tt>git apply
</tt>; this is
928 solely for people who want to just concentrate on reviewing the
929 text after the change. In addition, the output obviously lack
930 enough information to apply such a patch in reverse, even manually,
931 hence the name of the option.
933 <div class=
"paragraph"><p>When used together with
<tt>-B
</tt>, omit also the preimage in the deletion part
934 of a delete/create pair.
</p></div>
941 The
<tt>-M
</tt> and
<tt>-C
</tt> options require O(n^
2) processing time where n
942 is the number of potential rename/copy targets. This
943 option prevents rename/copy detection from running if
944 the number of rename/copy targets exceeds the specified
953 Output the patch in the order specified in the
954 <orderfile
>, which has one shell glob pattern per line.
965 Treat all files as text.
969 --ignore-space-at-eol
973 Ignore changes in whitespace at EOL.
980 --ignore-space-change
984 Ignore changes in amount of whitespace. This ignores whitespace
985 at line end, and considers all other sequences of one or
986 more whitespace characters to be equivalent.
997 Ignore whitespace when comparing lines. This ignores
998 differences even if one line has whitespace where the other
1002 <dt class=
"hdlist1">
1003 --inter-hunk-context=
<lines
>
1007 Show the context between diff hunks, up to the specified number
1008 of lines, thereby fusing hunks that are close to each other.
1011 <dt class=
"hdlist1">
1016 Allow an external diff helper to be executed. If you set an
1017 external diff driver with
<a href=
"gitattributes.html">gitattributes(
5)
</a>, you need
1018 to use this option with
<a href=
"git-log.html">git-log(
1)
</a> and friends.
1021 <dt class=
"hdlist1">
1026 Disallow external diff drivers.
1029 <dt class=
"hdlist1">
1032 <dt class=
"hdlist1">
1037 Allow (or disallow) external text conversion filters to be run
1038 when comparing binary files. See
<a href=
"gitattributes.html">gitattributes(
5)
</a> for
1039 details. Because textconv filters are typically a one-way
1040 conversion, the resulting diff is suitable for human
1041 consumption, but cannot be applied. For this reason, textconv
1042 filters are enabled by default only for
<a href=
"git-diff.html">git-diff(
1)
</a> and
1043 <a href=
"git-log.html">git-log(
1)
</a>, but not for
<a href=
"git-format-patch.html">git-format-patch(
1)
</a> or
1044 diff plumbing commands.
1047 <dt class=
"hdlist1">
1048 --ignore-submodules[=
<when
>]
1052 Ignore changes to submodules in the diff generation.
<when
> can be
1053 either
"none",
"untracked",
"dirty" or
"all", which is the default
1054 Using
"none" will consider the submodule modified when it either contains
1055 untracked or modified files or its HEAD differs from the commit recorded
1056 in the superproject and can be used to override any settings of the
1057 <em>ignore
</em> option in
<a href=
"git-config.html">git-config(
1)
</a> or
<a href=
"gitmodules.html">gitmodules(
5)
</a>. When
1058 "untracked" is used submodules are not considered dirty when they only
1059 contain untracked content (but they are still scanned for modified
1060 content). Using
"dirty" ignores all changes to the work tree of submodules,
1061 only changes to the commits stored in the superproject are shown (this was
1062 the behavior until
1.7.0). Using
"all" hides all changes to submodules.
1065 <dt class=
"hdlist1">
1066 --src-prefix=
<prefix
>
1070 Show the given source prefix instead of
"a/".
1073 <dt class=
"hdlist1">
1074 --dst-prefix=
<prefix
>
1078 Show the given destination prefix instead of
"b/".
1081 <dt class=
"hdlist1">
1086 Do not show any source or destination prefix.
1090 <div class=
"paragraph"><p>For more detailed explanation on these common options, see also
1091 <a href=
"gitdiffcore.html">gitdiffcore(
7)
</a>.
</p></div>
1092 <div class=
"dlist"><dl>
1093 <dt class=
"hdlist1">
1098 Prepare patches from the topmost
<n
> commits.
1101 <dt class=
"hdlist1">
1104 <dt class=
"hdlist1">
1105 --output-directory
<dir
>
1109 Use
<dir
> to store the resulting files, instead of the
1110 current working directory.
1113 <dt class=
"hdlist1">
1116 <dt class=
"hdlist1">
1121 Name output in
<em>[PATCH n/m]
</em> format, even with a single patch.
1124 <dt class=
"hdlist1">
1127 <dt class=
"hdlist1">
1132 Name output in
<em>[PATCH]
</em> format.
1135 <dt class=
"hdlist1">
1136 --start-number
<n
>
1140 Start numbering the patches at
<n
> instead of
1.
1143 <dt class=
"hdlist1">
1148 Output file names will be a simple number sequence
1149 without the default first line of the commit appended.
1152 <dt class=
"hdlist1">
1155 <dt class=
"hdlist1">
1160 Do not strip/add
<em>[PATCH]
</em> from the first line of the
1164 <dt class=
"hdlist1">
1167 <dt class=
"hdlist1">
1172 Add
<tt>Signed-off-by:
</tt> line to the commit message, using
1173 the committer identity of yourself.
1176 <dt class=
"hdlist1">
1181 Print all commits to the standard output in mbox format,
1182 instead of creating a file for each one.
1185 <dt class=
"hdlist1">
1186 --attach[=
<boundary
>]
1190 Create multipart/mixed attachment, the first part of
1191 which is the commit message and the patch itself in the
1192 second part, with
<tt>Content-Disposition: attachment
</tt>.
1195 <dt class=
"hdlist1">
1200 Disable the creation of an attachment, overriding the
1201 configuration setting.
1204 <dt class=
"hdlist1">
1205 --inline[=
<boundary
>]
1209 Create multipart/mixed attachment, the first part of
1210 which is the commit message and the patch itself in the
1211 second part, with
<tt>Content-Disposition: inline
</tt>.
1214 <dt class=
"hdlist1">
1215 --thread[=
<style
>]
1217 <dt class=
"hdlist1">
1222 Controls addition of
<tt>In-Reply-To
</tt> and
<tt>References
</tt> headers to
1223 make the second and subsequent mails appear as replies to the
1224 first. Also controls generation of the
<tt>Message-Id
</tt> header to
1227 <div class=
"paragraph"><p>The optional
<style
> argument can be either
<tt>shallow
</tt> or
<tt>deep
</tt>.
1228 <em>shallow
</em> threading makes every mail a reply to the head of the
1229 series, where the head is chosen from the cover letter, the
1230 <tt>--in-reply-to
</tt>, and the first patch mail, in this order.
<em>deep
</em>
1231 threading makes every mail a reply to the previous one.
</p></div>
1232 <div class=
"paragraph"><p>The default is
<tt>--no-thread
</tt>, unless the
<em>format.thread
</em> configuration
1233 is set. If
<tt>--thread
</tt> is specified without a style, it defaults to the
1234 style specified by
<em>format.thread
</em> if any, or else
<tt>shallow
</tt>.
</p></div>
1235 <div class=
"paragraph"><p>Beware that the default for
<em>git send-email
</em> is to thread emails
1236 itself. If you want
<tt>git format-patch
</tt> to take care of threading, you
1237 will want to ensure that threading is disabled for
<tt>git send-email
</tt>.
</p></div>
1239 <dt class=
"hdlist1">
1240 --in-reply-to=Message-Id
1244 Make the first mail (or all the mails with
<tt>--no-thread
</tt>) appear as a
1245 reply to the given Message-Id, which avoids breaking threads to
1246 provide a new patch series.
1249 <dt class=
"hdlist1">
1250 --ignore-if-in-upstream
1254 Do not include a patch that matches a commit in
1255 <until
>..
<since
>. This will examine all patches reachable
1256 from
<since
> but not from
<until
> and compare them with the
1257 patches being generated, and any patch that matches is
1261 <dt class=
"hdlist1">
1262 --subject-prefix=
<Subject-Prefix
>
1266 Instead of the standard
<em>[PATCH]
</em> prefix in the subject
1267 line, instead use
<em>[
<Subject-Prefix
>]
</em>. This
1268 allows for useful naming of a patch series, and can be
1269 combined with the
<tt>--numbered
</tt> option.
1272 <dt class=
"hdlist1">
1277 Add a
<tt>To:
</tt> header to the email headers. This is in addition
1278 to any configured headers, and may be used multiple times.
1279 The negated form
<tt>--no-to
</tt> discards all
<tt>To:
</tt> headers added so
1280 far (from config or command line).
1283 <dt class=
"hdlist1">
1288 Add a
<tt>Cc:
</tt> header to the email headers. This is in addition
1289 to any configured headers, and may be used multiple times.
1290 The negated form
<tt>--no-cc
</tt> discards all
<tt>Cc:
</tt> headers added so
1291 far (from config or command line).
1294 <dt class=
"hdlist1">
1295 --add-header=
<header
>
1299 Add an arbitrary header to the email headers. This is in addition
1300 to any configured headers, and may be used multiple times.
1301 For example,
<tt>--add-header=
"Organization: git-foo"</tt>.
1302 The negated form
<tt>--no-add-header
</tt> discards
<strong>all
</strong> (
<tt>To:
</tt>,
1303 <tt>Cc:
</tt>, and custom) headers added so far from config or command
1307 <dt class=
"hdlist1">
1312 In addition to the patches, generate a cover letter file
1313 containing the shortlog and the overall diffstat. You can
1314 fill in a description in the file before sending it out.
1317 <dt class=
"hdlist1">
1318 --[no]-signature=
<signature
>
1322 Add a signature to each message produced. Per RFC
3676 the signature
1323 is separated from the body by a line with '-- ' on it. If the
1324 signature option is omitted the signature defaults to the git version
1328 <dt class=
"hdlist1">
1329 --suffix=.
<sfx
>
1333 Instead of using
<tt>.patch
</tt> as the suffix for generated
1334 filenames, use specified suffix. A common alternative is
1335 <tt>--suffix=.txt
</tt>. Leaving this empty will remove the
<tt>.patch
</tt>
1338 <div class=
"paragraph"><p>Note that the leading character does not have to be a dot; for example,
1339 you can use
<tt>--suffix=-patch
</tt> to get
<tt>0001-description-of-my-change-patch
</tt>.
</p></div>
1341 <dt class=
"hdlist1">
1346 Do not print the names of the generated files to standard output.
1349 <dt class=
"hdlist1">
1354 Do not output contents of changes in binary files, instead
1355 display a notice that those files changed. Patches generated
1356 using this option cannot be applied properly, but they are
1357 still useful for code review.
1360 <dt class=
"hdlist1">
1365 Treat the revision argument as a
<revision range
>, even if it
1366 is just a single commit (that would normally be treated as a
1367 <since
>). Note that root commits included in the specified
1368 range are always formatted as creation patches, independently
1374 <h2 id=
"_configuration">CONFIGURATION
</h2>
1375 <div class=
"sectionbody">
1376 <div class=
"paragraph"><p>You can specify extra mail header lines to be added to each message,
1377 defaults for the subject prefix and file suffix, number patches when
1378 outputting more than one patch, add
"To" or
"Cc:" headers, configure
1379 attachments, and sign off patches with configuration variables.
</p></div>
1380 <div class=
"listingblock">
1381 <div class=
"content">
1383 headers =
"Organization: git-foo\n"
1384 subjectprefix = CHANGE
1389 attach [ = mime-boundary-string ]
1390 signoff = true
</tt></pre>
1393 <h2 id=
"_discussion">DISCUSSION
</h2>
1394 <div class=
"sectionbody">
1395 <div class=
"paragraph"><p>The patch produced by
<em>git format-patch
</em> is in UNIX mailbox format,
1396 with a fixed
"magic" time stamp to indicate that the file is output
1397 from format-patch rather than a real mailbox, like so:
</p></div>
1398 <div class=
"listingblock">
1399 <div class=
"content">
1400 <pre><tt>From
8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep
17 00:
00:
00 2001
1401 From: Tony Luck
<tony.luck@intel.com
>
1402 Date: Tue,
13 Jul
2010 11:
42:
54 -
0700
1403 Subject: [PATCH] =?UTF-
8?q?[IA64]=
20Put=
20ia64=
20config=
20files=
20on=
20the=
20?=
1404 =?UTF-
8?q?Uwe=
20Kleine-K=C3=B6nig=
20diet?=
1406 Content-Type: text/plain; charset=UTF-
8
1407 Content-Transfer-Encoding:
8bit
1409 arch/arm config files were slimmed down using a python script
1410 (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
1412 Do the same for ia64 so we can have sleek
& trim looking
1415 <div class=
"paragraph"><p>Typically it will be placed in a MUA
’s drafts folder, edited to add
1416 timely commentary that should not go in the changelog after the three
1417 dashes, and then sent as a message whose body, in our example, starts
1418 with
"arch/arm config files were…". On the receiving end, readers
1419 can save interesting patches in a UNIX mailbox and apply them with
1420 <a href=
"git-am.html">git-am(
1)
</a>.
</p></div>
1421 <div class=
"paragraph"><p>When a patch is part of an ongoing discussion, the patch generated by
1422 <em>git format-patch
</em> can be tweaked to take advantage of the
<em>git am
1423 --scissors
</em> feature. After your response to the discussion comes a
1424 line that consists solely of
"<tt>-- >8 --</tt>" (scissors and perforation),
1425 followed by the patch with unnecessary header fields removed:
</p></div>
1426 <div class=
"listingblock">
1427 <div class=
"content">
1429 > So we should do such-and-such.
1431 Makes sense to me. How about this patch?
1434 Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
1436 arch/arm config files were slimmed down using a python script
1439 <div class=
"paragraph"><p>When sending a patch this way, most often you are sending your own
1440 patch, so in addition to the
"<tt>From $SHA1 $magic_timestamp</tt>" marker you
1441 should omit
<tt>From:
</tt> and
<tt>Date:
</tt> lines from the patch file. The patch
1442 title is likely to be different from the subject of the discussion the
1443 patch is in response to, so it is likely that you would want to keep
1444 the Subject: line, like the example above.
</p></div>
1445 <h3 id=
"_checking_for_patch_corruption">Checking for patch corruption
</h3><div style=
"clear:left"></div>
1446 <div class=
"paragraph"><p>Many mailers if not set up properly will corrupt whitespace. Here are
1447 two common types of corruption:
</p></div>
1448 <div class=
"ulist"><ul>
1451 Empty context lines that do not have
<em>any
</em> whitespace.
1456 Non-empty context lines that have one extra whitespace at the
1461 <div class=
"paragraph"><p>One way to test if your MUA is set up correctly is:
</p></div>
1462 <div class=
"ulist"><ul>
1465 Send the patch to yourself, exactly the way you would, except
1466 with To: and Cc: lines that do not contain the list and
1472 Save that patch to a file in UNIX mailbox format. Call it a.patch,
1480 <div class=
"literalblock">
1481 <div class=
"content">
1482 <pre><tt>$ git fetch
<project
> master:test-apply
1483 $ git checkout test-apply
1485 $ git am a.patch
</tt></pre>
1489 <div class=
"paragraph"><p>If it does not apply correctly, there can be various reasons.
</p></div>
1490 <div class=
"ulist"><ul>
1493 The patch itself does not apply cleanly. That is
<em>bad
</em> but
1494 does not have much to do with your MUA. You might want to rebase
1495 the patch with
<a href=
"git-rebase.html">git-rebase(
1)
</a> before regenerating it in
1501 The MUA corrupted your patch;
"am" would complain that
1502 the patch does not apply. Look in the .git/rebase-apply/ subdirectory and
1503 see what
<em>patch
</em> file contains and check for the common
1504 corruption patterns mentioned above.
1509 While at it, check the
<em>info
</em> and
<em>final-commit
</em> files as well.
1510 If what is in
<em>final-commit
</em> is not exactly what you would want to
1511 see in the commit log message, it is very likely that the
1512 receiver would end up hand editing the log message when applying
1513 your patch. Things like
"Hi, this is my first patch.\n" in the
1514 patch e-mail should come after the three-dash line that signals
1515 the end of the commit message.
1520 <h2 id=
"_mua_specific_hints">MUA-SPECIFIC HINTS
</h2>
1521 <div class=
"sectionbody">
1522 <div class=
"paragraph"><p>Here are some hints on how to successfully submit patches inline using
1523 various mailers.
</p></div>
1524 <h3 id=
"_gmail">GMail
</h3><div style=
"clear:left"></div>
1525 <div class=
"paragraph"><p>GMail does not have any way to turn off line wrapping in the web
1526 interface, so it will mangle any emails that you send. You can however
1527 use
"git send-email" and send your patches through the GMail SMTP server, or
1528 use any IMAP email client to connect to the google IMAP server and forward
1529 the emails through that.
</p></div>
1530 <div class=
"paragraph"><p>For hints on using
<em>git send-email
</em> to send your patches through the
1531 GMail SMTP server, see the EXAMPLE section of
<a href=
"git-send-email.html">git-send-email(
1)
</a>.
</p></div>
1532 <div class=
"paragraph"><p>For hints on submission using the IMAP interface, see the EXAMPLE
1533 section of
<a href=
"git-imap-send.html">git-imap-send(
1)
</a>.
</p></div>
1534 <h3 id=
"_thunderbird">Thunderbird
</h3><div style=
"clear:left"></div>
1535 <div class=
"paragraph"><p>By default, Thunderbird will both wrap emails as well as flag
1536 them as being
<em>format=flowed
</em>, both of which will make the
1537 resulting email unusable by git.
</p></div>
1538 <div class=
"paragraph"><p>There are three different approaches: use an add-on to turn off line wraps,
1539 configure Thunderbird to not mangle patches, or use
1540 an external editor to keep Thunderbird from mangling the patches.
</p></div>
1541 <h4 id=
"_approach_1_add_on">Approach #
1 (add-on)
</h4>
1542 <div class=
"paragraph"><p>Install the Toggle Word Wrap add-on that is available from
1543 <a href=
"https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/">https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/
</a>
1544 It adds a menu entry
"Enable Word Wrap" in the composer
’s
"Options" menu
1545 that you can tick off. Now you can compose the message as you otherwise do
1546 (cut + paste,
<em>git format-patch
</em> |
<em>git imap-send
</em>, etc), but you have to
1547 insert line breaks manually in any text that you type.
</p></div>
1548 <h4 id=
"_approach_2_configuration">Approach #
2 (configuration)
</h4>
1549 <div class=
"paragraph"><p>Three steps:
</p></div>
1550 <div class=
"olist arabic"><ol class=
"arabic">
1553 Configure your mail server composition as plain text:
1554 Edit
…Account Settings
…Composition
& Addressing,
1555 uncheck
"Compose Messages in HTML".
1560 Configure your general composition window to not wrap.
1562 <div class=
"paragraph"><p>In Thunderbird
2:
1563 Edit..Preferences..Composition, wrap plain text messages at
0</p></div>
1564 <div class=
"paragraph"><p>In Thunderbird
3:
1565 Edit..Preferences..Advanced..Config Editor. Search for
1566 "mail.wrap_long_lines".
1567 Toggle it to make sure it is set to
<tt>false
</tt>.
</p></div>
1571 Disable the use of format=flowed:
1572 Edit..Preferences..Advanced..Config Editor. Search for
1573 "mailnews.send_plaintext_flowed".
1574 Toggle it to make sure it is set to
<tt>false
</tt>.
1578 <div class=
"paragraph"><p>After that is done, you should be able to compose email as you
1579 otherwise would (cut + paste,
<em>git format-patch
</em> |
<em>git imap-send
</em>, etc),
1580 and the patches will not be mangled.
</p></div>
1581 <h4 id=
"_approach_3_external_editor">Approach #
3 (external editor)
</h4>
1582 <div class=
"paragraph"><p>The following Thunderbird extensions are needed:
1583 AboutConfig from
<a href=
"http://aboutconfig.mozdev.org/">http://aboutconfig.mozdev.org/
</a> and
1584 External Editor from
<a href=
"http://globs.org/articles.php?lng=en&pg=8">http://globs.org/articles.php?lng=en
&pg=
8</a></p></div>
1585 <div class=
"olist arabic"><ol class=
"arabic">
1588 Prepare the patch as a text file using your method of choice.
1593 Before opening a compose window, use Edit
→Account Settings to
1594 uncheck the
"Compose messages in HTML format" setting in the
1595 "Composition & Addressing" panel of the account to be used to
1601 In the main Thunderbird window,
<em>before
</em> you open the compose
1602 window for the patch, use Tools
→about:config to set the
1603 following to the indicated values:
1605 <div class=
"listingblock">
1606 <div class=
"content">
1607 <pre><tt> mailnews.send_plaintext_flowed =
> false
1608 mailnews.wraplength =
> 0</tt></pre>
1613 Open a compose window and click the external editor icon.
1618 In the external editor window, read in the patch file and exit
1619 the editor normally.
1623 <div class=
"paragraph"><p>Side note: it may be possible to do step
2 with
1624 about:config and the following settings but no one
’s tried yet.
</p></div>
1625 <div class=
"listingblock">
1626 <div class=
"content">
1627 <pre><tt> mail.html_compose =
> false
1628 mail.identity.default.compose_html =
> false
1629 mail.identity.id?.compose_html =
> false
</tt></pre>
1631 <div class=
"paragraph"><p>There is a script in contrib/thunderbird-patch-inline which can help
1632 you include patches with Thunderbird in an easy way. To use it, do the
1633 steps above and then use the script as the external editor.
</p></div>
1634 <h3 id=
"_kmail">KMail
</h3><div style=
"clear:left"></div>
1635 <div class=
"paragraph"><p>This should help you to submit patches inline using KMail.
</p></div>
1636 <div class=
"olist arabic"><ol class=
"arabic">
1639 Prepare the patch as a text file.
1649 Go under
"Options" in the Composer window and be sure that
1650 "Word wrap" is not set.
1655 Use Message
→ Insert file
… and insert the patch.
1660 Back in the compose window: add whatever other text you wish to the
1661 message, complete the addressing and subject fields, and press send.
1666 <h2 id=
"_examples">EXAMPLES
</h2>
1667 <div class=
"sectionbody">
1668 <div class=
"ulist"><ul>
1671 Extract commits between revisions R1 and R2, and apply them on top of
1672 the current branch using
<em>git am
</em> to cherry-pick them:
1674 <div class=
"listingblock">
1675 <div class=
"content">
1676 <pre><tt>$ git format-patch -k --stdout R1..R2 | git am -
3 -k
</tt></pre>
1681 Extract all commits which are in the current branch but not in the
1684 <div class=
"listingblock">
1685 <div class=
"content">
1686 <pre><tt>$ git format-patch origin
</tt></pre>
1688 <div class=
"paragraph"><p>For each commit a separate file is created in the current directory.
</p></div>
1692 Extract all commits that lead to
<em>origin
</em> since the inception of the
1695 <div class=
"listingblock">
1696 <div class=
"content">
1697 <pre><tt>$ git format-patch --root origin
</tt></pre>
1702 The same as the previous one:
1704 <div class=
"listingblock">
1705 <div class=
"content">
1706 <pre><tt>$ git format-patch -M -B origin
</tt></pre>
1708 <div class=
"paragraph"><p>Additionally, it detects and handles renames and complete rewrites
1709 intelligently to produce a renaming patch. A renaming patch reduces
1710 the amount of text output, and generally makes it easier to review.
1711 Note that non-git
"patch" programs won
’t understand renaming patches, so
1712 use it only when you know the recipient uses git to apply your patch.
</p></div>
1716 Extract three topmost commits from the current branch and format them
1717 as e-mailable patches:
1719 <div class=
"listingblock">
1720 <div class=
"content">
1721 <pre><tt>$ git format-patch -
3</tt></pre>
1726 <h2 id=
"_see_also">SEE ALSO
</h2>
1727 <div class=
"sectionbody">
1728 <div class=
"paragraph"><p><a href=
"git-am.html">git-am(
1)
</a>,
<a href=
"git-send-email.html">git-send-email(
1)
</a></p></div>
1730 <h2 id=
"_git">GIT
</h2>
1731 <div class=
"sectionbody">
1732 <div class=
"paragraph"><p>Part of the
<a href=
"git.html">git(
1)
</a> suite
</p></div>
1735 <div id=
"footnotes"><hr /></div>
1737 <div id=
"footer-text">
1738 Last updated
2011-
09-
21 23:
01:
14 PDT