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
commit
a588f93dcb
4 changed files with 229 additions and 195 deletions
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
--------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue