diff options
Diffstat (limited to 'Documentation/git-format-patch.txt')
| -rw-r--r-- | Documentation/git-format-patch.txt | 68 |
1 files changed, 40 insertions, 28 deletions
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 687e667598..c8c81e8437 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -13,12 +13,13 @@ SYNOPSIS [--no-thread | --thread[=<style>]] [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] + [--signature=<signature> | --no-signature] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] - [--cc=<email>] + [--to=<email>] [--cc=<email>] [--cover-letter] [<common diff options>] [ <since> | <revision range> ] @@ -29,7 +30,7 @@ DESCRIPTION Prepare each commit with its patch in one file per commit, formatted to resemble UNIX mailbox format. The output of this command is convenient for e-mail submission or -for use with 'git-am'. +for use with 'git am'. There are two ways to specify which commits to operate on. @@ -43,28 +44,28 @@ There are two ways to specify which commits to operate on. The first rule takes precedence in the case of a single <commit>. To apply the second rule, i.e., format everything since the beginning of -history up until <commit>, use the '\--root' option: "git format-patch -\--root <commit>". If you want to format only <commit> itself, you -can do this with "git format-patch -1 <commit>". +history up until <commit>, use the '\--root' option: `git format-patch +\--root <commit>`. If you want to format only <commit> itself, you +can do this with `git format-patch -1 <commit>`. By default, each output file is numbered sequentially from 1, and uses the first line of the commit message (massaged for pathname safety) as -the filename. With the --numbered-files option, the output file names +the filename. With the `--numbered-files` option, the output file names will only be numbers, without the first line of the commit appended. The names of the output files are printed to standard -output, unless the --stdout option is specified. +output, unless the `--stdout` option is specified. -If -o is specified, output files are created in <dir>. Otherwise +If `-o` is specified, output files are created in <dir>. Otherwise they are created in the current working directory. By default, the subject of a single patch is "[PATCH] First Line" and the subject when multiple patches are output is "[PATCH n/m] First -Line". To force 1/1 to be added for a single patch, use -n. To omit -patch numbers from the subject, use -N +Line". To force 1/1 to be added for a single patch, use `-n`. To omit +patch numbers from the subject, use `-N`. -If given --thread, 'git-format-patch' will generate In-Reply-To and -References headers to make the second and subsequent patch mails appear -as replies to the first mail; this also generates a Message-Id header to +If given `--thread`, `git-format-patch` will generate `In-Reply-To` and +`References` headers to make the second and subsequent patch mails appear +as replies to the first mail; this also generates a `Message-Id` header to reference. OPTIONS @@ -112,7 +113,7 @@ include::diff-options.txt[] --attach[=<boundary>]:: Create multipart/mixed attachment, the first part of which is the commit message and the patch itself in the - second part, with "Content-Disposition: attachment". + second part, with `Content-Disposition: attachment`. --no-attach:: Disable the creation of an attachment, overriding the @@ -121,13 +122,13 @@ include::diff-options.txt[] --inline[=<boundary>]:: Create multipart/mixed attachment, the first part of which is the commit message and the patch itself in the - second part, with "Content-Disposition: inline". + second part, with `Content-Disposition: inline`. --thread[=<style>]:: --no-thread:: - Controls addition of In-Reply-To and References headers to + Controls addition of `In-Reply-To` and `References` headers to make the second and subsequent mails appear as replies to the - first. Also controls generation of the Message-Id header to + first. Also controls generation of the `Message-Id` header to reference. + The optional <style> argument can be either `shallow` or `deep`. @@ -136,16 +137,16 @@ series, where the head is chosen from the cover letter, the `\--in-reply-to`, and the first patch mail, in this order. 'deep' threading makes every mail a reply to the previous one. + -The default is --no-thread, unless the 'format.thread' configuration -is set. If --thread is specified without a style, it defaults to the +The default is `--no-thread`, unless the 'format.thread' configuration +is set. If `--thread` is specified without a style, it defaults to the style specified by 'format.thread' if any, or else `shallow`. + Beware that the default for 'git send-email' is to thread emails -itself. If you want 'git format-patch' to take care of hreading, you -will want to ensure that threading is disabled for 'git send-email'. +itself. If you want `git format-patch` to take care of threading, you +will want to ensure that threading is disabled for `git send-email`. --in-reply-to=Message-Id:: - Make the first mail (or all the mails with --no-thread) appear as a + Make the first mail (or all the mails with `--no-thread`) appear as a reply to the given Message-Id, which avoids breaking threads to provide a new patch series. @@ -160,22 +161,32 @@ will want to ensure that threading is disabled for 'git send-email'. Instead of the standard '[PATCH]' prefix in the subject line, instead use '[<Subject-Prefix>]'. This allows for useful naming of a patch series, and can be - combined with the --numbered option. + combined with the `--numbered` option. + +--to=<email>:: + Add a `To:` header to the email headers. This is in addition + to any configured headers, and may be used multiple times. --cc=<email>:: - Add a "Cc:" header to the email headers. This is in addition + Add a `Cc:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. --add-header=<header>:: Add an arbitrary header to the email headers. This is in addition to any configured headers, and may be used multiple times. - For example, --add-header="Organization: git-foo" + For example, `--add-header="Organization: git-foo"` --cover-letter:: In addition to the patches, generate a cover letter file containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--[no]-signature=<signature>:: + Add a signature to each message produced. Per RFC 3676 the signature + is separated from the body by a line with '-- ' on it. If the + signature option is omitted the signature defaults to the git version + number. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is @@ -202,8 +213,8 @@ CONFIGURATION ------------- You can specify extra mail header lines to be added to each message, defaults for the subject prefix and file suffix, number patches when -outputting more than one patch, add "Cc:" headers, configure attachments, -and sign off patches with configuration variables. +outputting more than one patch, add "To" or "Cc:" headers, configure +attachments, and sign off patches with configuration variables. ------------ [format] @@ -211,6 +222,7 @@ and sign off patches with configuration variables. subjectprefix = CHANGE suffix = .txt numbered = auto + to = <email> cc = <email> attach [ = mime-boundary-string ] signoff = true @@ -221,7 +233,7 @@ EXAMPLES -------- * Extract commits between revisions R1 and R2, and apply them on top of -the current branch using 'git-am' to cherry-pick them: +the current branch using 'git am' to cherry-pick them: + ------------ $ git format-patch -k --stdout R1..R2 | git am -3 -k |