Combine To: and Cc: headers
[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]
6eea60f8 12'git-format-patch' [-k] [-o <dir> | --stdout] [--thread]
a5a27c79
DB
13 [--attach[=<boundary>] | --inline[=<boundary>]]
14 [-s | --signoff] [<common diff options>]
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 [--subject-prefix=Subject-Prefix]
20 [--cover-letter]
8a1d076e 21 [ <since> | <revision range> ]
7fc9d69f
JH
22
23DESCRIPTION
24-----------
2052d146 25
8a1d076e 26Prepare each commit with its patch in
2052d146 27one file per commit, formatted to resemble UNIX mailbox format.
2052d146 28The output of this command is convenient for e-mail submission or
5162e697 29for use with linkgit:git-am[1].
35ef3a4c 30
8a1d076e
JH
31There are two ways to specify which commits to operate on.
32
331. A single commit, <since>, specifies that the commits leading
34 to the tip of the current branch that are not in the history
35 that leads to the <since> to be output.
36
372. Generic <revision range> expression (see "SPECIFYING
5162e697 38 REVISIONS" section in linkgit:git-rev-parse[1]) means the
2f6a3823
JH
39 commits in the specified range.
40
41A single commit, when interpreted as a <revision range>
42expression, means "everything that leads to that commit", but
43if you write 'git format-patch <commit>', the previous rule
44applies to that command line and you do not get "everything
45since the beginning of the time". If you want to format
46everything since project inception to one commit, say "git
47format-patch \--root <commit>" to make it clear that it is the
48latter case.
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
2052d146
DS
60If -n is specified, instead of "[PATCH] Subject", the first line
61is formatted as "[PATCH n/m] Subject".
35ef3a4c 62
cc35de84
JT
63If given --thread, git-format-patch will generate In-Reply-To and
64References headers to make the second and subsequent patch mails appear
65as replies to the first mail; this also generates a Message-Id header to
66reference.
7fc9d69f
JH
67
68OPTIONS
69-------
c1a95fa6 70:git-format-patch: 1
b8105375
BG
71include::diff-options.txt[]
72
ed5f07a6
MV
73-<n>::
74 Limits the number of patches to prepare.
75
6f855371 76-o|--output-directory <dir>::
35ef3a4c 77 Use <dir> to store the resulting files, instead of the
efd02016 78 current working directory.
35ef3a4c 79
6f855371 80-n|--numbered::
35ef3a4c
JH
81 Name output in '[PATCH n/m]' format.
82
49604a4d
BG
83-N|--no-numbered::
84 Name output in '[PATCH]' format.
85
2052d146
DS
86--start-number <n>::
87 Start numbering the patches at <n> instead of 1.
88
e6ff0f42
JL
89--numbered-files::
90 Output file names will be a simple number sequence
91 without the default first line of the commit appended.
92 Mutually exclusive with the --stdout option.
93
6f855371 94-k|--keep-subject::
35ef3a4c
JH
95 Do not strip/add '[PATCH]' from the first line of the
96 commit log message.
97
6f855371
NW
98-s|--signoff::
99 Add `Signed-off-by:` line to the commit message, using
100 the committer identity of yourself.
101
54ba6013 102--stdout::
2052d146
DS
103 Print all commits to the standard output in mbox format,
104 instead of creating a file for each one.
7fc9d69f 105
c112f689
JS
106--attach[=<boundary>]::
107 Create multipart/mixed attachment, the first part of
108 which is the commit message and the patch itself in the
109 second part, with "Content-Disposition: attachment".
110
111--inline[=<boundary>]::
112 Create multipart/mixed attachment, the first part of
113 which is the commit message and the patch itself in the
114 second part, with "Content-Disposition: inline".
a15a44ef 115
cc35de84
JT
116--thread::
117 Add In-Reply-To and References headers to make the second and
118 subsequent mails appear as replies to the first. Also generates
119 the Message-Id header to reference.
28ffb898 120
da56645d
JT
121--in-reply-to=Message-Id::
122 Make the first mail (or all the mails with --no-thread) appear as a
123 reply to the given Message-Id, which avoids breaking threads to
124 provide a new patch series.
125
cc75ad67
DK
126--ignore-if-in-upstream::
127 Do not include a patch that matches a commit in
128 <until>..<since>. This will examine all patches reachable
129 from <since> but not from <until> and compare them with the
130 patches being generated, and any patch that matches is
131 ignored.
132
2d9e4a47
RJ
133--subject-prefix=<Subject-Prefix>::
134 Instead of the standard '[PATCH]' prefix in the subject
135 line, instead use '[<Subject-Prefix>]'. This
136 allows for useful naming of a patch series, and can be
137 combined with the --numbered option.
138
a5a27c79
DB
139--cover-letter::
140 Generate a cover letter template. You still have to fill in
141 a description, but the shortlog and the diffstat will be
142 generated for you.
143
03eeaeae 144--suffix=.<sfx>::
917a8f89 145 Instead of using `.patch` as the suffix for generated
02783075 146 filenames, use specified suffix. A common alternative is
917a8f89 147 `--suffix=.txt`.
03eeaeae
JH
148+
149Note that you would need to include the leading dot `.` if you
150want a filename like `0001-description-of-my-change.patch`, and
151the first letter does not have to be a dot. Leaving it empty would
152not add any suffix.
153
96ce6d26
MM
154CONFIGURATION
155-------------
49604a4d
BG
156You can specify extra mail header lines to be added to each message
157in the repository configuration, new defaults for the subject prefix
158and file suffix, and number patches when outputting more than one.
96ce6d26 159
917a8f89 160------------
96ce6d26
MM
161[format]
162 headers = "Organization: git-foo\n"
dbd21447 163 subjectprefix = CHANGE
917a8f89 164 suffix = .txt
49604a4d 165 numbered = auto
917a8f89 166------------
03eeaeae 167
96ce6d26 168
28ffb898
JH
169EXAMPLES
170--------
171
172git-format-patch -k --stdout R1..R2 | git-am -3 -k::
173 Extract commits between revisions R1 and R2, and apply
174 them on top of the current branch using `git-am` to
175 cherry-pick them.
176
177git-format-patch origin::
2052d146
DS
178 Extract all commits which are in the current branch but
179 not in the origin branch. For each commit a separate file
180 is created in the current directory.
28ffb898 181
8a1d076e 182git-format-patch \--root origin::
136e6316 183 Extract all commits that lead to 'origin' since the
8a1d076e
JH
184 inception of the project.
185
803f498c 186git-format-patch -M -B origin::
2052d146
DS
187 The same as the previous one. Additionally, it detects
188 and handles renames and complete rewrites intelligently to
189 produce a renaming patch. A renaming patch reduces the
190 amount of text output, and generally makes it easier to
191 review it. Note that the "patch" program does not
192 understand renaming patches, so use it only when you know
193 the recipient uses git to apply your patch.
803f498c 194
7c496280
JH
195git-format-patch -3::
196 Extract three topmost commits from the current branch
197 and format them as e-mailable patches.
28ffb898
JH
198
199See Also
200--------
5162e697 201linkgit:git-am[1], linkgit:git-send-email[1]
28ffb898
JH
202
203
7fc9d69f
JH
204Author
205------
206Written by Junio C Hamano <junkio@cox.net>
207
208Documentation
209--------------
210Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
211
212GIT
213---
5162e697 214Part of the linkgit:git[7] suite