Skip to content

Commit

Permalink
Merge branch 'jn/format-patch-doc' into maint
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
Junio C Hamano committed May 26, 2011
2 parents ea8ec09 + b895960 commit 63c11eb
Show file tree
Hide file tree
Showing 4 changed files with 229 additions and 195 deletions.
207 changes: 15 additions & 192 deletions Documentation/SubmittingPatches
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -443,89 +413,10 @@ that or Gentoo did it.) So you need to set the
it.


Thunderbird
-----------

(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.
Thunderbird, KMail, GMail
-------------------------


[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
----
Expand All @@ -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).
Loading

0 comments on commit 63c11eb

Please sign in to comment.