1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-10-31 14:27:54 +01:00

Merge branch 'jn/format-patch-doc'

* 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
This commit is contained in:
Junio C Hamano 2011-05-04 15:51:41 -07:00
commit a588f93dcb
4 changed files with 229 additions and 195 deletions

View file

@ -344,50 +344,20 @@ MUA specific hints
Some of patches I receive or pick up from the list share common
patterns of breakage. Please make sure your MUA is set up
properly not to corrupt whitespaces. Here are two common ones
I have seen:
properly not to corrupt whitespaces.
* Empty context lines that do not have _any_ whitespace.
See the DISCUSSION section of git-format-patch(1) for hints on
checking your patch by mailing it to yourself and applying with
git-am(1).
* Non empty context lines that have one extra whitespace at the
beginning.
One test you could do yourself if your MUA is set up correctly is:
* Send the patch to yourself, exactly the way you would, except
To: and Cc: lines, which would not contain the list and
maintainer address.
* Save that patch to a file in UNIX mailbox format. Call it say
a.patch.
* Try to apply to the tip of the "master" branch from the
git.git public repository:
$ git fetch http://kernel.org/pub/scm/git/git.git 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.
* Your patch itself does not apply cleanly. That is _bad_ but
does not have much to do with your MUA. Please rebase the
patch appropriately.
* Your MUA corrupted your patch; "am" would complain that
the patch does not apply. Look at .git/rebase-apply/ subdirectory and
see what 'patch' file contains and check for the common
corruption patterns mentioned above.
* While you are at it, check what are in '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 your maintainer would end up
hand editing the log message when he applies your patch.
Things like "Hi, this is my first patch.\n", if you really
want to put in the patch e-mail, should come after the
three-dash line that signals the end of the commit message.
While you are at it, check the resulting commit log message from
a trial run of applying the patch. If what is in the resulting
commit is not exactly what you would want to see, it is very
likely that your maintainer would end up hand editing the log
message when he applies your patch. Things like "Hi, this is my
first patch.\n", if you really want to put in the patch e-mail,
should come after the three-dash line that signals the end of the
commit message.
Pine
@ -443,89 +413,10 @@ that or Gentoo did it.) So you need to set the
it.
Thunderbird
-----------
Thunderbird, KMail, GMail
-------------------------
(A Large Angry SCM)
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.
Here are some hints on how to successfully submit patches inline using
Thunderbird.
There are two different approaches. One approach is to configure
Thunderbird to not mangle patches. The second approach is to use
an external editor to keep Thunderbird from mangling the patches.
Approach #1 (configuration):
This recipe is current as of Thunderbird 2.0.0.19. 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
Edit..Preferences..Composition, wrap plain text messages at 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'.
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 should not be mangled.
Approach #2 (external editor):
This recipe appears to work with the current [*1*] Thunderbird from Suse.
The following Thunderbird extensions are needed:
AboutConfig 0.5
http://aboutconfig.mozdev.org/
External Editor 0.7.2
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. [*2*]
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.
6) Back in the compose window: Add whatever other text you wish to the
message, complete the addressing and subject fields, and press send.
7) Optionally, undo the about:config/account settings changes made in
steps 2 & 3.
[Footnotes]
*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
9.3 professional updates.
*2* It may be possible to do this with about:config and the following
settings but I haven't tried, yet.
mail.html_compose => false
mail.identity.default.compose_html => false
mail.identity.id?.compose_html => false
(Lukas Sandström)
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.
See the MUA-SPECIFIC HINTS section of git-format-patch(1).
Gnus
----
@ -540,71 +431,3 @@ characters (most notably in people's names), and also
whitespaces (fatal in patches). Running 'C-u g' to display the
message in raw form before using '|' to run the pipe can work
this problem around.
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.
Gmail
-----
GMail does not appear to have any way to turn off line wrapping in the web
interface, so this 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.
To use "git send-email" and send your patches through the GMail SMTP server,
edit ~/.gitconfig to specify your account settings:
[sendemail]
smtpencryption = tls
smtpserver = smtp.gmail.com
smtpuser = user@gmail.com
smtppass = p4ssw0rd
smtpserverport = 587
Once your commits are ready to be sent to the mailing list, run the
following commands:
$ git format-patch --cover-letter -M origin/master -o outgoing/
$ edit outgoing/0000-*
$ git send-email outgoing/*
To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your
account settings:
[imap]
folder = "[Gmail]/Drafts"
host = imaps://imap.gmail.com
user = user@gmail.com
pass = p4ssw0rd
port = 993
sslverify = false
You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
that the "Folder doesn't exist".
Once your commits are ready to be sent to the mailing list, run the
following commands:
$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
Just make sure to disable line wrapping in the email client (GMail web
interface will line wrap no matter what, so you need to use a real
IMAP client).

View file

@ -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
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
--------

View file

@ -111,6 +111,31 @@ Using direct mode with SSL:
..........................
EXAMPLE
-------
To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig
to specify your account settings:
---------
[imap]
folder = "[Gmail]/Drafts"
host = imaps://imap.gmail.com
user = user@gmail.com
port = 993
sslverify = false
---------
You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
that the "Folder doesn't exist".
Once the commits are ready to be sent, run the following command:
$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
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
users may wish to visit this web page for more information:
http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email
SEE ALSO
--------
linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)
GIT
---
Part of the linkgit:git[1] suite

View file

@ -348,10 +348,12 @@ sendemail.confirm::
one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
in the previous section for the meaning of these values.
EXAMPLE
-------
Use gmail as the smtp server
----------------------------
Add the following section to the config file:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use 'git send-email' to send your patches through the GMail SMTP server,
edit ~/.gitconfig to specify your account settings:
[sendemail]
smtpencryption = tls
@ -359,9 +361,20 @@ Add the following section to the config file:
smtpuser = yourname@gmail.com
smtpserverport = 587
Once your commits are ready to be sent to the mailing list, run the
following commands:
$ git format-patch --cover-letter -M origin/master -o outgoing/
$ edit outgoing/0000-*
$ git send-email outgoing/*
Note: the following perl modules are required
Net::SMTP::SSL, MIME::Base64 and Authen::SASL
SEE ALSO
--------
linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
GIT
---
Part of the linkgit:git[1] suite