List send-email config options in config.txt.
[git/git.git] / Documentation / git-format-patch.txt
CommitLineData
215a7ad1
JH
1git-format-patch(1)
2===================
7fc9d69f
JH
3
4NAME
5----
7bd7f280 6git-format-patch - Prepare patches for e-mail submission
7fc9d69f
JH
7
8
9SYNOPSIS
10--------
353ce815 11[verse]
50710ce4
SB
12'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
13 [--thread[=<style>]]
14 [(--attach|--inline)[=<boundary>] | --no-attach]
15 [-s | --signoff]
a5a27c79
DB
16 [-n | --numbered | -N | --no-numbered]
17 [--start-number <n>] [--numbered-files]
18 [--in-reply-to=Message-Id] [--suffix=.<sfx>]
19 [--ignore-if-in-upstream]
20 [--subject-prefix=Subject-Prefix]
736cc67d 21 [--cc=<email>]
a5a27c79 22 [--cover-letter]
50710ce4 23 [<common diff options>]
8a1d076e 24 [ <since> | <revision range> ]
7fc9d69f
JH
25
26DESCRIPTION
27-----------
2052d146 28
8a1d076e 29Prepare each commit with its patch in
2052d146 30one file per commit, formatted to resemble UNIX mailbox format.
2052d146 31The output of this command is convenient for e-mail submission or
ba020ef5 32for use with 'git-am'.
35ef3a4c 33
8a1d076e
JH
34There are two ways to specify which commits to operate on.
35
361. A single commit, <since>, specifies that the commits leading
37 to the tip of the current branch that are not in the history
38 that leads to the <since> to be output.
39
402. Generic <revision range> expression (see "SPECIFYING
5162e697 41 REVISIONS" section in linkgit:git-rev-parse[1]) means the
2f6a3823
JH
42 commits in the specified range.
43
2d266f9d
TR
44The first rule takes precedence in the case of a single <commit>. To
45apply the second rule, i.e., format everything since the beginning of
46history up until <commit>, use the '\--root' option: "git format-patch
47\--root <commit>". If you want to format only <commit> itself, you
48can do this with "git format-patch -1 <commit>".
8a1d076e 49
e6ff0f42 50By default, each output file is numbered sequentially from 1, and uses the
2052d146 51first line of the commit message (massaged for pathname safety) as
e6ff0f42
JL
52the filename. With the --numbered-files option, the output file names
53will only be numbers, without the first line of the commit appended.
54The names of the output files are printed to standard
2052d146 55output, unless the --stdout option is specified.
66f04f38 56
2052d146
DS
57If -o is specified, output files are created in <dir>. Otherwise
58they are created in the current working directory.
35ef3a4c 59
a567fdcb
BG
60By default, the subject of a single patch is "[PATCH] First Line" and
61the subject when multiple patches are output is "[PATCH n/m] First
62Line". To force 1/1 to be added for a single patch, use -n. To omit
63patch numbers from the subject, use -N
35ef3a4c 64
ba020ef5 65If given --thread, 'git-format-patch' will generate In-Reply-To and
cc35de84
JT
66References headers to make the second and subsequent patch mails appear
67as replies to the first mail; this also generates a Message-Id header to
68reference.
7fc9d69f
JH
69
70OPTIONS
71-------
c1a95fa6 72:git-format-patch: 1
b8105375
BG
73include::diff-options.txt[]
74
ed5f07a6
MV
75-<n>::
76 Limits the number of patches to prepare.
77
3240240f
SB
78-o <dir>::
79--output-directory <dir>::
35ef3a4c 80 Use <dir> to store the resulting files, instead of the
efd02016 81 current working directory.
35ef3a4c 82
3240240f
SB
83-n::
84--numbered::
a567fdcb 85 Name output in '[PATCH n/m]' format, even with a single patch.
35ef3a4c 86
3240240f
SB
87-N::
88--no-numbered::
49604a4d
BG
89 Name output in '[PATCH]' format.
90
2052d146
DS
91--start-number <n>::
92 Start numbering the patches at <n> instead of 1.
93
e6ff0f42
JL
94--numbered-files::
95 Output file names will be a simple number sequence
96 without the default first line of the commit appended.
e6ff0f42 97
3240240f
SB
98-k::
99--keep-subject::
35ef3a4c
JH
100 Do not strip/add '[PATCH]' from the first line of the
101 commit log message.
102
3240240f
SB
103-s::
104--signoff::
6f855371
NW
105 Add `Signed-off-by:` line to the commit message, using
106 the committer identity of yourself.
107
54ba6013 108--stdout::
2052d146
DS
109 Print all commits to the standard output in mbox format,
110 instead of creating a file for each one.
7fc9d69f 111
c112f689
JS
112--attach[=<boundary>]::
113 Create multipart/mixed attachment, the first part of
114 which is the commit message and the patch itself in the
115 second part, with "Content-Disposition: attachment".
116
0db5260b
JW
117--no-attach::
118 Disable the creation of an attachment, overriding the
119 configuration setting.
120
c112f689
JS
121--inline[=<boundary>]::
122 Create multipart/mixed attachment, the first part of
123 which is the commit message and the patch itself in the
124 second part, with "Content-Disposition: inline".
a15a44ef 125
30984ed2 126--thread[=<style>]::
cc35de84
JT
127 Add In-Reply-To and References headers to make the second and
128 subsequent mails appear as replies to the first. Also generates
129 the Message-Id header to reference.
30984ed2
TR
130+
131The optional <style> argument can be either `shallow` or `deep`.
fd1ff306 132'shallow' threading makes every mail a reply to the head of the
30984ed2 133series, where the head is chosen from the cover letter, the
fd1ff306 134`\--in-reply-to`, and the first patch mail, in this order. 'deep'
30984ed2
TR
135threading makes every mail a reply to the previous one. If not
136specified, defaults to the 'format.thread' configuration, or `shallow`
137if that is not set.
28ffb898 138
da56645d
JT
139--in-reply-to=Message-Id::
140 Make the first mail (or all the mails with --no-thread) appear as a
141 reply to the given Message-Id, which avoids breaking threads to
142 provide a new patch series.
143
cc75ad67
DK
144--ignore-if-in-upstream::
145 Do not include a patch that matches a commit in
146 <until>..<since>. This will examine all patches reachable
147 from <since> but not from <until> and compare them with the
148 patches being generated, and any patch that matches is
149 ignored.
150
2d9e4a47
RJ
151--subject-prefix=<Subject-Prefix>::
152 Instead of the standard '[PATCH]' prefix in the subject
153 line, instead use '[<Subject-Prefix>]'. This
154 allows for useful naming of a patch series, and can be
155 combined with the --numbered option.
156
736cc67d
DB
157--cc=<email>::
158 Add a "Cc:" header to the email headers. This is in addition
159 to any configured headers, and may be used multiple times.
160
d7d9c2d0
MH
161--add-header=<header>::
162 Add an arbitrary header to the email headers. This is in addition
163 to any configured headers, and may be used multiple times.
164 For example, --add-header="Organization: git-foo"
165
a5a27c79 166--cover-letter::
f4912391
MM
167 In addition to the patches, generate a cover letter file
168 containing the shortlog and the overall diffstat. You can
169 fill in a description in the file before sending it out.
a5a27c79 170
03eeaeae 171--suffix=.<sfx>::
917a8f89 172 Instead of using `.patch` as the suffix for generated
02783075 173 filenames, use specified suffix. A common alternative is
50710ce4
SB
174 `--suffix=.txt`. Leaving this empty will remove the `.patch`
175 suffix.
03eeaeae 176+
50710ce4
SB
177Note that the leading character does not have to be a dot; for example,
178you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
03eeaeae 179
37c22a4b 180--no-binary::
50710ce4
SB
181 Do not output contents of changes in binary files, instead
182 display a notice that those files changed. Patches generated
183 using this option cannot be applied properly, but they are
184 still useful for code review.
37c22a4b 185
2d266f9d
TR
186--root::
187 Treat the revision argument as a <revision range>, even if it
188 is just a single commit (that would normally be treated as a
189 <since>). Note that root commits included in the specified
190 range are always formatted as creation patches, independently
191 of this flag.
192
96ce6d26
MM
193CONFIGURATION
194-------------
50710ce4
SB
195You can specify extra mail header lines to be added to each message,
196defaults for the subject prefix and file suffix, number patches when
197outputting more than one patch, add "Cc:" headers, configure attachments,
198and sign off patches with configuration variables.
96ce6d26 199
917a8f89 200------------
96ce6d26 201[format]
7f9d77f2
JN
202 headers = "Organization: git-foo\n"
203 subjectprefix = CHANGE
204 suffix = .txt
205 numbered = auto
fe8928e6 206 cc = <email>
0db5260b 207 attach [ = mime-boundary-string ]
1d1876e9 208 signoff = true
917a8f89 209------------
03eeaeae 210
96ce6d26 211
28ffb898
JH
212EXAMPLES
213--------
214
921177f5 215* Extract commits between revisions R1 and R2, and apply them on top of
ba020ef5 216the current branch using 'git-am' to cherry-pick them:
921177f5
CC
217+
218------------
467c0197 219$ git format-patch -k --stdout R1..R2 | git am -3 -k
921177f5
CC
220------------
221
222* Extract all commits which are in the current branch but not in the
223origin branch:
224+
225------------
226$ git format-patch origin
227------------
228+
229For each commit a separate file is created in the current directory.
230
231* Extract all commits that lead to 'origin' since the inception of the
232project:
233+
234------------
9c67c757 235$ git format-patch --root origin
921177f5
CC
236------------
237
238* The same as the previous one:
239+
240------------
241$ git format-patch -M -B origin
242------------
243+
244Additionally, it detects and handles renames and complete rewrites
245intelligently to produce a renaming patch. A renaming patch reduces
50710ce4
SB
246the amount of text output, and generally makes it easier to review.
247Note that non-git "patch" programs won't understand renaming patches, so
921177f5
CC
248use it only when you know the recipient uses git to apply your patch.
249
250* Extract three topmost commits from the current branch and format them
251as e-mailable patches:
252+
253------------
254$ git format-patch -3
255------------
28ffb898 256
56ae8df5 257SEE ALSO
28ffb898 258--------
5162e697 259linkgit:git-am[1], linkgit:git-send-email[1]
28ffb898
JH
260
261
7fc9d69f
JH
262Author
263------
59eb68aa 264Written by Junio C Hamano <gitster@pobox.com>
7fc9d69f
JH
265
266Documentation
267--------------
268Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
269
270GIT
271---
9e1f0a85 272Part of the linkgit:git[1] suite