1GIT-FORMAT-PATCH(1) Git Manual GIT-FORMAT-PATCH(1)
2
6 git-format-patch - Prepare patches for e-mail submission
7
9 git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
10 [--no-thread | --thread[=<style>]]
11 [(--attach|--inline)[=<boundary>] | --no-attach]
12 [-s | --signoff]
13 [--signature=<signature> | --no-signature]
14 [-n | --numbered | -N | --no-numbered]
15 [--start-number <n>] [--numbered-files]
16 [--in-reply-to=Message-Id] [--suffix=.<sfx>]
17 [--ignore-if-in-upstream]
18 [--subject-prefix=Subject-Prefix]
19 [--to=<email>] [--cc=<email>]
20 [--cover-letter]
21 [<common diff options>]
22 [ <since> | <revision range> ]
23
26 Prepare each commit with its patch in one file per commit, formatted to
27 resemble UNIX mailbox format. The output of this command is convenient
28 for e-mail submission or for use with git am.
29 There are two ways to specify which commits to operate on.
31 1. A single commit, <since>, specifies that the commits leading to the
33 tip of the current branch that are not in the history that leads to
34 the <since> to be output.
35 2. Generic <revision range> expression (see "SPECIFYING REVISIONS"
37 section in gitrevisions(7)) means the commits in the specified
38 range.
39 The first rule takes precedence in the case of a single <commit>. To
41 apply the second rule, i.e., format everything since the beginning of
42 history up until <commit>, use the --root option: git format-patch
43 --root <commit>. If you want to format only <commit> itself, you can do
44 this with git format-patch -1 <commit>.
45 By default, each output file is numbered sequentially from 1, and uses
47 the first line of the commit message (massaged for pathname safety) as
48 the filename. With the --numbered-files option, the output file names
49 will only be numbers, without the first line of the commit appended.
50 The names of the output files are printed to standard output, unless
51 the --stdout option is specified.
52 If -o is specified, output files are created in <dir>. Otherwise they
54 are created in the current working directory.
55 By default, the subject of a single patch is "[PATCH] First Line" and
57 the subject when multiple patches are output is "[PATCH n/m] First
58 Line". To force 1/1 to be added for a single patch, use -n. To omit
59 patch numbers from the subject, use -N.
60 If given --thread, git-format-patch will generate In-Reply-To and
62 References headers to make the second and subsequent patch mails appear
63 as replies to the first mail; this also generates a Message-Id header
64 to reference.
65
67 -p, --no-stat
68 Generate plain patches without any diffstats.
69 -U<n>, --unified=<n>
71 Generate diffs with <n> lines of context instead of the usual
72 three.
73 --patience
75 Generate a diff using the "patience diff" algorithm.
76 --stat[=<width>[,<name-width>]]
78 Generate a diffstat. You can override the default output width for
79 80-column terminal by --stat=<width>. The width of the filename
80 part can be controlled by giving another width to it separated by a
81 comma.
82 --numstat
84 Similar to --stat, but shows number of added and deleted lines in
85 decimal notation and pathname without abbreviation, to make it more
86 machine friendly. For binary files, outputs two - instead of saying
87 0 0.
88 --shortstat
90 Output only the last line of the --stat format containing total
91 number of modified files, as well as number of added and deleted
92 lines.
93 --dirstat[=<limit>]
95 Output the distribution of relative amount of changes (number of
96 lines added or removed) for each sub-directory. Directories with
97 changes below a cut-off percent (3% by default) are not shown. The
98 cut-off percent can be set with --dirstat=<limit>. Changes in a
99 child directory are not counted for the parent directory, unless
100 --cumulative is used.
101 --dirstat-by-file[=<limit>]
103 Same as --dirstat, but counts changed files instead of lines.
104 --summary
106 Output a condensed summary of extended header information such as
107 creations, renames and mode changes.
108 --no-renames
110 Turn off rename detection, even when the configuration file gives
111 the default to do so.
112 --full-index
114 Instead of the first handful of characters, show the full pre- and
115 post-image blob object names on the "index" line when generating
116 patch format output.
117 --binary
119 In addition to --full-index, output a binary diff that can be
120 applied with git-apply.
121 --abbrev[=<n>]
123 Instead of showing the full 40-byte hexadecimal object name in
124 diff-raw format output and diff-tree header lines, show only a
125 partial prefix. This is independent of the --full-index option
126 above, which controls the diff-patch output format. Non default
127 number of digits can be specified with --abbrev=<n>.
128 -B[<n>][/<m>], --break-rewrites[=[<n>][/<m>]]
130 Break complete rewrite changes into pairs of delete and create.
131 This serves two purposes:
132 It affects the way a change that amounts to a total rewrite of a
134 file not as a series of deletion and insertion mixed together with
135 a very few lines that happen to match textually as the context, but
136 as a single deletion of everything old followed by a single
137 insertion of everything new, and the number m controls this aspect
138 of the -B option (defaults to 60%). -B/70% specifies that less
139 than 30% of the original should remain in the result for git to
140 consider it a total rewrite (i.e. otherwise the resulting patch
141 will be a series of deletion and insertion mixed together with
142 context lines).
143 When used with -M, a totally-rewritten file is also considered as
145 the source of a rename (usually -M only considers a file that
146 disappeared as the source of a rename), and the number n controls
147 this aspect of the -B option (defaults to 50%). -B20% specifies
148 that a change with addition and deletion compared to 20% or more of
149 the file’s size are eligible for being picked up as a possible
150 source of a rename to another file.
151 -M[<n>], --find-renames[=<n>]
153 Detect renames. If n is specified, it is a is a threshold on the
154 similarity index (i.e. amount of addition/deletions compared to the
155 file’s size). For example, -M90% means git should consider a
156 delete/add pair to be a rename if more than 90% of the file hasn’t
157 changed.
158 -C[<n>], --find-copies[=<n>]
160 Detect copies as well as renames. See also --find-copies-harder. If
161 n is specified, it has the same meaning as for -M<n>.
162 --find-copies-harder
164 For performance reasons, by default, -C option finds copies only if
165 the original file of the copy was modified in the same changeset.
166 This flag makes the command inspect unmodified files as candidates
167 for the source of copy. This is a very expensive operation for
168 large projects, so use it with caution. Giving more than one -C
169 option has the same effect.
170 -l<num>
172 The -M and -C options require O(n^2) processing time where n is the
173 number of potential rename/copy targets. This option prevents
174 rename/copy detection from running if the number of rename/copy
175 targets exceeds the specified number.
176 -O<orderfile>
178 Output the patch in the order specified in the <orderfile>, which
179 has one shell glob pattern per line.
180 -a, --text
182 Treat all files as text.
183 --ignore-space-at-eol
185 Ignore changes in whitespace at EOL.
186 -b, --ignore-space-change
188 Ignore changes in amount of whitespace. This ignores whitespace at
189 line end, and considers all other sequences of one or more
190 whitespace characters to be equivalent.
191 -w, --ignore-all-space
193 Ignore whitespace when comparing lines. This ignores differences
194 even if one line has whitespace where the other line has none.
195 --inter-hunk-context=<lines>
197 Show the context between diff hunks, up to the specified number of
198 lines, thereby fusing hunks that are close to each other.
199 --ext-diff
201 Allow an external diff helper to be executed. If you set an
202 external diff driver with gitattributes(5), you need to use this
203 option with git-log(1) and friends.
204 --no-ext-diff
206 Disallow external diff drivers.
207 --ignore-submodules[=<when>]
209 Ignore changes to submodules in the diff generation. <when> can be
210 either "none", "untracked", "dirty" or "all", which is the default
211 Using "none" will consider the submodule modified when it either
212 contains untracked or modified files or its HEAD differs from the
213 commit recorded in the superproject and can be used to override any
214 settings of the ignore option in git-config(1) or gitmodules(5).
215 When "untracked" is used submodules are not considered dirty when
216 they only contain untracked content (but they are still scanned for
217 modified content). Using "dirty" ignores all changes to the work
218 tree of submodules, only changes to the commits stored in the
219 superproject are shown (this was the behavior until 1.7.0). Using
220 "all" hides all changes to submodules.
221 --src-prefix=<prefix>
223 Show the given source prefix instead of "a/".
224 --dst-prefix=<prefix>
226 Show the given destination prefix instead of "b/".
227 --no-prefix
229 Do not show any source or destination prefix.
230 For more detailed explanation on these common options, see also
232 gitdiffcore(7).
233 -<n>
235 Prepare patches from the topmost <n> commits.
236 -o <dir>, --output-directory <dir>
238 Use <dir> to store the resulting files, instead of the current
239 working directory.
240 -n, --numbered
242 Name output in [PATCH n/m] format, even with a single patch.
243 -N, --no-numbered
245 Name output in [PATCH] format.
246 --start-number <n>
248 Start numbering the patches at <n> instead of 1.
249 --numbered-files
251 Output file names will be a simple number sequence without the
252 default first line of the commit appended.
253 -k, --keep-subject
255 Do not strip/add [PATCH] from the first line of the commit log
256 message.
257 -s, --signoff
259 Add Signed-off-by: line to the commit message, using the committer
260 identity of yourself.
261 --stdout
263 Print all commits to the standard output in mbox format, instead of
264 creating a file for each one.
265 --attach[=<boundary>]
267 Create multipart/mixed attachment, the first part of which is the
268 commit message and the patch itself in the second part, with
269 Content-Disposition: attachment.
270 --no-attach
272 Disable the creation of an attachment, overriding the configuration
273 setting.
274 --inline[=<boundary>]
276 Create multipart/mixed attachment, the first part of which is the
277 commit message and the patch itself in the second part, with
278 Content-Disposition: inline.
279 --thread[=<style>], --no-thread
281 Controls addition of In-Reply-To and References headers to make the
282 second and subsequent mails appear as replies to the first. Also
283 controls generation of the Message-Id header to reference.
284 The optional <style> argument can be either shallow or deep.
286 shallow threading makes every mail a reply to the head of the
287 series, where the head is chosen from the cover letter, the
288 --in-reply-to, and the first patch mail, in this order. deep
289 threading makes every mail a reply to the previous one.
290 The default is --no-thread, unless the format.thread configuration
292 is set. If --thread is specified without a style, it defaults to
293 the style specified by format.thread if any, or else shallow.
294 Beware that the default for git send-email is to thread emails
296 itself. If you want git format-patch to take care of threading, you
297 will want to ensure that threading is disabled for git send-email.
298 --in-reply-to=Message-Id
300 Make the first mail (or all the mails with --no-thread) appear as a
301 reply to the given Message-Id, which avoids breaking threads to
302 provide a new patch series.
303 --ignore-if-in-upstream
305 Do not include a patch that matches a commit in <until>..<since>.
306 This will examine all patches reachable from <since> but not from
307 <until> and compare them with the patches being generated, and any
308 patch that matches is ignored.
309 --subject-prefix=<Subject-Prefix>
311 Instead of the standard [PATCH] prefix in the subject line, instead
312 use [<Subject-Prefix>]. This allows for useful naming of a patch
313 series, and can be combined with the --numbered option.
314 --to=<email>
316 Add a To: header to the email headers. This is in addition to any
317 configured headers, and may be used multiple times.
318 --cc=<email>
320 Add a Cc: header to the email headers. This is in addition to any
321 configured headers, and may be used multiple times.
322 --add-header=<header>
324 Add an arbitrary header to the email headers. This is in addition
325 to any configured headers, and may be used multiple times. For
326 example, --add-header="Organization: git-foo"
327 --cover-letter
329 In addition to the patches, generate a cover letter file containing
330 the shortlog and the overall diffstat. You can fill in a
331 description in the file before sending it out.
332 --[no]-signature=<signature>
334 Add a signature to each message produced. Per RFC 3676 the
335 signature is separated from the body by a line with '-- ' on it. If
336 the signature option is omitted the signature defaults to the git
337 version number.
338 --suffix=.<sfx>
340 Instead of using .patch as the suffix for generated filenames, use
341 specified suffix. A common alternative is --suffix=.txt. Leaving
342 this empty will remove the .patch suffix.
343 Note that the leading character does not have to be a dot; for
345 example, you can use --suffix=-patch to get
346 0001-description-of-my-change-patch.
347 --no-binary
349 Do not output contents of changes in binary files, instead display
350 a notice that those files changed. Patches generated using this
351 option cannot be applied properly, but they are still useful for
352 code review.
353 --root
355 Treat the revision argument as a <revision range>, even if it is
356 just a single commit (that would normally be treated as a <since>).
357 Note that root commits included in the specified range are always
358 formatted as creation patches, independently of this flag.
359
361 You can specify extra mail header lines to be added to each message,
362 defaults for the subject prefix and file suffix, number patches when
363 outputting more than one patch, add "To" or "Cc:" headers, configure
364 attachments, and sign off patches with configuration variables.
365 [format]
367 headers = "Organization: git-foo\n"
368 subjectprefix = CHANGE
369 suffix = .txt
370 numbered = auto
371 to = <email>
372 cc = <email>
373 attach [ = mime-boundary-string ]
374 signoff = true
375
378 · Extract commits between revisions R1 and R2, and apply them on top
379 of the current branch using git am to cherry-pick them:
380 $ git format-patch -k --stdout R1..R2 | git am -3 -k
382 · Extract all commits which are in the current branch but not in the
385 origin branch:
386 $ git format-patch origin
388 For each commit a separate file is created in the current
390 directory.
391 · Extract all commits that lead to origin since the inception of the
393 project:
394 $ git format-patch --root origin
396 · The same as the previous one:
399 $ git format-patch -M -B origin
401 Additionally, it detects and handles renames and complete rewrites
403 intelligently to produce a renaming patch. A renaming patch reduces
404 the amount of text output, and generally makes it easier to review.
405 Note that non-git "patch" programs won’t understand renaming
406 patches, so use it only when you know the recipient uses git to
407 apply your patch.
408 · Extract three topmost commits from the current branch and format
410 them as e-mailable patches:
411 $ git format-patch -3
413
416 git-am(1), git-send-email(1)
417
419 Written by Junio C Hamano <gitster@pobox.com[1]>
420
422 Documentation by Junio C Hamano and the git-list
423 <git@vger.kernel.org[2]>.
424
426 Part of the git(1) suite
427
429 1. gitster@pobox.com
430 mailto:gitster@pobox.com
431 2. git@vger.kernel.org
433 mailto:git@vger.kernel.org
434Git 1.7.4.4 04/11/2011 GIT-FORMAT-PATCH(1)