[thirdparty/git.git] / Documentation / git-imap-send.txt

git-imap-send(1)
================

NAME
----
git-imap-send - Send a collection of patches from stdin to an IMAP folder


SYNOPSIS
--------
[verse]
'git imap-send'


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 when using mail clients that cannot read mailbox
files directly. The command also works with any general mailbox
in which emails have the fields "From", "Date", and "Subject" in
that order.

Typical usage is something like:

git format-patch --signoff --stdout --attach origin | git imap-send


CONFIGURATION
-------------

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", "INBOX/Drafts" or
	"[Gmail]/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.
	Ignored when imap.tunnel is set, but required to use imap-send
	otherwise.

imap.user::
	The username to use when logging in to the server.

imap.pass::
	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:// hosts and 993 for imaps:// hosts.
	Ignored when imap.tunnel is set.

imap.sslverify::
	A boolean to enable/disable verification of the server certificate
	used by the SSL/TLS connection. Default is `true`. Ignored when
	imap.tunnel is set.

imap.preformattedHTML::
	A boolean to enable/disable the use of html encoding when sending
	a patch.  An html encoded patch will be bracketed with <pre>
	and have a content type of text/html.  Ironically, enabling this
	option causes Thunderbird to send the patch as a plain/text,
	format=fixed email.  Default is `false`.

imap.authMethod::
	Specify authenticate method for authentication with IMAP server.
	Current supported method is 'CRAM-MD5' only.

Examples
~~~~~~~~

Using tunnel mode:

..........................
[imap]
    folder = "INBOX.Drafts"
    tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
..........................

Using direct mode:

.........................
[imap]
    folder = "INBOX.Drafts"
    host = imap://imap.example.com
    user = bob
    pass = p4ssw0rd
..........................

Using direct mode with SSL:

.........................
[imap]
    folder = "INBOX.Drafts"
    host = imaps://imap.example.com
    user = bob
    pass = p4ssw0rd
    port = 123
    sslverify = false
..........................


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
sent by your email program meets the standards of your project.
Many projects do not like patches to be attached.  Some mail
agents will transform patches (e.g. wrap lines, send them as
format=flowed) in ways that make them fail.  You will get angry
flames ridiculing you if you don't check this.

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
Commit	Line	Data
454a35b8 MM	1	git-imap-send(1)
	2	================
	3
	4	NAME
	5	----
c82b0748	6	git-imap-send - Send a collection of patches from stdin to an IMAP folder
454a35b8 MM	7
	8
	9	SYNOPSIS
	10	--------
7791a1d9	11	[verse]
b1889c36	12	'git imap-send'
454a35b8 MM	13
	14
	15	DESCRIPTION
	16	-----------
0b444cdb	17	This command uploads a mailbox generated with 'git format-patch'
c82b0748 RS	18	into an IMAP drafts folder. This allows patches to be sent as
c82b0748 RS	19	other email is when using mail clients that cannot read mailbox
4916c8f9 RR	20	files directly. The command also works with any general mailbox
	21	in which emails have the fields "From", "Date", and "Subject" in
	22	that order.
454a35b8 MM	23
	24	Typical usage is something like:
	25
b1889c36	26	git format-patch --signoff --stdout --attach origin \| git imap-send
454a35b8 MM	27
	28
	29	CONFIGURATION
	30	-------------
	31
c82b0748 RS	32	To use the tool, imap.folder and either imap.tunnel or imap.host must be set
	33	to appropriate values.
	34
	35	Variables
	36	~~~~~~~~~
	37
	38	imap.folder::
	39	The folder to drop the mails into, which is typically the Drafts
	40	folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
	41	"[Gmail]/Drafts". Required to use imap-send.
	42
	43	imap.tunnel::
	44	Command used to setup a tunnel to the IMAP server through which
	45	commands will be piped instead of using a direct network connection
	46	to the server. Required when imap.host is not set to use imap-send.
	47
	48	imap.host::
	49	A URL identifying the server. Use a `imap://` prefix for non-secure
	50	connections and a `imaps://` prefix for secure connections.
	51	Ignored when imap.tunnel is set, but required to use imap-send
	52	otherwise.
	53
	54	imap.user::
	55	The username to use when logging in to the server.
	56
43be7a78	57	imap.pass::
c82b0748 RS	58	The password to use when logging in to the server.
	59
	60	imap.port::
	61	An integer port number to connect to on the server.
	62	Defaults to 143 for imap:// hosts and 993 for imaps:// hosts.
	63	Ignored when imap.tunnel is set.
	64
	65	imap.sslverify::
	66	A boolean to enable/disable verification of the server certificate
	67	used by the SSL/TLS connection. Default is `true`. Ignored when
	68	imap.tunnel is set.
	69
c64d84f1 JW	70	imap.preformattedHTML::
	71	A boolean to enable/disable the use of html encoding when sending
	72	a patch. An html encoded patch will be bracketed with <pre>
	73	and have a content type of text/html. Ironically, enabling this
	74	option causes Thunderbird to send the patch as a plain/text,
	75	format=fixed email. Default is `false`.
	76
ae9c606e HM	77	imap.authMethod::
	78	Specify authenticate method for authentication with IMAP server.
	79	Current supported method is 'CRAM-MD5' only.
	80
c82b0748 RS	81	Examples
	82	~~~~~~~~
	83
	84	Using tunnel mode:
454a35b8	85
2b5f3ed3	86	..........................
454a35b8	87	[imap]
c82b0748 RS	88	folder = "INBOX.Drafts"
	89	tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
	90	..........................
454a35b8	91
c82b0748 RS	92	Using direct mode:
	93
	94	.........................
454a35b8	95	[imap]
c82b0748 RS	96	folder = "INBOX.Drafts"
	97	host = imap://imap.example.com
	98	user = bob
	99	pass = p4ssw0rd
	100	..........................
	101
	102	Using direct mode with SSL:
454a35b8	103
c82b0748	104	.........................
454a35b8	105	[imap]
c82b0748 RS	106	folder = "INBOX.Drafts"
	107	host = imaps://imap.example.com
	108	user = bob
	109	pass = p4ssw0rd
	110	port = 123
684ec6c6	111	sslverify = false
2b5f3ed3	112	..........................
454a35b8 MM	113
454a35b8 MM	114
36c10e6d JN	115	EXAMPLE
	116	-------
	117	To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig
	118	to specify your account settings:
	119
	120	---------
	121	[imap]
	122	folder = "[Gmail]/Drafts"
	123	host = imaps://imap.gmail.com
	124	user = user@gmail.com
	125	port = 993
	126	sslverify = false
	127	---------
	128
	129	You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
	130	that the "Folder doesn't exist".
	131
	132	Once the commits are ready to be sent, run the following command:
	133
	134	$ git format-patch --cover-letter -M --stdout origin/master \| git imap-send
	135
	136	Just make sure to disable line wrapping in the email client (GMail's web
	137	interface will wrap lines no matter what, so you need to use a real
	138	IMAP client).
	139
1a526d48 JW	140	CAUTION
	141	-------
	142	It is still your responsibility to make sure that the email message
	143	sent by your email program meets the standards of your project.
	144	Many projects do not like patches to be attached. Some mail
	145	agents will transform patches (e.g. wrap lines, send them as
	146	format=flowed) in ways that make them fail. You will get angry
	147	flames ridiculing you if you don't check this.
	148
	149	Thunderbird in particular is known to be problematic. Thunderbird
	150	users may wish to visit this web page for more information:
	151	http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email
	152
36c10e6d JN	153	SEE ALSO
	154	--------
	155	linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)
	156
454a35b8 MM	157	GIT
454a35b8 MM	158	---
9e1f0a85	159	Part of the linkgit:git[1] suite