[PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[Aaron Crane]

The suggested approach to dealing with Gmail's propensity for breaking
patches doesn't seem to work.  Recommend an alternative technique which
does.

Signed-off-by: Aaron Crane <git@aaroncrane.co.uk>
---
Thanks to Sverre Rabbelier, Jacob Helwig, David Aguilar, and Jay Soffian for
their suggestions; the advice here comes from them.

 Documentation/SubmittingPatches |   88 +++++++++++++++++++++++++--------------
 1 files changed, 56 insertions(+), 32 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index c686f86..4d3c45f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -517,35 +517,59 @@ 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 any IMAP email client to connect to the google imap server, and forward
-the emails through that.  Just make sure to disable line wrapping in that
-email client.  Alternatively, use "git send-email" instead.
-
-Submitting properly formatted patches via Gmail is simple now that
-IMAP support is available. 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".
-
-Next, ensure that your Gmail settings are correct. In "Settings" the
-"Use Unicode (UTF-8) encoding for outgoing messages" should be checked.
-
-Once your commits are ready to send to the mailing list, run the following
-command to send the patch emails to your Gmail Drafts folder.
-
-	$ git format-patch -M --stdout origin/master | git imap-send
-
-Go to your Gmail account, open the Drafts folder, find the patch email, fill
-in the To: and CC: fields and send away!
-
+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.  Nor can you use
+"git imap-send" to upload an email to your Drafts folder; the web interface
+will still mangle your message when you send it.
+
+The best approach is to send the email using Gmail's SMTP submission
+servers.  Configuring "git send-email" to do that looks like this:
+
+    [sendemail]
+        smtpencryption = tls
+        smtpserver = smtp.gmail.com
+        smtpuser = [YOURADDRESSHERE]@gmail.com
+        smtpserverport = 587
+
+Then sending will look like this:
+
+    $ git format-patch --no-color -C -M origin/master..topic -o outgoing/
+    $ git send-email --compose outgoing/00*
+
+"git send-email" will then prompt you for your password.
+
+However, "git send-email" needs the Net::SMTP::SSL Perl module to send to
+TLS-encrypted servers.  On some operating systems (like Mac OS X with
+MacPorts), it may be hard to install that module.  In such cases, the
+third-party "msmtp" program might be easier to install.  If so, configure
+"git send-email" like this:
+
+    [sendemail]
+        smtpserver = /opt/local/bin/msmtp
+        # adjust the path if necessary
+
+and then configure msmtp to use the Gmail servers, in your ~/.msmtprc file:
+
+    # Set default values for all following accounts
+    defaults
+    tls on
+    tls_trust_file /opt/local/share/curl/curl-ca-bundle.crt
+        # with MacPorts, install the curl-ca-bundle port for this file
+
+    # Configure a "gmail" account
+    account gmail
+    host smtp.gmail.com
+    port 587
+    from [YOURADDRESSHERE]@gmail.com
+    auth on
+    user [YOURADDRESSHERE]@gmail.com
+
+    # Set the "gmail" account as the default
+    account default : gmail
+
+If you're using either Gnome or Mac OS X, msmtp will look up your password
+from your OS keychain; otherwise, or if that fails, it prompts you for your
+password.
+
+For more details, see
+http://git.wiki.kernel.org/index.php/GitTips#Using_gmail_to_send_your_patches
-- 
1.6.6.1

Re: [PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[Jay Soffian]

On Sun, Feb 7, 2010 at 10:14 AM, Aaron Crane <git@aaroncrane.co.uk> wrote:
> The suggested approach to dealing with Gmail's propensity for breaking
> patches doesn't seem to work.  Recommend an alternative technique which
> does.
>
> Signed-off-by: Aaron Crane <git@aaroncrane.co.uk>
> ---

Thanks for writing this up. See inline.

> +However, "git send-email" needs the Net::SMTP::SSL Perl module to send to
> +TLS-encrypted servers.  On some operating systems (like Mac OS X with
> +MacPorts), it may be hard to install that module.  In such cases, the
> +third-party "msmtp" program might be easier to install.

Neither is harder to install than the other, I use msmtp primarily for
historical reasons (git didn't used to support SMTP over SSL/TLS) and
because it doesn't prompt me for my password. :-)

So I'd just say:

"Note that "git send-email" needs the Net::SMTP::SSL Perl module to
send to TLS-encrypted servers.  Alternately, git can make use of the
third-party "msmtp" program like so:"

Thanks,

j.

Re: [PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[Junio C Hamano]

Aaron Crane <git@aaroncrane.co.uk> writes:

> The suggested approach to dealing with Gmail's propensity for breaking
> patches doesn't seem to work.  Recommend an alternative technique which
> does.
>
> Signed-off-by: Aaron Crane <git@aaroncrane.co.uk>
> ---
> Thanks to Sverre Rabbelier, Jacob Helwig, David Aguilar, and Jay Soffian for
> their suggestions; the advice here comes from them.

Do you know _why_ it does not work?  For example, does it not work _at
all_ for you?  Or only certain things does not reliably work (iow, perhaps
you are seeing a bug in imap-send)?  We might want to find who wrote the
imap-send recommendation and ask their input.

What I am trying to get at is to see if the current imap-send suggestion
is fundamentally unworkable with gmail.  Perhaps they stopped supporting
imap.  Perhaps the procedure never worked.  I would be very happy to apply
your patch as is if that is the case.

But if the trouble you had is something fixable, I think removal of the
original text is unfriendly to people who have only imap reachability to
gmail---the description instead needs fixing.

Re: [PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[Aaron Crane]

Junio C Hamano <gitster@pobox.com> wrote:
> Aaron Crane <git@aaroncrane.co.uk> writes:
>> The suggested approach to dealing with Gmail's propensity for breaking
>> patches doesn't seem to work.  Recommend an alternative technique which
>> does.
>
> Do you know _why_ it does not work?  For example, does it not work _at
> all_ for you?  Or only certain things does not reliably work (iow, perhaps
> you are seeing a bug in imap-send)?

What happens for me is that `git imap-send` successfully puts the
message into the gmail Drafts folder, but when it's sent it's been
line-wrapped (and any line-end spaces are deleted, which breaks diffs
containing empty context lines).

I've verified that it's not `git imap-send` at fault, by tweaking it
to tee all socket-written data to a local file; all whitespace in the
mail prepared locally is sent to Gmail unchanged.  So Gmail is
mangling the message when it gets uploaded (or possibly when it's
opened in the web interface, or when it's sent).

I've tried this both with a vanilla Gmail account, and with Google
Apps For Your Domain Standard Edition, and I get the same behaviour.

> What I am trying to get at is to see if the current imap-send suggestion
> is fundamentally unworkable with gmail.  Perhaps they stopped supporting
> imap.  Perhaps the procedure never worked.

As far as I can determine, the current imap-send suggestion is
fundamentally unworkable with gmail at the moment.  I don't know
whether it ever used to work, though I've been assuming that it did.

-- 
Aaron Crane ** http://aaroncrane.co.uk/

Re: [PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[Jonathan Nieder]

Aaron Crane wrote:
> Junio C Hamano <gitster@pobox.com> wrote:

>> What I am trying to get at is to see if the current imap-send suggestion
>> is fundamentally unworkable with gmail.  Perhaps they stopped supporting
>> imap.  Perhaps the procedure never worked.
>
> As far as I can determine, the current imap-send suggestion is
> fundamentally unworkable with gmail at the moment.  I don't know
> whether it ever used to work, though I've been assuming that it did.

I think it still works, or depending on your perspective, it never did.
As John Tapsell wrote in SubmittingPatches (commit 50dffd4e, 2009-02-19):

| 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 any IMAP email client to connect to the google imap server, and forward
| the emails through that.  Just make sure to disable line wrapping in that
| email client.  Alternatively, use "git send-email" instead.

I am not sure what that means about what SubmittingPatches should say:
should it explain both methods, then?

If I were doing it, I would put the information in the git-imap-send and
git-send-mail man pages as examples.  That way, it would be visible for
people submitting patches to _other_ projects, too.  The section in
Documentation/SubmittingPatches could be replaced with a pointer.

Jonathan

Re: [PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[Jonathan Nieder]

Jonathan Nieder wrote:
> Aaron Crane wrote:

>> As far as I can determine, the current imap-send suggestion is
>> fundamentally unworkable with gmail at the moment.  I don't know
>> whether it ever used to work, though I've been assuming that it did.
>
> I think it still works, or depending on your perspective, it never did.

Scratch that: it looks like it once did.

http://thread.gmane.org/gmane.comp.version-control.git/99721/focus=99775

Tom, any clues?  Are you still able to avoid spurious line wrapping in
gmail?

Jonathan

Re: [PATCH] Documentation/SubmittingPatches: fix Gmail workaround advice

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Scratch that: it looks like it once did.
>
> http://thread.gmane.org/gmane.comp.version-control.git/99721/focus=99775
>
> Tom, any clues?  Are you still able to avoid spurious line wrapping in
> gmail?

The example Tom cites $gmane/99759 does not have long enough lines to be
linewrapped, so perhaps the problem was there from day one but was not
noticed.

I just tried it myself (I don't even regularly use Gmail), following the
procedure outlined in SubmittingPatches.  It does look like Gmail web
interface mangles longer lines in the message.