Documentation: Improve documentation for git-imap-send(1)
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. Signed-off-by: Robert Shearman <robertshearman@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Robert Shearman committed
Jul 9, 2008 at 22:29 UTC
c82b0748e53d51cc999c16f97bc76c25f2b46b12
1 file changed
+65
-12
Documentation/git-imap-send.txt
+65
-12
@@ -3,7 +3,7 @@ git-imap-send(1)
3
4
NAME
5
----
6
-git-imap-send - Dump a mailbox from stdin into an imap folder
6
+git-imap-send - Send a collection of patches from stdin to an IMAP folder
7
8
9
SYNOPSIS
@@ -13,9 +13,9 @@ SYNOPSIS
13
14
DESCRIPTION
15
-----------
16
-This command uploads a mailbox generated with git-format-patch
17
-into an imap drafts folder. This allows patches to be sent as
18
-other email is sent with mail clients that cannot read mailbox
16
+This command uploads a mailbox generated with 'git-format-patch'
17
+into an IMAP drafts folder. This allows patches to be sent as
18
+other email is when using mail clients that cannot read mailbox
19
files directly.
20
21
Typical usage is something like:
@@ -26,21 +26,74 @@ git format-patch --signoff --stdout --attach origin | git imap-send
26
CONFIGURATION
27
-------------
28
29
-'git-imap-send' requires the following values in the repository
30
-configuration file (shown with examples):
29
+To use the tool, imap.folder and either imap.tunnel or imap.host must be set
30
+to appropriate values.
31
+
32
+Variables
33
+~~~~~~~~~
34
+
35
+imap.folder::
36
+ The folder to drop the mails into, which is typically the Drafts
37
+ folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
38
+ "[Gmail]/Drafts". Required to use imap-send.
39
+
40
+imap.tunnel::
41
+ Command used to setup a tunnel to the IMAP server through which
42
+ commands will be piped instead of using a direct network connection
43
+ to the server. Required when imap.host is not set to use imap-send.
44
+
45
+imap.host::
46
+ A URL identifying the server. Use a `imap://` prefix for non-secure
47
+ connections and a `imaps://` prefix for secure connections.
48
+ Ignored when imap.tunnel is set, but required to use imap-send
49
+ otherwise.
50
+
51
+imap.user::
52
+ The username to use when logging in to the server.
53
+
54
+imap.password::
55
+ The password to use when logging in to the server.
56
+
57
+imap.port::
58
+ An integer port number to connect to on the server.
59
+ Defaults to 143 for imap:// hosts and 993 for imaps:// hosts.
60
+ Ignored when imap.tunnel is set.
61
+
62
+imap.sslverify::
63
+ A boolean to enable/disable verification of the server certificate
64
+ used by the SSL/TLS connection. Default is `true`. Ignored when
65
+ imap.tunnel is set.
66
+
67
+Examples
68
+~~~~~~~~
69
+
70
+Using tunnel mode:
71
72
..........................
73
[imap]
34
- Folder = "INBOX.Drafts"
74
+ folder = "INBOX.Drafts"
75
+ tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
76
+..........................
77
78
+Using direct mode:
79
+
80
+.........................
81
[imap]
37
- Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null"
82
+ folder = "INBOX.Drafts"
83
+ host = imap://imap.example.com
84
+ user = bob
85
+ pass = p4ssw0rd
86
+..........................
87
+
88
+Using direct mode with SSL:
89
90
+.........................
91
[imap]
40
- Host = imap://imap.example.com
41
- User = bob
42
- Pass = pwd
43
- Port = 143
92
+ folder = "INBOX.Drafts"
93
+ host = imaps://imap.example.com
94
+ user = bob
95
+ pass = p4ssw0rd
96
+ port = 123
97
sslverify = false
98
..........................
99