Documentation: publicize hints for sending patches with GMail

The hints in SubmittingPatches about stopping GMail from clobbering
patches are widely useful both as examples of "git send-email" and
"git imap-send" usage.

Move the documentation to the appropriate places.

While at it, don't encourage storing passwords in config files.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e9d8c3f6c1cccd40472946a341ea1ecab15b5b5c..938eccf2a5ac9dd629be1bc6bb53a59723c99083 100644 (file)
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -413,8 +413,8 @@ that or Gentoo did it.) So you need to set the
 it.
 
 
-Thunderbird, KMail
-------------------
+Thunderbird, KMail, GMail
+-------------------------
 
 See the MUA-SPECIFIC HINTS section of git-format-patch(1).
 
@@ -431,53 +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.
-
-
-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).

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 04e0f02d8ebc6d34e79883eec5fda5794178d9ee..81b442eb2871b07a26cd760469248433376ce855 100644 (file)
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -337,6 +337,20 @@ 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

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index d3013d6a29f2696e05e3c77b0d6f0159d0a98a76..4e09708cc96fbf88b468141c0234095ee35fee3c 100644 (file)
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -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

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index ee14f74fd3af8dd6cfd9e52002993355d63b97c8..5a168cfab2206cf67453bb5f1fd93dbe75bb4ef0 100644 (file)
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -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