diff options
Diffstat (limited to 'Documentation/git-format-patch.txt')
| -rw-r--r-- | Documentation/git-format-patch.txt | 268 |
1 files changed, 260 insertions, 8 deletions
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index a5525e9aa8..259dce4994 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [--to=<email>] [--cc=<email>] - [--cover-letter] + [--cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ] @@ -45,7 +45,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 -\--root <commit>`. If you want to format only <commit> itself, you +--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 @@ -58,10 +58,13 @@ 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. -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`. +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 +line (see the DISCUSSION section of linkgit:git-commit[1]). + +When multiple patches are output, the subject prefix will instead be +"[PATCH n/m] ". 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 @@ -134,7 +137,7 @@ include::diff-options.txt[] The optional <style> argument can be either `shallow` or `deep`. 'shallow' threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the -`\--in-reply-to`, and the first patch mail, in this order. 'deep' +`--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 @@ -166,21 +169,40 @@ will want to ensure that threading is disabled for `git send-email`. --to=<email>:: Add a `To:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. + The negated form `--no-to` discards all `To:` headers added so + far (from config or command line). --cc=<email>:: Add a `Cc:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. + The negated form `--no-cc` discards all `Cc:` headers added so + far (from config or command line). --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"`. + The negated form `--no-add-header` discards *all* (`To:`, + `Cc:`, and custom) headers added so far from config or command + line. --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. +--notes[=<ref>]:: + Append the notes (see linkgit:git-notes[1]) for the commit + after the three-dash line. ++ +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 +of the patch series (but see the discussion of the `notes.rewrite` +configuration options in linkgit:git-notes[1] to use this workflow). + --[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 @@ -196,6 +218,9 @@ will want to ensure that threading is disabled for `git send-email`. 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`. +--quiet:: + Do not print the names of the generated files to standard output. + --no-binary:: Do not output contents of changes in binary files, instead display a notice that those files changed. Patches generated @@ -229,6 +254,233 @@ attachments, and sign off patches with configuration variables. ------------ +DISCUSSION +---------- + +The patch produced by 'git format-patch' is in UNIX mailbox format, +with a fixed "magic" time stamp to indicate that the file is output +from format-patch rather than a real mailbox, like so: + +------------ +From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001 +From: Tony Luck <tony.luck@intel.com> +Date: Tue, 13 Jul 2010 11:42:54 -0700 +Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?= + =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?= +MIME-Version: 1.0 +Content-Type: text/plain; charset=UTF-8 +Content-Transfer-Encoding: 8bit + +arch/arm config files were slimmed down using a python script +(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment) + +Do the same for ia64 so we can have sleek & trim looking +... +------------ + +Typically it will be placed in a MUA's drafts folder, edited to add +timely commentary that should not go in the changelog after the three +dashes, and then sent as a message whose body, in our example, starts +with "arch/arm config files were...". On the receiving end, readers +can save interesting patches in a UNIX mailbox and apply them with +linkgit:git-am[1]. + +When a patch is part of an ongoing discussion, the patch generated by +'git format-patch' can be tweaked to take advantage of the 'git am +--scissors' feature. After your response to the discussion comes a +line that consists solely of "`-- >8 --`" (scissors and perforation), +followed by the patch with unnecessary header fields removed: + +------------ +... +> So we should do such-and-such. + +Makes sense to me. How about this patch? + +-- >8 -- +Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet + +arch/arm config files were slimmed down using a python script +... +------------ + +When sending a patch this way, most often you are sending your own +patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you +should omit `From:` and `Date:` lines from the patch file. The patch +title is likely to be different from the subject of the discussion the +patch is in response to, so it is likely that you would want to keep +the Subject: line, like the example above. + +Checking for patch corruption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Many mailers if not set up properly will corrupt whitespace. Here are +two common types of corruption: + +* Empty context lines that do not have _any_ whitespace. + +* Non-empty context lines that have one extra whitespace at the + beginning. + +One way to test if your MUA is set up correctly is: + +* Send the patch to yourself, exactly the way you would, except + with To: and Cc: lines that do not contain the list and + maintainer address. + +* Save that patch to a file in UNIX mailbox format. Call it a.patch, + say. + +* Apply it: + + $ git fetch <project> master:test-apply + $ git checkout test-apply + $ git reset --hard + $ git am a.patch + +If it does not apply correctly, there can be various reasons. + +* The patch itself does not apply cleanly. That is _bad_ but + does not have much to do with your MUA. You might want to rebase + the patch with linkgit:git-rebase[1] before regenerating it in + this case. + +* The MUA corrupted your patch; "am" would complain that + the patch does not apply. Look in the .git/rebase-apply/ subdirectory and + see what 'patch' file contains and check for the common + corruption patterns mentioned above. + +* While at it, check the 'info' and 'final-commit' files as well. + If what is in 'final-commit' is not exactly what you would want to + see in the commit log message, it is very likely that the + receiver would end up hand editing the log message when applying + your patch. Things like "Hi, this is my first patch.\n" in the + patch e-mail should come after the three-dash line that signals + the end of the commit message. + +MUA-SPECIFIC HINTS +------------------ +Here are some hints on how to successfully submit patches inline using +various mailers. + +GMail +~~~~~ +GMail does not have any way to turn off line wrapping in the web +interface, so it will mangle any emails that you send. You can however +use "git send-email" and send your patches through the GMail SMTP server, or +use any IMAP email client to connect to the google IMAP server and forward +the emails through that. + +For hints on using 'git send-email' to send your patches through the +GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1]. + +For hints on submission using the IMAP interface, see the EXAMPLE +section of linkgit:git-imap-send[1]. + +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. + +There are three different approaches: use an add-on to turn off line wraps, +configure Thunderbird to not mangle patches, or use +an external editor to keep Thunderbird from mangling the patches. + +Approach #1 (add-on) +^^^^^^^^^^^^^^^^^^^^ + +Install the Toggle Word Wrap add-on that is available from +https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ +It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu +that you can tick off. Now you can compose the message as you otherwise do +(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to +insert line breaks manually in any text that you type. + +Approach #2 (configuration) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Three steps: + +1. Configure your mail server composition as plain text: + Edit...Account Settings...Composition & Addressing, + uncheck "Compose Messages in HTML". + +2. Configure your general composition window to not wrap. ++ +In Thunderbird 2: +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`. + +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`. + +After that is done, you should be able to compose email as you +otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc), +and the patches will not be mangled. + +Approach #3 (external editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following Thunderbird extensions are needed: +AboutConfig from http://aboutconfig.mozdev.org/ and +External Editor from http://globs.org/articles.php?lng=en&pg=8 + +1. Prepare the patch as a text file using your method of choice. + +2. Before opening a compose window, use Edit->Account Settings to + uncheck the "Compose messages in HTML format" setting in the + "Composition & Addressing" panel of the account to be used to + send the patch. + +3. In the main Thunderbird window, 'before' you open the compose + window for the patch, use Tools->about:config to set the + following to the indicated values: ++ +---------- + mailnews.send_plaintext_flowed => false + mailnews.wraplength => 0 +---------- + +4. Open a compose window and click the external editor icon. + +5. In the external editor window, read in the patch file and exit + the editor normally. + +Side note: it may be possible to do step 2 with +about:config and the following settings but no one's tried yet. + +---------- + mail.html_compose => false + mail.identity.default.compose_html => false + mail.identity.id?.compose_html => false +---------- + +There is a script in contrib/thunderbird-patch-inline which can help +you include patches with Thunderbird in an easy way. To use it, do the +steps above and then use the script as the external editor. + +KMail +~~~~~ +This should help you to submit patches inline using KMail. + +1. Prepare the patch as a text file. + +2. Click on New Mail. + +3. Go under "Options" in the Composer window and be sure that + "Word wrap" is not set. + +4. Use Message -> Insert file... and insert the patch. + +5. Back in the compose window: add whatever other text you wish to the + message, complete the addressing and subject fields, and press send. + + EXAMPLES -------- |