blob: fe2f69d36e601081192b5fd857f79999cc911dde [file] [log] [blame]
Junio C Hamano215a7ad2005-09-07 17:26:23 -07001git-format-patch(1)
2===================
Junio C Hamano7fc9d692005-08-23 01:49:47 -07003
4NAME
5----
Fredrik Kuivinen7bd7f282006-03-09 17:24:50 +01006git-format-patch - Prepare patches for e-mail submission
Junio C Hamano7fc9d692005-08-23 01:49:47 -07007
8
9SYNOPSIS
10--------
Jonas Fonseca353ce812005-12-31 18:37:15 +010011[verse]
Stephen Boyd50710ce2009-04-23 09:16:52 -070012'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
Yann Dirsonf693b7e2009-07-22 23:39:31 +020013 [--no-thread | --thread[=<style>]]
Stephen Boyd50710ce2009-04-23 09:16:52 -070014 [(--attach|--inline)[=<boundary>] | --no-attach]
15 [-s | --signoff]
Stephen Boyd6622d9c2010-06-15 22:59:25 -070016 [--signature=<signature> | --no-signature]
Jeremiah Mahler70226502014-05-23 21:08:14 -070017 [--signature-file=<file>]
Daniel Barkalowa5a27c72008-02-18 22:56:13 -050018 [-n | --numbered | -N | --no-numbered]
19 [--start-number <n>] [--numbered-files]
Denton Liuc1a6f212019-08-27 00:05:17 -040020 [--in-reply-to=<message id>] [--suffix=.<sfx>]
Daniel Barkalowa5a27c72008-02-18 22:56:13 -050021 [--ignore-if-in-upstream]
Denton Liubf8e65b2019-10-15 02:06:40 -070022 [--cover-from-description=<mode>]
Denton Liuc1a6f212019-08-27 00:05:17 -040023 [--rfc] [--subject-prefix=<subject prefix>]
Josh Triplett68e83a52016-09-19 21:23:25 -070024 [(--reroll-count|-v) <n>]
Steven Drakeae6c0982010-02-17 12:39:34 +130025 [--to=<email>] [--cc=<email>]
Denton Liu83d9db72019-05-10 14:37:03 -040026 [--[no-]cover-letter] [--quiet]
Emma Brooks19d097e2020-04-08 04:31:38 +000027 [--[no-]encode-email-headers]
Denton Liu83d9db72019-05-10 14:37:03 -040028 [--no-notes | --notes[=<ref>]]
Eric Sunshine126facf2018-07-22 05:57:05 -040029 [--interdiff=<previous>]
Eric Sunshine8631bf12018-07-22 05:57:16 -040030 [--range-diff=<previous> [--creation-factor=<percent>]]
Junio C Hamano3baf58b2020-11-06 13:56:24 -080031 [--filename-max-length=<n>]
Kevin Willford738e88a2017-08-10 14:32:55 -040032 [--progress]
Stephen Boyd50710ce2009-04-23 09:16:52 -070033 [<common diff options>]
Junio C Hamano8a1d0762007-08-28 00:38:48 -070034 [ <since> | <revision range> ]
Junio C Hamano7fc9d692005-08-23 01:49:47 -070035
36DESCRIPTION
37-----------
Dennis Stosberg2052d142006-05-31 16:14:08 +020038
Jeff King8e0601f2021-05-01 10:13:24 -040039Prepare each non-merge commit with its "patch" in
Junio C Hamano28e29ee2021-03-24 10:35:40 -070040one "message" per commit, formatted to resemble a UNIX mailbox.
Dennis Stosberg2052d142006-05-31 16:14:08 +020041The output of this command is convenient for e-mail submission or
Thomas Rast0b444cd2010-01-10 00:33:00 +010042for use with 'git am'.
Junio C Hamano35ef3a42005-09-07 23:04:52 -070043
Junio C Hamano28e29ee2021-03-24 10:35:40 -070044A "message" generated by the command consists of three parts:
45
46* A brief metadata header that begins with `From <commit>`
47 with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs
48 like "file(1)" to recognize that the file is an output from this
49 command, fields that record the author identity, the author date,
50 and the title of the change (taken from the first paragraph of the
51 commit log message).
52
53* The second and subsequent paragraphs of the commit log message.
54
55* The "patch", which is the "diff -p --stat" output (see
56 linkgit:git-diff[1]) between the commit and its parent.
57
58The log message and the patch is separated by a line with a
59three-dash line.
60
Junio C Hamano8a1d0762007-08-28 00:38:48 -070061There are two ways to specify which commits to operate on.
62
631. A single commit, <since>, specifies that the commits leading
64 to the tip of the current branch that are not in the history
65 that leads to the <since> to be output.
66
672. Generic <revision range> expression (see "SPECIFYING
Jonathan Nieder9d83e382010-10-11 11:03:32 -050068 REVISIONS" section in linkgit:gitrevisions[7]) means the
Junio C Hamano2f6a3822007-08-28 21:58:53 -070069 commits in the specified range.
70
Thomas Rast2d266f92009-03-26 18:29:25 +010071The first rule takes precedence in the case of a single <commit>. To
72apply the second rule, i.e., format everything since the beginning of
Martin Ågren9e9f1322018-04-17 21:15:26 +020073history up until <commit>, use the `--root` option: `git format-patch
Jeff King6cf378f2012-04-26 04:51:57 -040074--root <commit>`. If you want to format only <commit> itself, you
Björn Gustavssondce5ef12009-11-07 10:53:07 +010075can do this with `git format-patch -1 <commit>`.
Junio C Hamano8a1d0762007-08-28 00:38:48 -070076
Jon Loeligere6ff0f42007-06-05 15:06:53 -050077By default, each output file is numbered sequentially from 1, and uses the
Dennis Stosberg2052d142006-05-31 16:14:08 +020078first line of the commit message (massaged for pathname safety) as
Björn Gustavssondce5ef12009-11-07 10:53:07 +010079the filename. With the `--numbered-files` option, the output file names
Jon Loeligere6ff0f42007-06-05 15:06:53 -050080will only be numbers, without the first line of the commit appended.
81The names of the output files are printed to standard
Björn Gustavssondce5ef12009-11-07 10:53:07 +010082output, unless the `--stdout` option is specified.
Andreas Ericsson66f04f32006-02-07 09:37:54 +000083
Björn Gustavssondce5ef12009-11-07 10:53:07 +010084If `-o` is specified, output files are created in <dir>. Otherwise
Alexander Kuleshovbc6bf2d2016-01-13 06:20:11 -070085they are created in the current working directory. The default path
Tom Russelloae9f6312016-06-08 19:23:16 +020086can be set with the `format.outputDirectory` configuration option.
Alexander Kuleshovbc6bf2d2016-01-13 06:20:11 -070087The `-o` option takes precedence over `format.outputDirectory`.
88To store patches in the current working directory even when
Bert Wesargedefc312019-10-11 10:36:41 +020089`format.outputDirectory` points elsewhere, use `-o .`. All directory
90components will be created.
Junio C Hamano35ef3a42005-09-07 23:04:52 -070091
Jeremy White52ffe992012-09-13 17:27:09 -050092By default, the subject of a single patch is "[PATCH] " followed by
93the concatenation of lines from the commit message up to the first blank
94line (see the DISCUSSION section of linkgit:git-commit[1]).
95
96When multiple patches are output, the subject prefix will instead be
97"[PATCH n/m] ". To force 1/1 to be added for a single patch, use `-n`.
98To omit patch numbers from the subject, use `-N`.
Junio C Hamano35ef3a42005-09-07 23:04:52 -070099
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100100If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
101`References` headers to make the second and subsequent patch mails appear
102as replies to the first mail; this also generates a `Message-Id` header to
Josh Triplettcc35de82006-07-14 17:49:04 -0700103reference.
Junio C Hamano7fc9d692005-08-23 01:49:47 -0700104
105OPTIONS
106-------
Sergei Organovc1a95fa2007-11-15 16:19:29 +0300107:git-format-patch: 1
Brian Gernhardtb8105372007-03-05 22:27:44 -0500108include::diff-options.txt[]
109
Miklos Vajnaed5f07a2007-07-04 01:38:29 +0200110-<n>::
Ramkumar Ramachandra2c642ed2010-08-28 01:58:16 +0530111 Prepare patches from the topmost <n> commits.
Miklos Vajnaed5f07a2007-07-04 01:38:29 +0200112
Stephan Beyer32402402008-06-08 03:36:09 +0200113-o <dir>::
114--output-directory <dir>::
Junio C Hamano35ef3a42005-09-07 23:04:52 -0700115 Use <dir> to store the resulting files, instead of the
Junio C Hamanoefd02012006-06-06 08:46:23 -0700116 current working directory.
Junio C Hamano7fc9d692005-08-23 01:49:47 -0700117
Stephan Beyer32402402008-06-08 03:36:09 +0200118-n::
119--numbered::
Brian Gernhardta567fdc2008-10-02 16:55:39 -0400120 Name output in '[PATCH n/m]' format, even with a single patch.
Junio C Hamano35ef3a42005-09-07 23:04:52 -0700121
Stephan Beyer32402402008-06-08 03:36:09 +0200122-N::
123--no-numbered::
Brian Gernhardt49604a42007-11-03 23:38:24 -0400124 Name output in '[PATCH]' format.
125
Dennis Stosberg2052d142006-05-31 16:14:08 +0200126--start-number <n>::
127 Start numbering the patches at <n> instead of 1.
128
Jon Loeligere6ff0f42007-06-05 15:06:53 -0500129--numbered-files::
130 Output file names will be a simple number sequence
131 without the default first line of the commit appended.
Jon Loeligere6ff0f42007-06-05 15:06:53 -0500132
Stephan Beyer32402402008-06-08 03:36:09 +0200133-k::
134--keep-subject::
Junio C Hamano35ef3a42005-09-07 23:04:52 -0700135 Do not strip/add '[PATCH]' from the first line of the
136 commit log message.
137
Stephan Beyer32402402008-06-08 03:36:09 +0200138-s::
139--signoff::
Bradley M. Kuhn3abd4a62020-10-19 18:03:55 -0700140 Add a `Signed-off-by` trailer to the commit message, using
Nikolai Weibull6f855372005-12-09 00:28:05 +0100141 the committer identity of yourself.
David A. Wheelerb2c150d2016-01-05 14:20:26 -0500142 See the signoff option in linkgit:git-commit[1] for more information.
Nikolai Weibull6f855372005-12-09 00:28:05 +0100143
Junio C Hamano54ba6012005-10-06 14:25:52 -0700144--stdout::
Dennis Stosberg2052d142006-05-31 16:14:08 +0200145 Print all commits to the standard output in mbox format,
146 instead of creating a file for each one.
Junio C Hamano7fc9d692005-08-23 01:49:47 -0700147
Johannes Schindelinc112f682007-03-04 00:12:06 +0100148--attach[=<boundary>]::
149 Create multipart/mixed attachment, the first part of
150 which is the commit message and the patch itself in the
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100151 second part, with `Content-Disposition: attachment`.
Johannes Schindelinc112f682007-03-04 00:12:06 +0100152
Jeremy White0db52602009-02-12 09:51:55 -0600153--no-attach::
154 Disable the creation of an attachment, overriding the
155 configuration setting.
156
Johannes Schindelinc112f682007-03-04 00:12:06 +0100157--inline[=<boundary>]::
158 Create multipart/mixed attachment, the first part of
159 which is the commit message and the patch itself in the
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100160 second part, with `Content-Disposition: inline`.
Mike McCormacka15a44e2006-03-10 13:47:24 +0900161
Thomas Rast30984ed2009-02-19 22:26:33 +0100162--thread[=<style>]::
Yann Dirsonf693b7e2009-07-22 23:39:31 +0200163--no-thread::
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100164 Controls addition of `In-Reply-To` and `References` headers to
Yann Dirsonf693b7e2009-07-22 23:39:31 +0200165 make the second and subsequent mails appear as replies to the
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100166 first. Also controls generation of the `Message-Id` header to
Yann Dirsonf693b7e2009-07-22 23:39:31 +0200167 reference.
Thomas Rast30984ed2009-02-19 22:26:33 +0100168+
169The optional <style> argument can be either `shallow` or `deep`.
Stephen Boydfd1ff302009-04-23 02:37:57 -0700170'shallow' threading makes every mail a reply to the head of the
Thomas Rast30984ed2009-02-19 22:26:33 +0100171series, where the head is chosen from the cover letter, the
Jeff King6cf378f2012-04-26 04:51:57 -0400172`--in-reply-to`, and the first patch mail, in this order. 'deep'
Yann Dirsonf693b7e2009-07-22 23:39:31 +0200173threading makes every mail a reply to the previous one.
174+
Tom Russelloae9f6312016-06-08 19:23:16 +0200175The default is `--no-thread`, unless the `format.thread` configuration
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100176is set. If `--thread` is specified without a style, it defaults to the
Tom Russelloae9f6312016-06-08 19:23:16 +0200177style specified by `format.thread` if any, or else `shallow`.
Yann Dirsonf693b7e2009-07-22 23:39:31 +0200178+
179Beware that the default for 'git send-email' is to thread emails
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100180itself. If you want `git format-patch` to take care of threading, you
181will want to ensure that threading is disabled for `git send-email`.
Junio C Hamano28ffb892005-11-05 02:55:18 -0800182
Denton Liuc1a6f212019-08-27 00:05:17 -0400183--in-reply-to=<message id>::
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100184 Make the first mail (or all the mails with `--no-thread`) appear as a
Denton Liuc1a6f212019-08-27 00:05:17 -0400185 reply to the given <message id>, which avoids breaking threads to
Josh Triplettda566452006-07-14 17:49:08 -0700186 provide a new patch series.
187
David Kågedalcc75ad62007-01-18 12:27:35 +0100188--ignore-if-in-upstream::
189 Do not include a patch that matches a commit in
190 <until>..<since>. This will examine all patches reachable
191 from <since> but not from <until> and compare them with the
192 patches being generated, and any patch that matches is
193 ignored.
194
Denton Liubf8e65b2019-10-15 02:06:40 -0700195--cover-from-description=<mode>::
196 Controls which parts of the cover letter will be automatically
197 populated using the branch's description.
198+
199If `<mode>` is `message` or `default`, the cover letter subject will be
200populated with placeholder text. The body of the cover letter will be
201populated with the branch's description. This is the default mode when
202no configuration nor command line option is specified.
203+
204If `<mode>` is `subject`, the first paragraph of the branch description will
205populate the cover letter subject. The remainder of the description will
206populate the body of the cover letter.
207+
208If `<mode>` is `auto`, if the first paragraph of the branch description
209is greater than 100 bytes, then the mode will be `message`, otherwise
210`subject` will be used.
211+
212If `<mode>` is `none`, both the cover letter subject and body will be
213populated with placeholder text.
214
Denton Liuc1a6f212019-08-27 00:05:17 -0400215--subject-prefix=<subject prefix>::
Robin H. Johnson2d9e4a42007-04-11 16:58:07 -0700216 Instead of the standard '[PATCH]' prefix in the subject
Denton Liuc1a6f212019-08-27 00:05:17 -0400217 line, instead use '[<subject prefix>]'. This
Robin H. Johnson2d9e4a42007-04-11 16:58:07 -0700218 allows for useful naming of a patch series, and can be
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100219 combined with the `--numbered` option.
Robin H. Johnson2d9e4a42007-04-11 16:58:07 -0700220
Junio C Hamano3baf58b2020-11-06 13:56:24 -0800221--filename-max-length=<n>::
222 Instead of the standard 64 bytes, chomp the generated output
223 filenames at around '<n>' bytes (too short a value will be
224 silently raised to a reasonable length). Defaults to the
225 value of the `format.filenameMaxLength` configuration
226 variable, or 64 if unconfigured.
227
Josh Triplett68e83a52016-09-19 21:23:25 -0700228--rfc::
229 Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For
230 Comments"; use this when sending an experimental patch for
231 discussion rather than application.
232
Junio C Hamano7952ea62013-01-02 14:19:05 -0800233-v <n>::
Junio C Hamano4aad08e2013-01-02 14:16:07 -0800234--reroll-count=<n>::
235 Mark the series as the <n>-th iteration of the topic. The
Frans Klaverd614f072015-06-10 23:01:14 +0200236 output filenames have `v<n>` prepended to them, and the
Junio C Hamano4aad08e2013-01-02 14:16:07 -0800237 subject prefix ("PATCH" by default, but configurable via the
238 `--subject-prefix` option) has ` v<n>` appended to it. E.g.
239 `--reroll-count=4` may produce `v4-0001-add-makefile.patch`
240 file that has "Subject: [PATCH v4 1/20] Add makefile" in it.
ZheNing Hudb919882021-03-23 11:12:25 +0000241 `<n>` does not have to be an integer (e.g. "--reroll-count=4.4",
242 or "--reroll-count=4rev2" are allowed), but the downside of
243 using such a reroll-count is that the range-diff/interdiff
244 with the previous version does not state exactly which
245 version the new interation is compared against.
Junio C Hamano4aad08e2013-01-02 14:16:07 -0800246
Steven Drakeae6c0982010-02-17 12:39:34 +1300247--to=<email>::
248 Add a `To:` header to the email headers. This is in addition
249 to any configured headers, and may be used multiple times.
Thomas Rastb2cd17b2011-08-29 22:10:49 +0200250 The negated form `--no-to` discards all `To:` headers added so
251 far (from config or command line).
Steven Drakeae6c0982010-02-17 12:39:34 +1300252
Daniel Barkalow736cc672008-02-19 02:40:35 -0500253--cc=<email>::
Björn Gustavssondce5ef12009-11-07 10:53:07 +0100254 Add a `Cc:` header to the email headers. This is in addition
Daniel Barkalow736cc672008-02-19 02:40:35 -0500255 to any configured headers, and may be used multiple times.
Thomas Rastb2cd17b2011-08-29 22:10:49 +0200256 The negated form `--no-cc` discards all `Cc:` headers added so
257 far (from config or command line).
Daniel Barkalow736cc672008-02-19 02:40:35 -0500258
Jeff Kinga9080472013-07-03 03:08:22 -0400259--from::
260--from=<ident>::
261 Use `ident` in the `From:` header of each commit email. If the
262 author ident of the commit is not textually identical to the
263 provided `ident`, place a `From:` header in the body of the
264 message with the original author. If no `ident` is given, use
265 the committer ident.
266+
267Note that this option is only useful if you are actually sending the
268emails and want to identify yourself as the sender, but retain the
269original author (and `git am` will correctly pick up the in-body
270header). Note also that `git send-email` already handles this
271transformation for you, and this option should not be used if you are
272feeding the result to `git send-email`.
273
Michael Hendricksd7d9c2d2009-03-26 10:51:05 -0600274--add-header=<header>::
275 Add an arbitrary header to the email headers. This is in addition
276 to any configured headers, and may be used multiple times.
Thomas Rastb2cd17b2011-08-29 22:10:49 +0200277 For example, `--add-header="Organization: git-foo"`.
278 The negated form `--no-add-header` discards *all* (`To:`,
279 `Cc:`, and custom) headers added so far from config or command
280 line.
Michael Hendricksd7d9c2d2009-03-26 10:51:05 -0600281
Felipe Contreras2a4c2602013-04-07 12:46:23 -0500282--[no-]cover-letter::
Matt McCutchenf4912392008-08-14 13:37:41 -0400283 In addition to the patches, generate a cover letter file
Philip Oakley561d2b72015-09-14 15:10:53 +0100284 containing the branch description, shortlog and the overall diffstat. You can
Matt McCutchenf4912392008-08-14 13:37:41 -0400285 fill in a description in the file before sending it out.
Daniel Barkalowa5a27c72008-02-18 22:56:13 -0500286
Emma Brooks19d097e2020-04-08 04:31:38 +0000287--encode-email-headers::
288--no-encode-email-headers::
289 Encode email headers that have non-ASCII characters with
290 "Q-encoding" (described in RFC 2047), instead of outputting the
291 headers verbatim. Defaults to the value of the
292 `format.encodeEmailHeaders` configuration variable.
293
Eric Sunshine126facf2018-07-22 05:57:05 -0400294--interdiff=<previous>::
Eric Sunshineee6cbf72018-07-22 05:57:09 -0400295 As a reviewer aid, insert an interdiff into the cover letter,
296 or as commentary of the lone patch of a 1-patch series, showing
Eric Sunshine126facf2018-07-22 05:57:05 -0400297 the differences between the previous version of the patch series and
298 the series currently being formatted. `previous` is a single revision
299 naming the tip of the previous series which shares a common base with
300 the series being formatted (for example `git format-patch
301 --cover-letter --interdiff=feature/v1 -3 feature/v2`).
302
Eric Sunshine31e26172018-07-22 05:57:13 -0400303--range-diff=<previous>::
304 As a reviewer aid, insert a range-diff (see linkgit:git-range-diff[1])
Eric Sunshine40ce4162018-07-22 05:57:17 -0400305 into the cover letter, or as commentary of the lone patch of a
306 1-patch series, showing the differences between the previous
Eric Sunshine31e26172018-07-22 05:57:13 -0400307 version of the patch series and the series currently being formatted.
Eric Sunshine2e6fd712018-07-22 05:57:14 -0400308 `previous` can be a single revision naming the tip of the previous
309 series if it shares a common base with the series being formatted (for
Eric Sunshine31e26172018-07-22 05:57:13 -0400310 example `git format-patch --cover-letter --range-diff=feature/v1 -3
Eric Sunshine2e6fd712018-07-22 05:57:14 -0400311 feature/v2`), or a revision range if the two versions of the series are
312 disjoint (for example `git format-patch --cover-letter
313 --range-diff=feature/v1~3..feature/v1 -3 feature/v2`).
Junio C Hamanod8981c32018-11-30 13:27:11 +0900314+
315Note that diff options passed to the command affect how the primary
316product of `format-patch` is generated, and they are not passed to
317the underlying `range-diff` machinery used to generate the cover-letter
318material (this may change in the future).
Eric Sunshine31e26172018-07-22 05:57:13 -0400319
Eric Sunshine8631bf12018-07-22 05:57:16 -0400320--creation-factor=<percent>::
321 Used with `--range-diff`, tweak the heuristic which matches up commits
322 between the previous and current series of patches by adjusting the
323 creation/deletion cost fudge factor. See linkgit:git-range-diff[1])
324 for details.
325
Junio C Hamanoe422c0c2012-10-19 13:01:05 -0700326--notes[=<ref>]::
Denton Liu83d9db72019-05-10 14:37:03 -0400327--no-notes::
Junio C Hamanoe422c0c2012-10-19 13:01:05 -0700328 Append the notes (see linkgit:git-notes[1]) for the commit
329 after the three-dash line.
330+
331The expected use case of this is to write supporting explanation for
Philip Oakley6454d9f2012-10-21 22:34:10 +0100332the commit that does not belong to the commit log message proper,
333and include it with the patch submission. While one can simply write
334these explanations after `format-patch` has run but before sending,
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100335keeping them as Git notes allows them to be maintained between versions
Philip Oakley6454d9f2012-10-21 22:34:10 +0100336of the patch series (but see the discussion of the `notes.rewrite`
337configuration options in linkgit:git-notes[1] to use this workflow).
Denton Liu13cdf782019-05-16 19:14:14 -0400338+
339The default is `--no-notes`, unless the `format.notes` configuration is
340set.
Junio C Hamanoe422c0c2012-10-19 13:01:05 -0700341
Ævar Arnfjörð Bjarmason2c7ee982017-03-20 13:20:29 +0000342--[no-]signature=<signature>::
Stephen Boyd6622d9c2010-06-15 22:59:25 -0700343 Add a signature to each message produced. Per RFC 3676 the signature
344 is separated from the body by a line with '-- ' on it. If the
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100345 signature option is omitted the signature defaults to the Git version
Stephen Boyd6622d9c2010-06-15 22:59:25 -0700346 number.
347
Jeremiah Mahler70226502014-05-23 21:08:14 -0700348--signature-file=<file>::
349 Works just like --signature except the signature is read from a file.
350
Junio C Hamano03eeaea2007-01-17 11:12:03 -0800351--suffix=.<sfx>::
Junio C Hamano917a8f82007-01-17 15:03:39 -0800352 Instead of using `.patch` as the suffix for generated
Brian Hetro02783072007-08-23 20:44:13 -0400353 filenames, use specified suffix. A common alternative is
Stephen Boyd50710ce2009-04-23 09:16:52 -0700354 `--suffix=.txt`. Leaving this empty will remove the `.patch`
355 suffix.
Junio C Hamano03eeaea2007-01-17 11:12:03 -0800356+
Stephen Boyd50710ce2009-04-23 09:16:52 -0700357Note that the leading character does not have to be a dot; for example,
358you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
Junio C Hamano03eeaea2007-01-17 11:12:03 -0800359
Stefan Bellerb7df0982013-08-03 13:51:20 +0200360-q::
Carlos Martín Nietob781cfa2011-04-12 17:51:37 +0200361--quiet::
362 Do not print the names of the generated files to standard output.
363
Caio Marcelo de Oliveira Filho37c22a42008-05-09 19:55:43 -0300364--no-binary::
Stephen Boyd50710ce2009-04-23 09:16:52 -0700365 Do not output contents of changes in binary files, instead
366 display a notice that those files changed. Patches generated
367 using this option cannot be applied properly, but they are
368 still useful for code review.
Caio Marcelo de Oliveira Filho37c22a42008-05-09 19:55:43 -0300369
brian m. carlson3a30aa12015-12-15 01:52:04 +0000370--zero-commit::
371 Output an all-zero hash in each patch's From header instead
372 of the hash of the commit.
373
Denton Liu945dc552019-12-04 13:25:06 -0800374--[no-]base[=<commit>]::
Xiaolong Yefa2ab862016-04-26 15:51:22 +0800375 Record the base tree information to identify the state the
376 patch series applies to. See the BASE TREE INFORMATION section
Denton Liuc1a6f212019-08-27 00:05:17 -0400377 below for details. If <commit> is "auto", a base commit is
Denton Liu945dc552019-12-04 13:25:06 -0800378 automatically chosen. The `--no-base` option overrides a
379 `format.useAutoBase` configuration.
Xiaolong Yefa2ab862016-04-26 15:51:22 +0800380
Thomas Rast2d266f92009-03-26 18:29:25 +0100381--root::
382 Treat the revision argument as a <revision range>, even if it
383 is just a single commit (that would normally be treated as a
384 <since>). Note that root commits included in the specified
385 range are always formatted as creation patches, independently
386 of this flag.
387
Kevin Willford738e88a2017-08-10 14:32:55 -0400388--progress::
389 Show progress reports on stderr as patches are generated.
390
Mike McCormack96ce6d22006-03-10 13:47:59 +0900391CONFIGURATION
392-------------
Stephen Boyd50710ce2009-04-23 09:16:52 -0700393You can specify extra mail header lines to be added to each message,
394defaults for the subject prefix and file suffix, number patches when
Denton Liuc1a6f212019-08-27 00:05:17 -0400395outputting more than one patch, add "To:" or "Cc:" headers, configure
396attachments, change the patch output directory, and sign off patches
397with configuration variables.
Mike McCormack96ce6d22006-03-10 13:47:59 +0900398
Junio C Hamano917a8f82007-01-17 15:03:39 -0800399------------
Mike McCormack96ce6d22006-03-10 13:47:59 +0900400[format]
Jonathan Nieder7f9d77f2008-07-03 00:03:54 -0500401 headers = "Organization: git-foo\n"
Nguyễn Thái Ngọc Duyda0005b2015-03-11 16:32:45 -0400402 subjectPrefix = CHANGE
Jonathan Nieder7f9d77f2008-07-03 00:03:54 -0500403 suffix = .txt
404 numbered = auto
Steven Drakeae6c0982010-02-17 12:39:34 +1300405 to = <email>
Miklos Vajnafe8928e2008-04-26 23:19:06 +0200406 cc = <email>
Jeremy White0db52602009-02-12 09:51:55 -0600407 attach [ = mime-boundary-string ]
Nguyễn Thái Ngọc Duyda0005b2015-03-11 16:32:45 -0400408 signOff = true
Denton Liuc1a6f212019-08-27 00:05:17 -0400409 outputDirectory = <directory>
410 coverLetter = auto
Denton Liubf8e65b2019-10-15 02:06:40 -0700411 coverFromDescription = auto
Junio C Hamano917a8f82007-01-17 15:03:39 -0800412------------
Junio C Hamano03eeaea2007-01-17 11:12:03 -0800413
Mike McCormack96ce6d22006-03-10 13:47:59 +0900414
Jonathan Niedere0d48272011-04-14 21:22:02 -0500415DISCUSSION
416----------
417
418The patch produced by 'git format-patch' is in UNIX mailbox format,
419with a fixed "magic" time stamp to indicate that the file is output
420from format-patch rather than a real mailbox, like so:
421
422------------
423From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
424From: Tony Luck <tony.luck@intel.com>
425Date: Tue, 13 Jul 2010 11:42:54 -0700
426Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
427 =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
428MIME-Version: 1.0
429Content-Type: text/plain; charset=UTF-8
430Content-Transfer-Encoding: 8bit
431
432arch/arm config files were slimmed down using a python script
433(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
434
435Do the same for ia64 so we can have sleek & trim looking
436...
437------------
438
439Typically it will be placed in a MUA's drafts folder, edited to add
440timely commentary that should not go in the changelog after the three
441dashes, and then sent as a message whose body, in our example, starts
442with "arch/arm config files were...". On the receiving end, readers
443can save interesting patches in a UNIX mailbox and apply them with
444linkgit:git-am[1].
445
446When a patch is part of an ongoing discussion, the patch generated by
447'git format-patch' can be tweaked to take advantage of the 'git am
448--scissors' feature. After your response to the discussion comes a
449line that consists solely of "`-- >8 --`" (scissors and perforation),
450followed by the patch with unnecessary header fields removed:
451
452------------
453...
454> So we should do such-and-such.
455
456Makes sense to me. How about this patch?
457
458-- >8 --
459Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
460
461arch/arm config files were slimmed down using a python script
462...
463------------
464
465When sending a patch this way, most often you are sending your own
466patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you
467should omit `From:` and `Date:` lines from the patch file. The patch
468title is likely to be different from the subject of the discussion the
469patch is in response to, so it is likely that you would want to keep
470the Subject: line, like the example above.
471
Jonathan Nieder57756162011-04-14 21:24:01 -0500472Checking for patch corruption
473~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
474Many mailers if not set up properly will corrupt whitespace. Here are
475two common types of corruption:
476
477* Empty context lines that do not have _any_ whitespace.
478
479* Non-empty context lines that have one extra whitespace at the
480 beginning.
481
482One way to test if your MUA is set up correctly is:
483
484* Send the patch to yourself, exactly the way you would, except
485 with To: and Cc: lines that do not contain the list and
486 maintainer address.
487
488* Save that patch to a file in UNIX mailbox format. Call it a.patch,
489 say.
490
491* Apply it:
492
493 $ git fetch <project> master:test-apply
Nguyễn Thái Ngọc Duy328c6cb2019-03-29 17:39:19 +0700494 $ git switch test-apply
Nguyễn Thái Ngọc Duy80f537f2019-04-25 16:45:58 +0700495 $ git restore --source=HEAD --staged --worktree :/
Jonathan Nieder57756162011-04-14 21:24:01 -0500496 $ git am a.patch
497
498If it does not apply correctly, there can be various reasons.
499
500* The patch itself does not apply cleanly. That is _bad_ but
501 does not have much to do with your MUA. You might want to rebase
502 the patch with linkgit:git-rebase[1] before regenerating it in
503 this case.
504
505* The MUA corrupted your patch; "am" would complain that
506 the patch does not apply. Look in the .git/rebase-apply/ subdirectory and
507 see what 'patch' file contains and check for the common
508 corruption patterns mentioned above.
509
510* While at it, check the 'info' and 'final-commit' files as well.
511 If what is in 'final-commit' is not exactly what you would want to
512 see in the commit log message, it is very likely that the
513 receiver would end up hand editing the log message when applying
514 your patch. Things like "Hi, this is my first patch.\n" in the
515 patch e-mail should come after the three-dash line that signals
516 the end of the commit message.
517
Jonathan Niederdc531512011-04-14 21:28:06 -0500518MUA-SPECIFIC HINTS
519------------------
520Here are some hints on how to successfully submit patches inline using
521various mailers.
522
Jonathan Nieder36c10e62011-04-14 21:33:57 -0500523GMail
524~~~~~
525GMail does not have any way to turn off line wrapping in the web
526interface, so it will mangle any emails that you send. You can however
527use "git send-email" and send your patches through the GMail SMTP server, or
528use any IMAP email client to connect to the google IMAP server and forward
529the emails through that.
530
531For hints on using 'git send-email' to send your patches through the
532GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1].
533
534For hints on submission using the IMAP interface, see the EXAMPLE
535section of linkgit:git-imap-send[1].
536
Jonathan Niederdc531512011-04-14 21:28:06 -0500537Thunderbird
538~~~~~~~~~~~
539By default, Thunderbird will both wrap emails as well as flag
540them as being 'format=flowed', both of which will make the
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100541resulting email unusable by Git.
Jonathan Niederdc531512011-04-14 21:28:06 -0500542
Johannes Sixtb8959602011-04-18 08:31:16 +0200543There are three different approaches: use an add-on to turn off line wraps,
544configure Thunderbird to not mangle patches, or use
Jonathan Niederdc531512011-04-14 21:28:06 -0500545an external editor to keep Thunderbird from mangling the patches.
546
Johannes Sixtb8959602011-04-18 08:31:16 +0200547Approach #1 (add-on)
548^^^^^^^^^^^^^^^^^^^^
549
550Install the Toggle Word Wrap add-on that is available from
551https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/
552It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu
553that you can tick off. Now you can compose the message as you otherwise do
554(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to
555insert line breaks manually in any text that you type.
556
557Approach #2 (configuration)
Jonathan Niederdc531512011-04-14 21:28:06 -0500558^^^^^^^^^^^^^^^^^^^^^^^^^^^
559Three steps:
560
5611. Configure your mail server composition as plain text:
562 Edit...Account Settings...Composition & Addressing,
563 uncheck "Compose Messages in HTML".
564
5652. Configure your general composition window to not wrap.
566+
567In Thunderbird 2:
568Edit..Preferences..Composition, wrap plain text messages at 0
569+
570In Thunderbird 3:
571Edit..Preferences..Advanced..Config Editor. Search for
572"mail.wrap_long_lines".
Ramsay Jonesf7376842013-10-06 21:51:31 +0100573Toggle it to make sure it is set to `false`. Also, search for
574"mailnews.wraplength" and set the value to 0.
Jonathan Niederdc531512011-04-14 21:28:06 -0500575
5763. Disable the use of format=flowed:
Jean-Noël Avilaba170512019-01-22 21:16:35 +0100577 Edit..Preferences..Advanced..Config Editor. Search for
578 "mailnews.send_plaintext_flowed".
579 Toggle it to make sure it is set to `false`.
Jonathan Niederdc531512011-04-14 21:28:06 -0500580
581After that is done, you should be able to compose email as you
582otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc),
583and the patches will not be mangled.
584
Johannes Sixtb8959602011-04-18 08:31:16 +0200585Approach #3 (external editor)
Jonathan Niederdc531512011-04-14 21:28:06 -0500586^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
587
588The following Thunderbird extensions are needed:
589AboutConfig from http://aboutconfig.mozdev.org/ and
590External Editor from http://globs.org/articles.php?lng=en&pg=8
591
5921. Prepare the patch as a text file using your method of choice.
593
5942. Before opening a compose window, use Edit->Account Settings to
595 uncheck the "Compose messages in HTML format" setting in the
596 "Composition & Addressing" panel of the account to be used to
597 send the patch.
598
5993. In the main Thunderbird window, 'before' you open the compose
600 window for the patch, use Tools->about:config to set the
601 following to the indicated values:
602+
603----------
604 mailnews.send_plaintext_flowed => false
605 mailnews.wraplength => 0
606----------
607
6084. Open a compose window and click the external editor icon.
609
6105. In the external editor window, read in the patch file and exit
611 the editor normally.
612
613Side note: it may be possible to do step 2 with
614about:config and the following settings but no one's tried yet.
615
616----------
617 mail.html_compose => false
618 mail.identity.default.compose_html => false
619 mail.identity.id?.compose_html => false
620----------
621
622There is a script in contrib/thunderbird-patch-inline which can help
623you include patches with Thunderbird in an easy way. To use it, do the
624steps above and then use the script as the external editor.
625
Jonathan Nieder967ab8e2011-04-14 21:32:55 -0500626KMail
627~~~~~
628This should help you to submit patches inline using KMail.
629
6301. Prepare the patch as a text file.
631
6322. Click on New Mail.
633
6343. Go under "Options" in the Composer window and be sure that
635 "Word wrap" is not set.
636
6374. Use Message -> Insert file... and insert the patch.
638
6395. Back in the compose window: add whatever other text you wish to the
640 message, complete the addressing and subject fields, and press send.
641
Xiaolong Yefa2ab862016-04-26 15:51:22 +0800642BASE TREE INFORMATION
643---------------------
644
645The base tree information block is used for maintainers or third party
646testers to know the exact state the patch series applies to. It consists
647of the 'base commit', which is a well-known commit that is part of the
648stable part of the project history everybody else works off of, and zero
649or more 'prerequisite patches', which are well-known patches in flight
650that is not yet part of the 'base commit' that need to be applied on top
651of 'base commit' in topological order before the patches can be applied.
652
653The 'base commit' is shown as "base-commit: " followed by the 40-hex of
654the commit object name. A 'prerequisite patch' is shown as
655"prerequisite-patch-id: " followed by the 40-hex 'patch id', which can
656be obtained by passing the patch through the `git patch-id --stable`
657command.
658
659Imagine that on top of the public commit P, you applied well-known
660patches X, Y and Z from somebody else, and then built your three-patch
661series A, B, C, the history would be like:
662
663................................................
664---P---X---Y---Z---A---B---C
665................................................
666
667With `git format-patch --base=P -3 C` (or variants thereof, e.g. with
Giuseppe Bilotta7ba1cee2017-04-18 00:32:53 +0200668`--cover-letter` or using `Z..C` instead of `-3 C` to specify the
Xiaolong Yefa2ab862016-04-26 15:51:22 +0800669range), the base tree information block is shown at the end of the
670first message the command outputs (either the first patch, or the
671cover letter), like this:
672
673------------
674base-commit: P
675prerequisite-patch-id: X
676prerequisite-patch-id: Y
677prerequisite-patch-id: Z
678------------
679
680For non-linear topology, such as
681
682................................................
683---P---X---A---M---C
684 \ /
685 Y---Z---B
686................................................
687
688You can also use `git format-patch --base=P -3 C` to generate patches
689for A, B and C, and the identifiers for P, X, Y, Z are appended at the
690end of the first message.
Jonathan Niedere0d48272011-04-14 21:22:02 -0500691
Xiaolong Ye3de66512016-04-26 15:51:23 +0800692If set `--base=auto` in cmdline, it will track base commit automatically,
693the base commit will be the merge base of tip commit of the remote-tracking
694branch and revision-range specified in cmdline.
695For a local branch, you need to track a remote branch by `git branch
696--set-upstream-to` before using this option.
697
Junio C Hamano28ffb892005-11-05 02:55:18 -0800698EXAMPLES
699--------
700
Christian Couder921177f2008-05-07 06:29:28 +0200701* Extract commits between revisions R1 and R2, and apply them on top of
Jean-Noël Avilaba170512019-01-22 21:16:35 +0100702 the current branch using 'git am' to cherry-pick them:
Christian Couder921177f2008-05-07 06:29:28 +0200703+
704------------
Jonathan Nieder467c0192008-07-03 00:28:15 -0500705$ git format-patch -k --stdout R1..R2 | git am -3 -k
Christian Couder921177f2008-05-07 06:29:28 +0200706------------
Junio C Hamano28ffb892005-11-05 02:55:18 -0800707
Christian Couder921177f2008-05-07 06:29:28 +0200708* Extract all commits which are in the current branch but not in the
Jean-Noël Avilaba170512019-01-22 21:16:35 +0100709 origin branch:
Christian Couder921177f2008-05-07 06:29:28 +0200710+
711------------
712$ git format-patch origin
713------------
714+
715For each commit a separate file is created in the current directory.
Junio C Hamano28ffb892005-11-05 02:55:18 -0800716
Christian Couder921177f2008-05-07 06:29:28 +0200717* Extract all commits that lead to 'origin' since the inception of the
Jean-Noël Avilaba170512019-01-22 21:16:35 +0100718 project:
Christian Couder921177f2008-05-07 06:29:28 +0200719+
720------------
Jonathan Nieder9c67c752008-07-02 23:47:05 -0500721$ git format-patch --root origin
Christian Couder921177f2008-05-07 06:29:28 +0200722------------
Junio C Hamano8a1d0762007-08-28 00:38:48 -0700723
Christian Couder921177f2008-05-07 06:29:28 +0200724* The same as the previous one:
725+
726------------
727$ git format-patch -M -B origin
728------------
729+
730Additionally, it detects and handles renames and complete rewrites
731intelligently to produce a renaming patch. A renaming patch reduces
Stephen Boyd50710ce2009-04-23 09:16:52 -0700732the amount of text output, and generally makes it easier to review.
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100733Note that non-Git "patch" programs won't understand renaming patches, so
734use it only when you know the recipient uses Git to apply your patch.
Junio C Hamano803f4982005-12-13 01:54:15 -0800735
Christian Couder921177f2008-05-07 06:29:28 +0200736* Extract three topmost commits from the current branch and format them
Jean-Noël Avilaba170512019-01-22 21:16:35 +0100737 as e-mailable patches:
Christian Couder921177f2008-05-07 06:29:28 +0200738+
739------------
740$ git format-patch -3
741------------
Junio C Hamano28ffb892005-11-05 02:55:18 -0800742
Jeff King8e0601f2021-05-01 10:13:24 -0400743CAVEATS
744-------
745
746Note that `format-patch` will omit merge commits from the output, even
747if they are part of the requested range. A simple "patch" does not
748include enough information for the receiving end to reproduce the same
749merge commit.
750
Junio C Hamano56ae8df2008-05-28 16:55:27 -0700751SEE ALSO
Junio C Hamano28ffb892005-11-05 02:55:18 -0800752--------
Dan McGee5162e692007-12-29 00:20:38 -0600753linkgit:git-am[1], linkgit:git-send-email[1]
Junio C Hamano28ffb892005-11-05 02:55:18 -0800754
Junio C Hamano7fc9d692005-08-23 01:49:47 -0700755GIT
756---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200757Part of the linkgit:git[1] suite