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 [-n | --numbered | -N | --no-numbered]
14 [--start-number <n>] [--numbered-files]
15 [--in-reply-to=Message-Id] [--suffix=.<sfx>]
16 [--ignore-if-in-upstream]
17 [--subject-prefix=Subject-Prefix]
18 [--to=<email>] [--cc=<email>]
19 [--cover-letter]
20 [<common diff options>]
21 [ <since> | <revision range> ]
22
25 Prepare each commit with its patch in one file per commit, formatted to
26 resemble UNIX mailbox format. The output of this command is convenient
27 for e-mail submission or for use with git am.
28 There are two ways to specify which commits to operate on.
30 1. A single commit, <since>, specifies that the commits leading to the
32 tip of the current branch that are not in the history that leads to
33 the <since> to be output.
34 2. Generic <revision range> expression (see "SPECIFYING REVISIONS"
36 section in git-rev-parse(1)) means the commits in the specified
37 range.
38 The first rule takes precedence in the case of a single <commit>. To
40 apply the second rule, i.e., format everything since the beginning of
41 history up until <commit>, use the --root option: git format-patch
42 --root <commit>. If you want to format only <commit> itself, you can do
43 this with git format-patch -1 <commit>.
44 By default, each output file is numbered sequentially from 1, and uses
46 the first line of the commit message (massaged for pathname safety) as
47 the filename. With the --numbered-files option, the output file names
48 will only be numbers, without the first line of the commit appended.
49 The names of the output files are printed to standard output, unless
50 the --stdout option is specified.
51 If -o is specified, output files are created in <dir>. Otherwise they
53 are created in the current working directory.
54 By default, the subject of a single patch is "[PATCH] First Line" and
56 the subject when multiple patches are output is "[PATCH n/m] First
57 Line". To force 1/1 to be added for a single patch, use -n. To omit
58 patch numbers from the subject, use -N.
59 If given --thread, git-format-patch will generate In-Reply-To and
61 References headers to make the second and subsequent patch mails appear
62 as replies to the first mail; this also generates a Message-Id header
63 to reference.
64
66 -p, --no-stat
67 Generate plain patches without any diffstats.
68 -U<n>, --unified=<n>
70 Generate diffs with <n> lines of context instead of the usual
71 three.
72 --patience
74 Generate a diff using the "patience diff" algorithm.
75 --stat[=width[,name-width]]
77 Generate a diffstat. You can override the default output width for
78 80-column terminal by --stat=width. The width of the filename part
79 can be controlled by giving another width to it separated by a
80 comma.
81 --numstat
83 Similar to --stat, but shows number of added and deleted lines in
84 decimal notation and pathname without abbreviation, to make it more
85 machine friendly. For binary files, outputs two - instead of saying
86 0 0.
87 --shortstat
89 Output only the last line of the --stat format containing total
90 number of modified files, as well as number of added and deleted
91 lines.
92 --dirstat[=limit]
94 Output the distribution of relative amount of changes (number of
95 lines added or removed) for each sub-directory. Directories with
96 changes below a cut-off percent (3% by default) are not shown. The
97 cut-off percent can be set with --dirstat=limit. Changes in a child
98 directory is not counted for the parent directory, unless
99 --cumulative is used.
100 --dirstat-by-file[=limit]
102 Same as --dirstat, but counts changed files instead of lines.
103 --summary
105 Output a condensed summary of extended header information such as
106 creations, renames and mode changes.
107 --no-renames
109 Turn off rename detection, even when the configuration file gives
110 the default to do so.
111 --full-index
113 Instead of the first handful of characters, show the full pre- and
114 post-image blob object names on the "index" line when generating
115 patch format output.
116 --binary
118 In addition to --full-index, output a binary diff that can be
119 applied with git-apply.
120 --abbrev[=<n>]
122 Instead of showing the full 40-byte hexadecimal object name in
123 diff-raw format output and diff-tree header lines, show only a
124 partial prefix. This is independent of the --full-index option
125 above, which controls the diff-patch output format. Non default
126 number of digits can be specified with --abbrev=<n>.
127 -B
129 Break complete rewrite changes into pairs of delete and create.
130 -M
132 Detect renames.
133 -C
135 Detect copies as well as renames. See also --find-copies-harder.
136 --find-copies-harder
138 For performance reasons, by default, -C option finds copies only if
139 the original file of the copy was modified in the same changeset.
140 This flag makes the command inspect unmodified files as candidates
141 for the source of copy. This is a very expensive operation for
142 large projects, so use it with caution. Giving more than one -C
143 option has the same effect.
144 -l<num>
146 The -M and -C options require O(n^2) processing time where n is the
147 number of potential rename/copy targets. This option prevents
148 rename/copy detection from running if the number of rename/copy
149 targets exceeds the specified number.
150 -O<orderfile>
152 Output the patch in the order specified in the <orderfile>, which
153 has one shell glob pattern per line.
154 -a, --text
156 Treat all files as text.
157 --ignore-space-at-eol
159 Ignore changes in whitespace at EOL.
160 -b, --ignore-space-change
162 Ignore changes in amount of whitespace. This ignores whitespace at
163 line end, and considers all other sequences of one or more
164 whitespace characters to be equivalent.
165 -w, --ignore-all-space
167 Ignore whitespace when comparing lines. This ignores differences
168 even if one line has whitespace where the other line has none.
169 --inter-hunk-context=<lines>
171 Show the context between diff hunks, up to the specified number of
172 lines, thereby fusing hunks that are close to each other.
173 --ext-diff
175 Allow an external diff helper to be executed. If you set an
176 external diff driver with gitattributes(5), you need to use this
177 option with git-log(1) and friends.
178 --no-ext-diff
180 Disallow external diff drivers.
181 --ignore-submodules
183 Ignore changes to submodules in the diff generation.
184 --src-prefix=<prefix>
186 Show the given source prefix instead of "a/".
187 --dst-prefix=<prefix>
189 Show the given destination prefix instead of "b/".
190 --no-prefix
192 Do not show any source or destination prefix.
193 For more detailed explanation on these common options, see also
195 gitdiffcore(7).
196 -<n>
198 Limits the number of patches to prepare.
199 -o <dir>, --output-directory <dir>
201 Use <dir> to store the resulting files, instead of the current
202 working directory.
203 -n, --numbered
205 Name output in [PATCH n/m] format, even with a single patch.
206 -N, --no-numbered
208 Name output in [PATCH] format.
209 --start-number <n>
211 Start numbering the patches at <n> instead of 1.
212 --numbered-files
214 Output file names will be a simple number sequence without the
215 default first line of the commit appended.
216 -k, --keep-subject
218 Do not strip/add [PATCH] from the first line of the commit log
219 message.
220 -s, --signoff
222 Add Signed-off-by: line to the commit message, using the committer
223 identity of yourself.
224 --stdout
226 Print all commits to the standard output in mbox format, instead of
227 creating a file for each one.
228 --attach[=<boundary>]
230 Create multipart/mixed attachment, the first part of which is the
231 commit message and the patch itself in the second part, with
232 Content-Disposition: attachment.
233 --no-attach
235 Disable the creation of an attachment, overriding the configuration
236 setting.
237 --inline[=<boundary>]
239 Create multipart/mixed attachment, the first part of which is the
240 commit message and the patch itself in the second part, with
241 Content-Disposition: inline.
242 --thread[=<style>], --no-thread
244 Controls addition of In-Reply-To and References headers to make the
245 second and subsequent mails appear as replies to the first. Also
246 controls generation of the Message-Id header to reference.
247 The optional <style> argument can be either shallow or deep.
249 shallow threading makes every mail a reply to the head of the
250 series, where the head is chosen from the cover letter, the
251 --in-reply-to, and the first patch mail, in this order. deep
252 threading makes every mail a reply to the previous one.
253 The default is --no-thread, unless the format.thread configuration
255 is set. If --thread is specified without a style, it defaults to
256 the style specified by format.thread if any, or else shallow.
257 Beware that the default for git send-email is to thread emails
259 itself. If you want git format-patch to take care of threading, you
260 will want to ensure that threading is disabled for git send-email.
261 --in-reply-to=Message-Id
263 Make the first mail (or all the mails with --no-thread) appear as a
264 reply to the given Message-Id, which avoids breaking threads to
265 provide a new patch series.
266 --ignore-if-in-upstream
268 Do not include a patch that matches a commit in <until>..<since>.
269 This will examine all patches reachable from <since> but not from
270 <until> and compare them with the patches being generated, and any
271 patch that matches is ignored.
272 --subject-prefix=<Subject-Prefix>
274 Instead of the standard [PATCH] prefix in the subject line, instead
275 use [<Subject-Prefix>]. This allows for useful naming of a patch
276 series, and can be combined with the --numbered option.
277 --to=<email>
279 Add a To: header to the email headers. This is in addition to any
280 configured headers, and may be used multiple times.
281 --cc=<email>
283 Add a Cc: header to the email headers. This is in addition to any
284 configured headers, and may be used multiple times.
285 --add-header=<header>
287 Add an arbitrary header to the email headers. This is in addition
288 to any configured headers, and may be used multiple times. For
289 example, --add-header="Organization: git-foo"
290 --cover-letter
292 In addition to the patches, generate a cover letter file containing
293 the shortlog and the overall diffstat. You can fill in a
294 description in the file before sending it out.
295 --suffix=.<sfx>
297 Instead of using .patch as the suffix for generated filenames, use
298 specified suffix. A common alternative is --suffix=.txt. Leaving
299 this empty will remove the .patch suffix.
300 Note that the leading character does not have to be a dot; for
302 example, you can use --suffix=-patch to get
303 0001-description-of-my-change-patch.
304 --no-binary
306 Do not output contents of changes in binary files, instead display
307 a notice that those files changed. Patches generated using this
308 option cannot be applied properly, but they are still useful for
309 code review.
310 --root
312 Treat the revision argument as a <revision range>, even if it is
313 just a single commit (that would normally be treated as a <since>).
314 Note that root commits included in the specified range are always
315 formatted as creation patches, independently of this flag.
316
318 You can specify extra mail header lines to be added to each message,
319 defaults for the subject prefix and file suffix, number patches when
320 outputting more than one patch, add "To" or "Cc:" headers, configure
321 attachments, and sign off patches with configuration variables.
322 [format]
324 headers = "Organization: git-foo\n"
325 subjectprefix = CHANGE
326 suffix = .txt
327 numbered = auto
328 to = <email>
329 cc = <email>
330 attach [ = mime-boundary-string ]
331 signoff = true
332
335 · Extract commits between revisions R1 and R2, and apply them on top
336 of the current branch using git am to cherry-pick them:
337 $ git format-patch -k --stdout R1..R2 | git am -3 -k
339 · Extract all commits which are in the current branch but not in the
342 origin branch:
343 $ git format-patch origin
345 For each commit a separate file is created in the current
347 directory.
348 · Extract all commits that lead to origin since the inception of the
350 project:
351 $ git format-patch --root origin
353 · The same as the previous one:
356 $ git format-patch -M -B origin
358 Additionally, it detects and handles renames and complete rewrites
360 intelligently to produce a renaming patch. A renaming patch reduces
361 the amount of text output, and generally makes it easier to review.
362 Note that non-git "patch" programs won’t understand renaming
363 patches, so use it only when you know the recipient uses git to
364 apply your patch.
365 · Extract three topmost commits from the current branch and format
367 them as e-mailable patches:
368 $ git format-patch -3
370
373 git-am(1), git-send-email(1)
374
376 Written by Junio C Hamano <gitster@pobox.com[1]>
377
379 Documentation by Junio C Hamano and the git-list
380 <git@vger.kernel.org[2]>.
381
383 Part of the git(1) suite
384
386 1. gitster@pobox.com
387 mailto:gitster@pobox.com
388 2. git@vger.kernel.org
390 mailto:git@vger.kernel.org
391Git 1.7.1 08/16/2017 GIT-FORMAT-PATCH(1)