diff options
Diffstat (limited to 'Documentation/git-format-patch.txt')
| -rw-r--r-- | Documentation/git-format-patch.txt | 294 |
1 files changed, 258 insertions, 36 deletions
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 259dce4994..fe2f69d36e 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -14,24 +14,50 @@ SYNOPSIS [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] [--signature=<signature> | --no-signature] + [--signature-file=<file>] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] - [--in-reply-to=Message-Id] [--suffix=.<sfx>] + [--in-reply-to=<message id>] [--suffix=.<sfx>] [--ignore-if-in-upstream] - [--subject-prefix=Subject-Prefix] + [--cover-from-description=<mode>] + [--rfc] [--subject-prefix=<subject prefix>] + [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] [--notes[=<ref>]] + [--[no-]cover-letter] [--quiet] + [--[no-]encode-email-headers] + [--no-notes | --notes[=<ref>]] + [--interdiff=<previous>] + [--range-diff=<previous> [--creation-factor=<percent>]] + [--filename-max-length=<n>] + [--progress] [<common diff options>] [ <since> | <revision range> ] DESCRIPTION ----------- -Prepare each commit with its patch in -one file per commit, formatted to resemble UNIX mailbox format. +Prepare each non-merge commit with its "patch" in +one "message" per commit, formatted to resemble a UNIX mailbox. The output of this command is convenient for e-mail submission or for use with 'git am'. +A "message" generated by the command consists of three parts: + +* A brief metadata header that begins with `From <commit>` + with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs + like "file(1)" to recognize that the file is an output from this + command, fields that record the author identity, the author date, + and the title of the change (taken from the first paragraph of the + commit log message). + +* The second and subsequent paragraphs of the commit log message. + +* The "patch", which is the "diff -p --stat" output (see + linkgit:git-diff[1]) between the commit and its parent. + +The log message and the patch is separated by a line with a +three-dash line. + There are two ways to specify which commits to operate on. 1. A single commit, <since>, specifies that the commits leading @@ -44,7 +70,7 @@ 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 +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>`. @@ -56,7 +82,12 @@ The names of the output files are printed to standard output, unless the `--stdout` option is specified. If `-o` is specified, output files are created in <dir>. Otherwise -they are created in the current working directory. +they are created in the current working directory. The default path +can be set with the `format.outputDirectory` configuration option. +The `-o` option takes precedence over `format.outputDirectory`. +To store patches in the current working directory even when +`format.outputDirectory` points elsewhere, use `-o .`. All directory +components will be created. By default, the subject of a single patch is "[PATCH] " followed by the concatenation of lines from the commit message up to the first blank @@ -106,8 +137,9 @@ include::diff-options.txt[] -s:: --signoff:: - Add `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by` trailer to the commit message, using the committer identity of yourself. + See the signoff option in linkgit:git-commit[1] for more information. --stdout:: Print all commits to the standard output in mbox format, @@ -140,17 +172,17 @@ 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 +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`. +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 threading, you will want to ensure that threading is disabled for `git send-email`. ---in-reply-to=Message-Id:: +--in-reply-to=<message id>:: 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 + reply to the given <message id>, which avoids breaking threads to provide a new patch series. --ignore-if-in-upstream:: @@ -160,12 +192,58 @@ will want to ensure that threading is disabled for `git send-email`. patches being generated, and any patch that matches is ignored. ---subject-prefix=<Subject-Prefix>:: +--cover-from-description=<mode>:: + Controls which parts of the cover letter will be automatically + populated using the branch's description. ++ +If `<mode>` is `message` or `default`, the cover letter subject will be +populated with placeholder text. The body of the cover letter will be +populated with the branch's description. This is the default mode when +no configuration nor command line option is specified. ++ +If `<mode>` is `subject`, the first paragraph of the branch description will +populate the cover letter subject. The remainder of the description will +populate the body of the cover letter. ++ +If `<mode>` is `auto`, if the first paragraph of the branch description +is greater than 100 bytes, then the mode will be `message`, otherwise +`subject` will be used. ++ +If `<mode>` is `none`, both the cover letter subject and body will be +populated with placeholder text. + +--subject-prefix=<subject prefix>:: Instead of the standard '[PATCH]' prefix in the subject - line, instead use '[<Subject-Prefix>]'. This + line, instead use '[<subject prefix>]'. This allows for useful naming of a patch series, and can be combined with the `--numbered` option. +--filename-max-length=<n>:: + Instead of the standard 64 bytes, chomp the generated output + filenames at around '<n>' bytes (too short a value will be + silently raised to a reasonable length). Defaults to the + value of the `format.filenameMaxLength` configuration + variable, or 64 if unconfigured. + +--rfc:: + Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For + Comments"; use this when sending an experimental patch for + discussion rather than application. + +-v <n>:: +--reroll-count=<n>:: + Mark the series as the <n>-th iteration of the topic. The + output filenames have `v<n>` prepended to them, and the + subject prefix ("PATCH" by default, but configurable via the + `--subject-prefix` option) has ` v<n>` appended to it. E.g. + `--reroll-count=4` may produce `v4-0001-add-makefile.patch` + file that has "Subject: [PATCH v4 1/20] Add makefile" in it. + `<n>` does not have to be an integer (e.g. "--reroll-count=4.4", + or "--reroll-count=4rev2" are allowed), but the downside of + using such a reroll-count is that the range-diff/interdiff + with the previous version does not state exactly which + version the new interation is compared against. + --to=<email>:: Add a `To:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. @@ -178,6 +256,21 @@ will want to ensure that threading is disabled for `git send-email`. The negated form `--no-cc` discards all `Cc:` headers added so far (from config or command line). +--from:: +--from=<ident>:: + Use `ident` in the `From:` header of each commit email. If the + author ident of the commit is not textually identical to the + provided `ident`, place a `From:` header in the body of the + message with the original author. If no `ident` is given, use + the committer ident. ++ +Note that this option is only useful if you are actually sending the +emails and want to identify yourself as the sender, but retain the +original author (and `git am` will correctly pick up the in-body +header). Note also that `git send-email` already handles this +transformation for you, and this option should not be used if you are +feeding the result to `git send-email`. + --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. @@ -186,12 +279,52 @@ will want to ensure that threading is disabled for `git send-email`. `Cc:`, and custom) headers added so far from config or command line. ---cover-letter:: +--[no-]cover-letter:: In addition to the patches, generate a cover letter file - containing the shortlog and the overall diffstat. You can + containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--encode-email-headers:: +--no-encode-email-headers:: + Encode email headers that have non-ASCII characters with + "Q-encoding" (described in RFC 2047), instead of outputting the + headers verbatim. Defaults to the value of the + `format.encodeEmailHeaders` configuration variable. + +--interdiff=<previous>:: + As a reviewer aid, insert an interdiff into the cover letter, + or as commentary of the lone patch of a 1-patch series, showing + the differences between the previous version of the patch series and + the series currently being formatted. `previous` is a single revision + naming the tip of the previous series which shares a common base with + the series being formatted (for example `git format-patch + --cover-letter --interdiff=feature/v1 -3 feature/v2`). + +--range-diff=<previous>:: + As a reviewer aid, insert a range-diff (see linkgit:git-range-diff[1]) + into the cover letter, or as commentary of the lone patch of a + 1-patch series, showing the differences between the previous + version of the patch series and the series currently being formatted. + `previous` can be a single revision naming the tip of the previous + series if it shares a common base with the series being formatted (for + example `git format-patch --cover-letter --range-diff=feature/v1 -3 + feature/v2`), or a revision range if the two versions of the series are + disjoint (for example `git format-patch --cover-letter + --range-diff=feature/v1~3..feature/v1 -3 feature/v2`). ++ +Note that diff options passed to the command affect how the primary +product of `format-patch` is generated, and they are not passed to +the underlying `range-diff` machinery used to generate the cover-letter +material (this may change in the future). + +--creation-factor=<percent>:: + Used with `--range-diff`, tweak the heuristic which matches up commits + between the previous and current series of patches by adjusting the + creation/deletion cost fudge factor. See linkgit:git-range-diff[1]) + for details. + --notes[=<ref>]:: +--no-notes:: Append the notes (see linkgit:git-notes[1]) for the commit after the three-dash line. + @@ -199,16 +332,22 @@ The expected use case of this is to write supporting explanation for the commit that does not belong to the commit log message proper, and include it with the patch submission. While one can simply write these explanations after `format-patch` has run but before sending, -keeping them as git notes allows them to be maintained between versions +keeping them as Git notes allows them to be maintained between versions of the patch series (but see the discussion of the `notes.rewrite` configuration options in linkgit:git-notes[1] to use this workflow). ++ +The default is `--no-notes`, unless the `format.notes` configuration is +set. ---[no]-signature=<signature>:: +--[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 + signature option is omitted the signature defaults to the Git version number. +--signature-file=<file>:: + Works just like --signature except the signature is read from a file. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is @@ -218,6 +357,7 @@ configuration options in linkgit:git-notes[1] to use this workflow). Note that the leading character does not have to be a dot; for example, you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. +-q:: --quiet:: Do not print the names of the generated files to standard output. @@ -227,6 +367,17 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. using this option cannot be applied properly, but they are still useful for code review. +--zero-commit:: + Output an all-zero hash in each patch's From header instead + of the hash of the commit. + +--[no-]base[=<commit>]:: + Record the base tree information to identify the state the + patch series applies to. See the BASE TREE INFORMATION section + below for details. If <commit> is "auto", a base commit is + automatically chosen. The `--no-base` option overrides a + `format.useAutoBase` configuration. + --root:: Treat the revision argument as a <revision range>, even if it is just a single commit (that would normally be treated as a @@ -234,23 +385,30 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. range are always formatted as creation patches, independently of this flag. +--progress:: + Show progress reports on stderr as patches are generated. + 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 "To" or "Cc:" headers, configure -attachments, and sign off patches with configuration variables. +outputting more than one patch, add "To:" or "Cc:" headers, configure +attachments, change the patch output directory, and sign off patches +with configuration variables. ------------ [format] headers = "Organization: git-foo\n" - subjectprefix = CHANGE + subjectPrefix = CHANGE suffix = .txt numbered = auto to = <email> cc = <email> attach [ = mime-boundary-string ] - signoff = true + signOff = true + outputDirectory = <directory> + coverLetter = auto + coverFromDescription = auto ------------ @@ -333,8 +491,8 @@ One way to test if your MUA is set up correctly is: * Apply it: $ git fetch <project> master:test-apply - $ git checkout test-apply - $ git reset --hard + $ git switch test-apply + $ git restore --source=HEAD --staged --worktree :/ $ git am a.patch If it does not apply correctly, there can be various reasons. @@ -380,7 +538,7 @@ Thunderbird ~~~~~~~~~~~ By default, Thunderbird will both wrap emails as well as flag them as being 'format=flowed', both of which will make the -resulting email unusable by git. +resulting email unusable by Git. There are three different approaches: use an add-on to turn off line wraps, configure Thunderbird to not mangle patches, or use @@ -412,12 +570,13 @@ Edit..Preferences..Composition, wrap plain text messages at 0 In Thunderbird 3: Edit..Preferences..Advanced..Config Editor. Search for "mail.wrap_long_lines". -Toggle it to make sure it is set to `false`. +Toggle it to make sure it is set to `false`. Also, search for +"mailnews.wraplength" and set the value to 0. 3. Disable the use of format=flowed: -Edit..Preferences..Advanced..Config Editor. Search for -"mailnews.send_plaintext_flowed". -Toggle it to make sure it is set to `false`. + Edit..Preferences..Advanced..Config Editor. Search for + "mailnews.send_plaintext_flowed". + Toggle it to make sure it is set to `false`. After that is done, you should be able to compose email as you otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc), @@ -480,19 +639,74 @@ This should help you to submit patches inline using KMail. 5. Back in the compose window: add whatever other text you wish to the message, complete the addressing and subject fields, and press send. +BASE TREE INFORMATION +--------------------- + +The base tree information block is used for maintainers or third party +testers to know the exact state the patch series applies to. It consists +of the 'base commit', which is a well-known commit that is part of the +stable part of the project history everybody else works off of, and zero +or more 'prerequisite patches', which are well-known patches in flight +that is not yet part of the 'base commit' that need to be applied on top +of 'base commit' in topological order before the patches can be applied. + +The 'base commit' is shown as "base-commit: " followed by the 40-hex of +the commit object name. A 'prerequisite patch' is shown as +"prerequisite-patch-id: " followed by the 40-hex 'patch id', which can +be obtained by passing the patch through the `git patch-id --stable` +command. + +Imagine that on top of the public commit P, you applied well-known +patches X, Y and Z from somebody else, and then built your three-patch +series A, B, C, the history would be like: + +................................................ +---P---X---Y---Z---A---B---C +................................................ + +With `git format-patch --base=P -3 C` (or variants thereof, e.g. with +`--cover-letter` or using `Z..C` instead of `-3 C` to specify the +range), the base tree information block is shown at the end of the +first message the command outputs (either the first patch, or the +cover letter), like this: + +------------ +base-commit: P +prerequisite-patch-id: X +prerequisite-patch-id: Y +prerequisite-patch-id: Z +------------ + +For non-linear topology, such as + +................................................ +---P---X---A---M---C + \ / + Y---Z---B +................................................ + +You can also use `git format-patch --base=P -3 C` to generate patches +for A, B and C, and the identifiers for P, X, Y, Z are appended at the +end of the first message. + +If set `--base=auto` in cmdline, it will track base commit automatically, +the base commit will be the merge base of tip commit of the remote-tracking +branch and revision-range specified in cmdline. +For a local branch, you need to track a remote branch by `git branch +--set-upstream-to` before using this option. 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 ------------ * Extract all commits which are in the current branch but not in the -origin branch: + origin branch: + ------------ $ git format-patch origin @@ -501,7 +715,7 @@ $ git format-patch origin For each commit a separate file is created in the current directory. * Extract all commits that lead to 'origin' since the inception of the -project: + project: + ------------ $ git format-patch --root origin @@ -516,16 +730,24 @@ $ git format-patch -M -B origin Additionally, it detects and handles renames and complete rewrites intelligently to produce a renaming patch. A renaming patch reduces the amount of text output, and generally makes it easier to review. -Note that non-git "patch" programs won't understand renaming patches, so -use it only when you know the recipient uses git to apply your patch. +Note that non-Git "patch" programs won't understand renaming patches, so +use it only when you know the recipient uses Git to apply your patch. * Extract three topmost commits from the current branch and format them -as e-mailable patches: + as e-mailable patches: + ------------ $ git format-patch -3 ------------ +CAVEATS +------- + +Note that `format-patch` will omit merge commits from the output, even +if they are part of the requested range. A simple "patch" does not +include enough information for the receiving end to reproduce the same +merge commit. + SEE ALSO -------- linkgit:git-am[1], linkgit:git-send-email[1] |