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