{"thread":{"id":"14358","subject":"[PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).","startedAt":"2008-07-08T22:18:16Z","lastAt":"2008-07-09T12:05:34Z","messageCount":3,"participants":["Robert Shearman","Brian Gernhardt","Rob Shearman"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"82642","messageId":"1215555496-21335-4-git-send-email-robertshearman@gmail.com","threadId":"14358","inReplyTo":null,"subject":"[PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).","fromName":"Robert Shearman","fromEmail":"robertshearman@gmail.com","sentAt":"2008-07-08T22:18:16Z","receivedAt":"2008-07-08T22:18:16Z","isPatch":true,"sender":{"key":"robertshearman@gmail.com","avatar":null},"body":"Change the description to be similar to that used for git-send-email(1) to give a better description of what the tool can be used for and sound more user-friendly.\n\nDocument the configuration variables used by git-imap-send, split the example into tunnel and direct examples. Rephrase other parts of the git-imap-send documentation to use better grammar and to be clearer.\n---\n Documentation/git-imap-send.txt |   65 +++++++++++++++++++++++++++++++--------\n 1 files changed, 52 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt\nindex e4a5873..4429e06 100644\n--- a/Documentation/git-imap-send.txt\n+++ b/Documentation/git-imap-send.txt\n@@ -3,7 +3,7 @@ git-imap-send(1)\n \n NAME\n ----\n-git-imap-send - Dump a mailbox from stdin into an imap folder\n+git-imap-send - Send a collection of patches from stdin to an IMAP folder\n \n \n SYNOPSIS\n@@ -13,9 +13,9 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-This command uploads a mailbox generated with git-format-patch\n-into an imap drafts folder.  This allows patches to be sent as\n-other email is sent with mail clients that cannot read mailbox\n+This command uploads a mailbox generated with git format-patch\n+into an IMAP drafts folder.  This allows patches to be sent as\n+other email is when using mail clients that cannot read mailbox\n files directly.\n \n Typical usage is something like:\n@@ -26,21 +26,60 @@ git format-patch --signoff --stdout --attach origin | git imap-send\n CONFIGURATION\n -------------\n \n-'git-imap-send' requires the following values in the repository\n-configuration file (shown with examples):\n+To use the tool imap.folder and either imap.tunnel or imap.host must be set\n+to appropriate values.\n+\n+Variables\n+~~~~~~~~~\n+\n+imap.folder::\n+\tThe folder to drop the mails into, which is typically the Drafts\n+\tfolder. For example: \"INBOX.Drafts\". Required to use imap-send.\n+\n+imap.tunnel::\n+\tCommand used to setup a tunnel to the IMAP server through which\n+\tcommands will be piped instead of using a direct network connection\n+\tto the server. Required when imap.host is not set to use imap-send.\n+\n+imap.host::\n+\tA URL identifying the server. Use a `imap://` prefix for non-secure\n+\tconnections and a `imaps://` prefix for secure connections.\n+\tRequired when imap.tunnel is not set to use imap-send.\n+\n+imap.user::\n+\tThe username to use when logging in to the server.\n+\n+imap.password::\n+\tThe password to use when logging in to the server.\n+ \n+imap.port::\n+\tAn integer port number to connect to on the server.\n+\tDefaults to 143 for imap:// and 993 for imaps://.\n+\n+imap.sslverify::\n+\tA boolean to enable/disable verification of the server certificate\n+\tused by the SSL/TLS connection. Default is `true`.\n+\n+Examples\n+~~~~~~~~\n+\n+Using tunnel mode:\n \n ..........................\n [imap]\n-    Folder = \"INBOX.Drafts\"\n+    folder = \"INBOX.Drafts\"\n+    tunnel = \"ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null\"\n+..........................\n \n-[imap]\n-    Tunnel = \"ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null\"\n+Using direct mode:\n \n+.........................\n [imap]\n-    Host = imaps://imap.example.com\n-    User = bob\n-    Pass = pwd\n-    Port = 993\n+    folder = \"[Gmail]/Drafts\"\n+    host = imaps://imap.example.com\n+    user = bob\n+    pass = p4ssw0rd\n+    port = 123\n     sslverify = false\n ..........................\n \n-- \n1.5.6.GIT\n"},{"id":"82668","messageId":"19AD9080-74BE-4147-8DF5-8A2937129B6D@silverinsanity.com","threadId":"14358","inReplyTo":"1215555496-21335-4-git-send-email-robertshearman@gmail.com","subject":"Re: [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).","fromName":"Brian Gernhardt","fromEmail":"benji@silverinsanity.com","sentAt":"2008-07-09T01:35:46Z","receivedAt":"2008-07-09T01:35:46Z","isPatch":true,"sender":{"key":"benji@silverinsanity.com","avatar":"https://gravatar.com/avatar/e06c101dbc25c68114d859b4a9ec7cf8a2c52fd2b0270ef0eac0e2e63ff22311?d=mp&s=160"},"body":"\nOn Jul 8, 2008, at 6:18 PM, Robert Shearman wrote:\n\n> +Using direct mode:\n>\n> +.........................\n> [imap]\n> -    Host = imaps://imap.example.com\n> -    User = bob\n> -    Pass = pwd\n> -    Port = 993\n> +    folder = \"[Gmail]/Drafts\"\n> +    host = imaps://imap.example.com\n> +    user = bob\n> +    pass = p4ssw0rd\n> +    port = 123\n>     sslverify = false\n> ..........................\n\nIf you're going to use [Gmail]/Drafts as the example folder, shouldn't  \nyou just use mail.google.com as your example?  Google themselves use username@gmail.com \n  as an example[1], so that should be safe. So:\n\n..............................\n[imap]\n     folder = \"[Gmail]/Drafts\"\n     host = imaps://imap.gmail.com\n     port = 993\n     user = username\n     pass = password\n..............................\n\nAnd I also assume that someone has tried this with Gmail and it  \ndoesn't mangle the Drafts.  I'd also move the sslverify option into  \nthe tunneling example, as it's more likely to be needed there.\n\n[1] http://mail.google.com/support/bin/answer.py?answer=78799\n\n~~ Brian\n"},{"id":"82713","messageId":"1096648c0807090505l43e30f43pd348f95af4345956@mail.gmail.com","threadId":"14358","inReplyTo":"19AD9080-74BE-4147-8DF5-8A2937129B6D@silverinsanity.com","subject":"Re: [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).","fromName":"Rob Shearman","fromEmail":"robertshearman@gmail.com","sentAt":"2008-07-09T12:05:34Z","receivedAt":"2008-07-09T12:05:34Z","isPatch":true,"sender":{"key":"robertshearman@gmail.com","avatar":null},"body":"2008/7/9 Brian Gernhardt <benji@silverinsanity.com>:\n>\n> On Jul 8, 2008, at 6:18 PM, Robert Shearman wrote:\n>\n>> +Using direct mode:\n>>\n>> +.........................\n>> [imap]\n>> -    Host = imaps://imap.example.com\n>> -    User = bob\n>> -    Pass = pwd\n>> -    Port = 993\n>> +    folder = \"[Gmail]/Drafts\"\n>> +    host = imaps://imap.example.com\n>> +    user = bob\n>> +    pass = p4ssw0rd\n>> +    port = 123\n>>    sslverify = false\n>> ..........................\n>\n> If you're going to use [Gmail]/Drafts as the example folder, shouldn't you\n> just use mail.google.com as your example?  Google themselves use\n> username@gmail.com as an example[1], so that should be safe. So:\n\nI'll fix it not to use \"[Gmail]/Drafts\" in the example as that is the\nexception rather than the norm.\n\n> And I also assume that someone has tried this with Gmail and it doesn't\n> mangle the Drafts.\n\nYes, as specified in my previous email I tested with two different\nIMAP servers, one of which was Gmail.\n\n>  I'd also move the sslverify option into the tunneling\n> example, as it's more likely to be needed there.\n\nActually, the sslverify option is ignored in tunnel mode (since you're\nlikely to be using your own encryption with the tunnel). I'll document\nthis and other ignored options in a revised patch.\n\n-- \nRob Shearman\n"}]}