# [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1). 3 messages from 2008-07-08 to 2008-07-09. Participants: Robert Shearman, Brian Gernhardt, Rob Shearman. Thread: https://gitlist.dev/t/14358 ## Robert Shearman, 2008-07-08 22:18 Subject: [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1). Message-ID: <1215555496-21335-4-git-send-email-robertshearman@gmail.com> URL: https://gitlist.dev/e/1215555496-21335-4-git-send-email-robertshearman%40gmail.com ``` 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. Document 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. --- Documentation/git-imap-send.txt | 65 +++++++++++++++++++++++++++++++-------- 1 files changed, 52 insertions(+), 13 deletions(-) diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index e4a5873..4429e06 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -3,7 +3,7 @@ git-imap-send(1) NAME ---- -git-imap-send - Dump a mailbox from stdin into an imap folder +git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS @@ -13,9 +13,9 @@ SYNOPSIS DESCRIPTION ----------- -This command uploads a mailbox generated with git-format-patch -into an imap drafts folder. This allows patches to be sent as -other email is sent with mail clients that cannot read mailbox +This command uploads a mailbox generated with git format-patch +into an IMAP drafts folder. This allows patches to be sent as +other email is when using mail clients that cannot read mailbox files directly. Typical usage is something like: @@ -26,21 +26,60 @@ git format-patch --signoff --stdout --attach origin | git imap-send CONFIGURATION ------------- -'git-imap-send' requires the following values in the repository -configuration file (shown with examples): +To use the tool imap.folder and either imap.tunnel or imap.host must be set +to appropriate values. + +Variables +~~~~~~~~~ + +imap.folder:: + The folder to drop the mails into, which is typically the Drafts + folder. For example: "INBOX.Drafts". Required to use imap-send. + +imap.tunnel:: + Command used to setup a tunnel to the IMAP server through which + commands will be piped instead of using a direct network connection + to the server. Required when imap.host is not set to use imap-send. + +imap.host:: + A URL identifying the server. Use a `imap://` prefix for non-secure + connections and a `imaps://` prefix for secure connections. + Required when imap.tunnel is not set to use imap-send. + +imap.user:: + The username to use when logging in to the server. + +imap.password:: + The password to use when logging in to the server. + +imap.port:: + An integer port number to connect to on the server. + Defaults to 143 for imap:// and 993 for imaps://. + +imap.sslverify:: + A boolean to enable/disable verification of the server certificate + used by the SSL/TLS connection. Default is `true`. + +Examples +~~~~~~~~ + +Using tunnel mode: .......................... [imap] - Folder = "INBOX.Drafts" + folder = "INBOX.Drafts" + tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null" +.......................... -[imap] - Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null" +Using direct mode: +......................... [imap] - Host = imaps://imap.example.com - User = bob - Pass = pwd - Port = 993 + folder = "[Gmail]/Drafts" + host = imaps://imap.example.com + user = bob + pass = p4ssw0rd + port = 123 sslverify = false .......................... -- 1.5.6.GIT ``` ## Brian Gernhardt, 2008-07-09 01:35 Subject: Re: [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1). Message-ID: <19AD9080-74BE-4147-8DF5-8A2937129B6D@silverinsanity.com> URL: https://gitlist.dev/e/19AD9080-74BE-4147-8DF5-8A2937129B6D%40silverinsanity.com In-Reply-To: <1215555496-21335-4-git-send-email-robertshearman@gmail.com> ``` On Jul 8, 2008, at 6:18 PM, Robert Shearman wrote: > +Using direct mode: > > +......................... > [imap] > - Host = imaps://imap.example.com > - User = bob > - Pass = pwd > - Port = 993 > + folder = "[Gmail]/Drafts" > + host = imaps://imap.example.com > + user = bob > + pass = p4ssw0rd > + port = 123 > sslverify = false > .......................... If you're going to use [Gmail]/Drafts as the example folder, shouldn't you just use mail.google.com as your example? Google themselves use username@gmail.com as an example[1], so that should be safe. So: .............................. [imap] folder = "[Gmail]/Drafts" host = imaps://imap.gmail.com port = 993 user = username pass = password .............................. And I also assume that someone has tried this with Gmail and it doesn't mangle the Drafts. I'd also move the sslverify option into the tunneling example, as it's more likely to be needed there. [1] http://mail.google.com/support/bin/answer.py?answer=78799 ~~ Brian ``` ## Rob Shearman, 2008-07-09 12:05 Subject: Re: [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1). Message-ID: <1096648c0807090505l43e30f43pd348f95af4345956@mail.gmail.com> URL: https://gitlist.dev/e/1096648c0807090505l43e30f43pd348f95af4345956%40mail.gmail.com In-Reply-To: <19AD9080-74BE-4147-8DF5-8A2937129B6D@silverinsanity.com> ``` 2008/7/9 Brian Gernhardt : > > On Jul 8, 2008, at 6:18 PM, Robert Shearman wrote: > >> +Using direct mode: >> >> +......................... >> [imap] >> - Host = imaps://imap.example.com >> - User = bob >> - Pass = pwd >> - Port = 993 >> + folder = "[Gmail]/Drafts" >> + host = imaps://imap.example.com >> + user = bob >> + pass = p4ssw0rd >> + port = 123 >> sslverify = false >> .......................... > > If you're going to use [Gmail]/Drafts as the example folder, shouldn't you > just use mail.google.com as your example? Google themselves use > username@gmail.com as an example[1], so that should be safe. So: I'll fix it not to use "[Gmail]/Drafts" in the example as that is the exception rather than the norm. > And I also assume that someone has tried this with Gmail and it doesn't > mangle the Drafts. Yes, as specified in my previous email I tested with two different IMAP servers, one of which was Gmail. > I'd also move the sslverify option into the tunneling > example, as it's more likely to be needed there. Actually, the sslverify option is ignored in tunnel mode (since you're likely to be using your own encryption with the tunnel). I'll document this and other ignored options in a revised patch. -- Rob Shearman ```