* jn/format-patch-doc:
Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird
Documentation: publicize hints for sending patches with GMail
Documentation: publicize KMail hints for sending patches inline
Documentation: hints for sending patches inline with Thunderbird
Documentation: explain how to check for patch corruption
@ -289,6 +289,175 @@ title is likely to be different from the subject of the discussion the
@@ -289,6 +289,175 @@ 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
Just make sure to disable line wrapping in the email client (GMail's web
interface will wrap lines no matter what, so you need to use a real
IMAP client).
CAUTION
-------
It is still your responsibility to make sure that the email message
@ -124,6 +149,10 @@ Thunderbird in particular is known to be problematic. Thunderbird
@@ -124,6 +149,10 @@ Thunderbird in particular is known to be problematic. Thunderbird
users may wish to visit this web page for more information:
Junio C Hamano
14 years ago