Update draft release notes to 1.7.2
[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 12'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
f693b7e9 13 [--no-thread | --thread[=<style>]]
50710ce4
SB
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]
ae6c098f 21 [--to=<email>] [--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
0b444cdb 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
dce5ef14
BG
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
dce5ef14 52the filename. With the `--numbered-files` option, the output file names
e6ff0f42
JL
53will only be numbers, without the first line of the commit appended.
54The names of the output files are printed to standard
dce5ef14 55output, unless the `--stdout` option is specified.
66f04f38 56
dce5ef14 57If `-o` is specified, output files are created in <dir>. Otherwise
2052d146 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
dce5ef14
BG
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
dce5ef14
BG
65If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
66`References` headers to make the second and subsequent patch mails appear
67as replies to the first mail; this also generates a `Message-Id` header to
cc35de84 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
dce5ef14 115 second part, with `Content-Disposition: attachment`.
c112f689 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
dce5ef14 124 second part, with `Content-Disposition: inline`.
a15a44ef 125
30984ed2 126--thread[=<style>]::
f693b7e9 127--no-thread::
dce5ef14 128 Controls addition of `In-Reply-To` and `References` headers to
f693b7e9 129 make the second and subsequent mails appear as replies to the
dce5ef14 130 first. Also controls generation of the `Message-Id` header to
f693b7e9 131 reference.
30984ed2
TR
132+
133The optional <style> argument can be either `shallow` or `deep`.
fd1ff306 134'shallow' threading makes every mail a reply to the head of the
30984ed2 135series, where the head is chosen from the cover letter, the
fd1ff306 136`\--in-reply-to`, and the first patch mail, in this order. 'deep'
f693b7e9
YD
137threading makes every mail a reply to the previous one.
138+
dce5ef14
BG
139The default is `--no-thread`, unless the 'format.thread' configuration
140is set. If `--thread` is specified without a style, it defaults to the
f693b7e9
YD
141style specified by 'format.thread' if any, or else `shallow`.
142+
143Beware that the default for 'git send-email' is to thread emails
dce5ef14
BG
144itself. If you want `git format-patch` to take care of threading, you
145will want to ensure that threading is disabled for `git send-email`.
28ffb898 146
da56645d 147--in-reply-to=Message-Id::
dce5ef14 148 Make the first mail (or all the mails with `--no-thread`) appear as a
da56645d
JT
149 reply to the given Message-Id, which avoids breaking threads to
150 provide a new patch series.
151
cc75ad67
DK
152--ignore-if-in-upstream::
153 Do not include a patch that matches a commit in
154 <until>..<since>. This will examine all patches reachable
155 from <since> but not from <until> and compare them with the
156 patches being generated, and any patch that matches is
157 ignored.
158
2d9e4a47
RJ
159--subject-prefix=<Subject-Prefix>::
160 Instead of the standard '[PATCH]' prefix in the subject
161 line, instead use '[<Subject-Prefix>]'. This
162 allows for useful naming of a patch series, and can be
dce5ef14 163 combined with the `--numbered` option.
2d9e4a47 164
ae6c098f
SD
165--to=<email>::
166 Add a `To:` header to the email headers. This is in addition
167 to any configured headers, and may be used multiple times.
168
736cc67d 169--cc=<email>::
dce5ef14 170 Add a `Cc:` header to the email headers. This is in addition
736cc67d
DB
171 to any configured headers, and may be used multiple times.
172
d7d9c2d0
MH
173--add-header=<header>::
174 Add an arbitrary header to the email headers. This is in addition
175 to any configured headers, and may be used multiple times.
dce5ef14 176 For example, `--add-header="Organization: git-foo"`
d7d9c2d0 177
a5a27c79 178--cover-letter::
f4912391
MM
179 In addition to the patches, generate a cover letter file
180 containing the shortlog and the overall diffstat. You can
181 fill in a description in the file before sending it out.
a5a27c79 182
03eeaeae 183--suffix=.<sfx>::
917a8f89 184 Instead of using `.patch` as the suffix for generated
02783075 185 filenames, use specified suffix. A common alternative is
50710ce4
SB
186 `--suffix=.txt`. Leaving this empty will remove the `.patch`
187 suffix.
03eeaeae 188+
50710ce4
SB
189Note that the leading character does not have to be a dot; for example,
190you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
03eeaeae 191
37c22a4b 192--no-binary::
50710ce4
SB
193 Do not output contents of changes in binary files, instead
194 display a notice that those files changed. Patches generated
195 using this option cannot be applied properly, but they are
196 still useful for code review.
37c22a4b 197
2d266f9d
TR
198--root::
199 Treat the revision argument as a <revision range>, even if it
200 is just a single commit (that would normally be treated as a
201 <since>). Note that root commits included in the specified
202 range are always formatted as creation patches, independently
203 of this flag.
204
96ce6d26
MM
205CONFIGURATION
206-------------
50710ce4
SB
207You can specify extra mail header lines to be added to each message,
208defaults for the subject prefix and file suffix, number patches when
ae6c098f
SD
209outputting more than one patch, add "To" or "Cc:" headers, configure
210attachments, and sign off patches with configuration variables.
96ce6d26 211
917a8f89 212------------
96ce6d26 213[format]
7f9d77f2
JN
214 headers = "Organization: git-foo\n"
215 subjectprefix = CHANGE
216 suffix = .txt
217 numbered = auto
ae6c098f 218 to = <email>
fe8928e6 219 cc = <email>
0db5260b 220 attach [ = mime-boundary-string ]
1d1876e9 221 signoff = true
917a8f89 222------------
03eeaeae 223
96ce6d26 224
28ffb898
JH
225EXAMPLES
226--------
227
921177f5 228* Extract commits between revisions R1 and R2, and apply them on top of
0b444cdb 229the current branch using 'git am' to cherry-pick them:
921177f5
CC
230+
231------------
467c0197 232$ git format-patch -k --stdout R1..R2 | git am -3 -k
921177f5
CC
233------------
234
235* Extract all commits which are in the current branch but not in the
236origin branch:
237+
238------------
239$ git format-patch origin
240------------
241+
242For each commit a separate file is created in the current directory.
243
244* Extract all commits that lead to 'origin' since the inception of the
245project:
246+
247------------
9c67c757 248$ git format-patch --root origin
921177f5
CC
249------------
250
251* The same as the previous one:
252+
253------------
254$ git format-patch -M -B origin
255------------
256+
257Additionally, it detects and handles renames and complete rewrites
258intelligently to produce a renaming patch. A renaming patch reduces
50710ce4
SB
259the amount of text output, and generally makes it easier to review.
260Note that non-git "patch" programs won't understand renaming patches, so
921177f5
CC
261use it only when you know the recipient uses git to apply your patch.
262
263* Extract three topmost commits from the current branch and format them
264as e-mailable patches:
265+
266------------
267$ git format-patch -3
268------------
28ffb898 269
56ae8df5 270SEE ALSO
28ffb898 271--------
5162e697 272linkgit:git-am[1], linkgit:git-send-email[1]
28ffb898
JH
273
274
7fc9d69f
JH
275Author
276------
59eb68aa 277Written by Junio C Hamano <gitster@pobox.com>
7fc9d69f
JH
278
279Documentation
280--------------
281Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
282
283GIT
284---
9e1f0a85 285Part of the linkgit:git[1] suite