Git 1.7.0
[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]
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
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
736cc67d 165--cc=<email>::
dce5ef14 166 Add a `Cc:` header to the email headers. This is in addition
736cc67d
DB
167 to any configured headers, and may be used multiple times.
168
d7d9c2d0
MH
169--add-header=<header>::
170 Add an arbitrary header to the email headers. This is in addition
171 to any configured headers, and may be used multiple times.
dce5ef14 172 For example, `--add-header="Organization: git-foo"`
d7d9c2d0 173
a5a27c79 174--cover-letter::
f4912391
MM
175 In addition to the patches, generate a cover letter file
176 containing the shortlog and the overall diffstat. You can
177 fill in a description in the file before sending it out.
a5a27c79 178
03eeaeae 179--suffix=.<sfx>::
917a8f89 180 Instead of using `.patch` as the suffix for generated
02783075 181 filenames, use specified suffix. A common alternative is
50710ce4
SB
182 `--suffix=.txt`. Leaving this empty will remove the `.patch`
183 suffix.
03eeaeae 184+
50710ce4
SB
185Note that the leading character does not have to be a dot; for example,
186you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
03eeaeae 187
37c22a4b 188--no-binary::
50710ce4
SB
189 Do not output contents of changes in binary files, instead
190 display a notice that those files changed. Patches generated
191 using this option cannot be applied properly, but they are
192 still useful for code review.
37c22a4b 193
2d266f9d
TR
194--root::
195 Treat the revision argument as a <revision range>, even if it
196 is just a single commit (that would normally be treated as a
197 <since>). Note that root commits included in the specified
198 range are always formatted as creation patches, independently
199 of this flag.
200
96ce6d26
MM
201CONFIGURATION
202-------------
50710ce4
SB
203You can specify extra mail header lines to be added to each message,
204defaults for the subject prefix and file suffix, number patches when
205outputting more than one patch, add "Cc:" headers, configure attachments,
206and sign off patches with configuration variables.
96ce6d26 207
917a8f89 208------------
96ce6d26 209[format]
7f9d77f2
JN
210 headers = "Organization: git-foo\n"
211 subjectprefix = CHANGE
212 suffix = .txt
213 numbered = auto
fe8928e6 214 cc = <email>
0db5260b 215 attach [ = mime-boundary-string ]
1d1876e9 216 signoff = true
917a8f89 217------------
03eeaeae 218
96ce6d26 219
28ffb898
JH
220EXAMPLES
221--------
222
921177f5 223* Extract commits between revisions R1 and R2, and apply them on top of
0b444cdb 224the current branch using 'git am' to cherry-pick them:
921177f5
CC
225+
226------------
467c0197 227$ git format-patch -k --stdout R1..R2 | git am -3 -k
921177f5
CC
228------------
229
230* Extract all commits which are in the current branch but not in the
231origin branch:
232+
233------------
234$ git format-patch origin
235------------
236+
237For each commit a separate file is created in the current directory.
238
239* Extract all commits that lead to 'origin' since the inception of the
240project:
241+
242------------
9c67c757 243$ git format-patch --root origin
921177f5
CC
244------------
245
246* The same as the previous one:
247+
248------------
249$ git format-patch -M -B origin
250------------
251+
252Additionally, it detects and handles renames and complete rewrites
253intelligently to produce a renaming patch. A renaming patch reduces
50710ce4
SB
254the amount of text output, and generally makes it easier to review.
255Note that non-git "patch" programs won't understand renaming patches, so
921177f5
CC
256use it only when you know the recipient uses git to apply your patch.
257
258* Extract three topmost commits from the current branch and format them
259as e-mailable patches:
260+
261------------
262$ git format-patch -3
263------------
28ffb898 264
56ae8df5 265SEE ALSO
28ffb898 266--------
5162e697 267linkgit:git-am[1], linkgit:git-send-email[1]
28ffb898
JH
268
269
7fc9d69f
JH
270Author
271------
59eb68aa 272Written by Junio C Hamano <gitster@pobox.com>
7fc9d69f
JH
273
274Documentation
275--------------
276Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
277
278GIT
279---
9e1f0a85 280Part of the linkgit:git[1] suite