Documentation: fix gitlinks
[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]
b1889c36 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
483bc4f0 30for use with `git-am`.
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
483bc4f0 64If given --thread, `git-format-patch` will generate In-Reply-To and
cc35de84
JT
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
3240240f
SB
77-o <dir>::
78--output-directory <dir>::
35ef3a4c 79 Use <dir> to store the resulting files, instead of the
efd02016 80 current working directory.
35ef3a4c 81
3240240f
SB
82-n::
83--numbered::
35ef3a4c
JH
84 Name output in '[PATCH n/m]' format.
85
3240240f
SB
86-N::
87--no-numbered::
49604a4d
BG
88 Name output in '[PATCH]' format.
89
2052d146
DS
90--start-number <n>::
91 Start numbering the patches at <n> instead of 1.
92
e6ff0f42
JL
93--numbered-files::
94 Output file names will be a simple number sequence
95 without the default first line of the commit appended.
96 Mutually exclusive with the --stdout option.
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
117--inline[=<boundary>]::
118 Create multipart/mixed attachment, the first part of
119 which is the commit message and the patch itself in the
120 second part, with "Content-Disposition: inline".
a15a44ef 121
cc35de84
JT
122--thread::
123 Add In-Reply-To and References headers to make the second and
124 subsequent mails appear as replies to the first. Also generates
125 the Message-Id header to reference.
28ffb898 126
da56645d
JT
127--in-reply-to=Message-Id::
128 Make the first mail (or all the mails with --no-thread) appear as a
129 reply to the given Message-Id, which avoids breaking threads to
130 provide a new patch series.
131
cc75ad67
DK
132--ignore-if-in-upstream::
133 Do not include a patch that matches a commit in
134 <until>..<since>. This will examine all patches reachable
135 from <since> but not from <until> and compare them with the
136 patches being generated, and any patch that matches is
137 ignored.
138
2d9e4a47
RJ
139--subject-prefix=<Subject-Prefix>::
140 Instead of the standard '[PATCH]' prefix in the subject
141 line, instead use '[<Subject-Prefix>]'. This
142 allows for useful naming of a patch series, and can be
143 combined with the --numbered option.
144
736cc67d
DB
145--cc=<email>::
146 Add a "Cc:" header to the email headers. This is in addition
147 to any configured headers, and may be used multiple times.
148
a5a27c79
DB
149--cover-letter::
150 Generate a cover letter template. You still have to fill in
151 a description, but the shortlog and the diffstat will be
152 generated for you.
153
03eeaeae 154--suffix=.<sfx>::
917a8f89 155 Instead of using `.patch` as the suffix for generated
02783075 156 filenames, use specified suffix. A common alternative is
917a8f89 157 `--suffix=.txt`.
03eeaeae
JH
158+
159Note that you would need to include the leading dot `.` if you
160want a filename like `0001-description-of-my-change.patch`, and
161the first letter does not have to be a dot. Leaving it empty would
162not add any suffix.
163
37c22a4b
CMOF
164--no-binary::
165 Don't output contents of changes in binary files, just take note
166 that they differ. Note that this disable the patch to be properly
167 applied. By default the contents of changes in those files are
168 encoded in the patch.
169
96ce6d26
MM
170CONFIGURATION
171-------------
49604a4d
BG
172You can specify extra mail header lines to be added to each message
173in the repository configuration, new defaults for the subject prefix
174and file suffix, and number patches when outputting more than one.
96ce6d26 175
917a8f89 176------------
96ce6d26
MM
177[format]
178 headers = "Organization: git-foo\n"
dbd21447 179 subjectprefix = CHANGE
917a8f89 180 suffix = .txt
49604a4d 181 numbered = auto
fe8928e6 182 cc = <email>
917a8f89 183------------
03eeaeae 184
96ce6d26 185
28ffb898
JH
186EXAMPLES
187--------
188
921177f5
CC
189* Extract commits between revisions R1 and R2, and apply them on top of
190the current branch using `git-am` to cherry-pick them:
191+
192------------
193$ git format-patch -k --stdout R1..R2 | git-am -3 -k
194------------
195
196* Extract all commits which are in the current branch but not in the
197origin branch:
198+
199------------
200$ git format-patch origin
201------------
202+
203For each commit a separate file is created in the current directory.
204
205* Extract all commits that lead to 'origin' since the inception of the
206project:
207+
208------------
9c67c757 209$ git format-patch --root origin
921177f5
CC
210------------
211
212* The same as the previous one:
213+
214------------
215$ git format-patch -M -B origin
216------------
217+
218Additionally, it detects and handles renames and complete rewrites
219intelligently to produce a renaming patch. A renaming patch reduces
220the amount of text output, and generally makes it easier to review it.
221Note that the "patch" program does not understand renaming patches, so
222use it only when you know the recipient uses git to apply your patch.
223
224* Extract three topmost commits from the current branch and format them
225as e-mailable patches:
226+
227------------
228$ git format-patch -3
229------------
28ffb898 230
56ae8df5 231SEE ALSO
28ffb898 232--------
5162e697 233linkgit:git-am[1], linkgit:git-send-email[1]
28ffb898
JH
234
235
7fc9d69f
JH
236Author
237------
238Written by Junio C Hamano <junkio@cox.net>
239
240Documentation
241--------------
242Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
243
244GIT
245---
9e1f0a85 246Part of the linkgit:git[1] suite