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