Merge branch 'maint'
[git/vmiklos.git] / Documentation / git-format-patch.txt
blob687e66759817bc2f349e8a5a89aa2c6731237b23
1 git-format-patch(1)
2 ===================
4 NAME
5 ----
6 git-format-patch - Prepare patches for e-mail submission
9 SYNOPSIS
10 --------
11 [verse]
12 'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
13                    [--no-thread | --thread[=<style>]]
14                    [(--attach|--inline)[=<boundary>] | --no-attach]
15                    [-s | --signoff]
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]
21                    [--cc=<email>]
22                    [--cover-letter]
23                    [<common diff options>]
24                    [ <since> | <revision range> ]
26 DESCRIPTION
27 -----------
29 Prepare each commit with its patch in
30 one file per commit, formatted to resemble UNIX mailbox format.
31 The output of this command is convenient for e-mail submission or
32 for use with 'git-am'.
34 There are two ways to specify which commits to operate on.
36 1. 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.
40 2. Generic <revision range> expression (see "SPECIFYING
41    REVISIONS" section in linkgit:git-rev-parse[1]) means the
42    commits in the specified range.
44 The first rule takes precedence in the case of a single <commit>.  To
45 apply the second rule, i.e., format everything since the beginning of
46 history up until <commit>, use the '\--root' option: "git format-patch
47 \--root <commit>".  If you want to format only <commit> itself, you
48 can do this with "git format-patch -1 <commit>".
50 By default, each output file is numbered sequentially from 1, and uses the
51 first line of the commit message (massaged for pathname safety) as
52 the filename. With the --numbered-files option, the output file names
53 will only be numbers, without the first line of the commit appended.
54 The names of the output files are printed to standard
55 output, unless the --stdout option is specified.
57 If -o is specified, output files are created in <dir>.  Otherwise
58 they are created in the current working directory.
60 By default, the subject of a single patch is "[PATCH] First Line" and
61 the subject when multiple patches are output is "[PATCH n/m] First
62 Line". To force 1/1 to be added for a single patch, use -n.  To omit
63 patch numbers from the subject, use -N
65 If given --thread, 'git-format-patch' will generate In-Reply-To and
66 References headers to make the second and subsequent patch mails appear
67 as replies to the first mail; this also generates a Message-Id header to
68 reference.
70 OPTIONS
71 -------
72 :git-format-patch: 1
73 include::diff-options.txt[]
75 -<n>::
76         Limits the number of patches to prepare.
78 -o <dir>::
79 --output-directory <dir>::
80         Use <dir> to store the resulting files, instead of the
81         current working directory.
83 -n::
84 --numbered::
85         Name output in '[PATCH n/m]' format, even with a single patch.
87 -N::
88 --no-numbered::
89         Name output in '[PATCH]' format.
91 --start-number <n>::
92         Start numbering the patches at <n> instead of 1.
94 --numbered-files::
95         Output file names will be a simple number sequence
96         without the default first line of the commit appended.
98 -k::
99 --keep-subject::
100         Do not strip/add '[PATCH]' from the first line of the
101         commit log message.
103 -s::
104 --signoff::
105         Add `Signed-off-by:` line to the commit message, using
106         the committer identity of yourself.
108 --stdout::
109         Print all commits to the standard output in mbox format,
110         instead of creating a file for each one.
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".
117 --no-attach::
118         Disable the creation of an attachment, overriding the
119         configuration setting.
121 --inline[=<boundary>]::
122         Create multipart/mixed attachment, the first part of
123         which is the commit message and the patch itself in the
124         second part, with "Content-Disposition: inline".
126 --thread[=<style>]::
127 --no-thread::
128         Controls addition of In-Reply-To and References headers to
129         make the second and subsequent mails appear as replies to the
130         first.  Also controls generation of the Message-Id header to
131         reference.
133 The optional <style> argument can be either `shallow` or `deep`.
134 'shallow' threading makes every mail a reply to the head of the
135 series, where the head is chosen from the cover letter, the
136 `\--in-reply-to`, and the first patch mail, in this order.  'deep'
137 threading makes every mail a reply to the previous one.
139 The default is --no-thread, unless the 'format.thread' configuration
140 is set.  If --thread is specified without a style, it defaults to the
141 style specified by 'format.thread' if any, or else `shallow`.
143 Beware that the default for 'git send-email' is to thread emails
144 itself.  If you want 'git format-patch' to take care of hreading, you
145 will want to ensure that threading is disabled for 'git send-email'.
147 --in-reply-to=Message-Id::
148         Make the first mail (or all the mails with --no-thread) appear as a
149         reply to the given Message-Id, which avoids breaking threads to
150         provide a new patch series.
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.
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
163         combined with the --numbered option.
165 --cc=<email>::
166         Add a "Cc:" header to the email headers. This is in addition
167         to any configured headers, and may be used multiple times.
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.
172         For example, --add-header="Organization: git-foo"
174 --cover-letter::
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.
179 --suffix=.<sfx>::
180         Instead of using `.patch` as the suffix for generated
181         filenames, use specified suffix.  A common alternative is
182         `--suffix=.txt`.  Leaving this empty will remove the `.patch`
183         suffix.
185 Note that the leading character does not have to be a dot; for example,
186 you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
188 --no-binary::
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.
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.
201 CONFIGURATION
202 -------------
203 You can specify extra mail header lines to be added to each message,
204 defaults for the subject prefix and file suffix, number patches when
205 outputting more than one patch, add "Cc:" headers, configure attachments,
206 and sign off patches with configuration variables.
208 ------------
209 [format]
210         headers = "Organization: git-foo\n"
211         subjectprefix = CHANGE
212         suffix = .txt
213         numbered = auto
214         cc = <email>
215         attach [ = mime-boundary-string ]
216         signoff = true
217 ------------
220 EXAMPLES
221 --------
223 * Extract commits between revisions R1 and R2, and apply them on top of
224 the current branch using 'git-am' to cherry-pick them:
226 ------------
227 $ git format-patch -k --stdout R1..R2 | git am -3 -k
228 ------------
230 * Extract all commits which are in the current branch but not in the
231 origin branch:
233 ------------
234 $ git format-patch origin
235 ------------
237 For each commit a separate file is created in the current directory.
239 * Extract all commits that lead to 'origin' since the inception of the
240 project:
242 ------------
243 $ git format-patch --root origin
244 ------------
246 * The same as the previous one:
248 ------------
249 $ git format-patch -M -B origin
250 ------------
252 Additionally, it detects and handles renames and complete rewrites
253 intelligently to produce a renaming patch.  A renaming patch reduces
254 the amount of text output, and generally makes it easier to review.
255 Note that non-git "patch" programs won't understand renaming patches, so
256 use it only when you know the recipient uses git to apply your patch.
258 * Extract three topmost commits from the current branch and format them
259 as e-mailable patches:
261 ------------
262 $ git format-patch -3
263 ------------
265 SEE ALSO
266 --------
267 linkgit:git-am[1], linkgit:git-send-email[1]
270 Author
271 ------
272 Written by Junio C Hamano <gitster@pobox.com>
274 Documentation
275 --------------
276 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
280 Part of the linkgit:git[1] suite