doc: git-htmldocs.googlecode.com is no more
[git/git.git] / Documentation / git-send-email.txt
1 git-send-email(1)
2 =================
3
4 NAME
5 ----
6 git-send-email - Send a collection of patches as emails
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git send-email' [options] <file|directory|rev-list options>...
13 'git send-email' --dump-aliases
14
15
16 DESCRIPTION
17 -----------
18 Takes the patches given on the command line and emails them out.
19 Patches can be specified as files, directories (which will send all
20 files in the directory), or directly as a revision list. In the
21 last case, any format accepted by linkgit:git-format-patch[1] can
22 be passed to git send-email.
23
24 The header of the email is configurable via command-line options. If not
25 specified on the command line, the user will be prompted with a ReadLine
26 enabled interface to provide the necessary information.
27
28 There are two formats accepted for patch files:
29
30 1. mbox format files
31 +
32 This is what linkgit:git-format-patch[1] generates. Most headers and MIME
33 formatting are ignored.
34
35 2. The original format used by Greg Kroah-Hartman's 'send_lots_of_email.pl'
36 script
37 +
38 This format expects the first line of the file to contain the "Cc:" value
39 and the "Subject:" of the message as the second line.
40
41
42 OPTIONS
43 -------
44
45 Composing
46 ~~~~~~~~~
47
48 --annotate::
49 Review and edit each patch you're about to send. Default is the value
50 of 'sendemail.annotate'. See the CONFIGURATION section for
51 'sendemail.multiEdit'.
52
53 --bcc=<address>,...::
54 Specify a "Bcc:" value for each email. Default is the value of
55 'sendemail.bcc'.
56 +
57 This option may be specified multiple times.
58
59 --cc=<address>,...::
60 Specify a starting "Cc:" value for each email.
61 Default is the value of 'sendemail.cc'.
62 +
63 This option may be specified multiple times.
64
65 --compose::
66 Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1])
67 to edit an introductory message for the patch series.
68 +
69 When '--compose' is used, git send-email will use the From, Subject, and
70 In-Reply-To headers specified in the message. If the body of the message
71 (what you type after the headers and a blank line) only contains blank
72 (or Git: prefixed) lines, the summary won't be sent, but From, Subject,
73 and In-Reply-To headers will be used unless they are removed.
74 +
75 Missing From or In-Reply-To headers will be prompted for.
76 +
77 See the CONFIGURATION section for 'sendemail.multiEdit'.
78
79 --from=<address>::
80 Specify the sender of the emails. If not specified on the command line,
81 the value of the 'sendemail.from' configuration option is used. If
82 neither the command-line option nor 'sendemail.from' are set, then the
83 user will be prompted for the value. The default for the prompt will be
84 the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not
85 set, as returned by "git var -l".
86
87 --in-reply-to=<identifier>::
88 Make the first mail (or all the mails with `--no-thread`) appear as a
89 reply to the given Message-Id, which avoids breaking threads to
90 provide a new patch series.
91 The second and subsequent emails will be sent as replies according to
92 the `--[no]-chain-reply-to` setting.
93 +
94 So for example when `--thread` and `--no-chain-reply-to` are specified, the
95 second and subsequent patches will be replies to the first one like in the
96 illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:
97 +
98 [PATCH 0/2] Here is what I did...
99 [PATCH 1/2] Clean up and tests
100 [PATCH 2/2] Implementation
101 [PATCH v2 0/3] Here is a reroll
102 [PATCH v2 1/3] Clean up
103 [PATCH v2 2/3] New tests
104 [PATCH v2 3/3] Implementation
105 +
106 Only necessary if --compose is also set. If --compose
107 is not set, this will be prompted for.
108
109 --subject=<string>::
110 Specify the initial subject of the email thread.
111 Only necessary if --compose is also set. If --compose
112 is not set, this will be prompted for.
113
114 --to=<address>,...::
115 Specify the primary recipient of the emails generated. Generally, this
116 will be the upstream maintainer of the project involved. Default is the
117 value of the 'sendemail.to' configuration value; if that is unspecified,
118 and --to-cmd is not specified, this will be prompted for.
119 +
120 This option may be specified multiple times.
121
122 --8bit-encoding=<encoding>::
123 When encountering a non-ASCII message or subject that does not
124 declare its encoding, add headers/quoting to indicate it is
125 encoded in <encoding>. Default is the value of the
126 'sendemail.assume8bitEncoding'; if that is unspecified, this
127 will be prompted for if any non-ASCII files are encountered.
128 +
129 Note that no attempts whatsoever are made to validate the encoding.
130
131 --compose-encoding=<encoding>::
132 Specify encoding of compose message. Default is the value of the
133 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed.
134
135 --transfer-encoding=(7bit|8bit|quoted-printable|base64)::
136 Specify the transfer encoding to be used to send the message over SMTP.
137 7bit will fail upon encountering a non-ASCII message. quoted-printable
138 can be useful when the repository contains files that contain carriage
139 returns, but makes the raw patch email file (as saved from a MUA) much
140 harder to inspect manually. base64 is even more fool proof, but also
141 even more opaque. Default is the value of the 'sendemail.transferEncoding'
142 configuration value; if that is unspecified, git will use 8bit and not
143 add a Content-Transfer-Encoding header.
144
145 --xmailer::
146 --no-xmailer::
147 Add (or prevent adding) the "X-Mailer:" header. By default,
148 the header is added, but it can be turned off by setting the
149 `sendemail.xmailer` configuration variable to `false`.
150
151 Sending
152 ~~~~~~~
153
154 --envelope-sender=<address>::
155 Specify the envelope sender used to send the emails.
156 This is useful if your default address is not the address that is
157 subscribed to a list. In order to use the 'From' address, set the
158 value to "auto". If you use the sendmail binary, you must have
159 suitable privileges for the -f parameter. Default is the value of the
160 'sendemail.envelopeSender' configuration variable; if that is
161 unspecified, choosing the envelope sender is left to your MTA.
162
163 --smtp-encryption=<encryption>::
164 Specify the encryption to use, either 'ssl' or 'tls'. Any other
165 value reverts to plain SMTP. Default is the value of
166 'sendemail.smtpEncryption'.
167
168 --smtp-domain=<FQDN>::
169 Specifies the Fully Qualified Domain Name (FQDN) used in the
170 HELO/EHLO command to the SMTP server. Some servers require the
171 FQDN to match your IP address. If not set, git send-email attempts
172 to determine your FQDN automatically. Default is the value of
173 'sendemail.smtpDomain'.
174
175 --smtp-auth=<mechanisms>::
176 Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting
177 forces using only the listed mechanisms. Example:
178 +
179 ------
180 $ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ...
181 ------
182 +
183 If at least one of the specified mechanisms matches the ones advertised by the
184 SMTP server and if it is supported by the utilized SASL library, the mechanism
185 is used for authentication. If neither 'sendemail.smtpAuth' nor '--smtp-auth'
186 is specified, all mechanisms supported by the SASL library can be used.
187
188 --smtp-pass[=<password>]::
189 Password for SMTP-AUTH. The argument is optional: If no
190 argument is specified, then the empty string is used as
191 the password. Default is the value of 'sendemail.smtpPass',
192 however '--smtp-pass' always overrides this value.
193 +
194 Furthermore, passwords need not be specified in configuration files
195 or on the command line. If a username has been specified (with
196 '--smtp-user' or a 'sendemail.smtpUser'), but no password has been
197 specified (with '--smtp-pass' or 'sendemail.smtpPass'), then
198 a password is obtained using 'git-credential'.
199
200 --smtp-server=<host>::
201 If set, specifies the outgoing SMTP server to use (e.g.
202 `smtp.example.com` or a raw IP address). Alternatively it can
203 specify a full pathname of a sendmail-like program instead;
204 the program must support the `-i` option. Default value can
205 be specified by the 'sendemail.smtpServer' configuration
206 option; the built-in default is `/usr/sbin/sendmail` or
207 `/usr/lib/sendmail` if such program is available, or
208 `localhost` otherwise.
209
210 --smtp-server-port=<port>::
211 Specifies a port different from the default port (SMTP
212 servers typically listen to smtp port 25, but may also listen to
213 submission port 587, or the common SSL smtp port 465);
214 symbolic port names (e.g. "submission" instead of 587)
215 are also accepted. The port can also be set with the
216 'sendemail.smtpServerPort' configuration variable.
217
218 --smtp-server-option=<option>::
219 If set, specifies the outgoing SMTP server option to use.
220 Default value can be specified by the 'sendemail.smtpServerOption'
221 configuration option.
222 +
223 The --smtp-server-option option must be repeated for each option you want
224 to pass to the server. Likewise, different lines in the configuration files
225 must be used for each option.
226
227 --smtp-ssl::
228 Legacy alias for '--smtp-encryption ssl'.
229
230 --smtp-ssl-cert-path::
231 Path to a store of trusted CA certificates for SMTP SSL/TLS
232 certificate validation (either a directory that has been processed
233 by 'c_rehash', or a single file containing one or more PEM format
234 certificates concatenated together: see verify(1) -CAfile and
235 -CApath for more information on these). Set it to an empty string
236 to disable certificate verification. Defaults to the value of the
237 'sendemail.smtpsslcertpath' configuration variable, if set, or the
238 backing SSL library's compiled-in default otherwise (which should
239 be the best choice on most platforms).
240
241 --smtp-user=<user>::
242 Username for SMTP-AUTH. Default is the value of 'sendemail.smtpUser';
243 if a username is not specified (with '--smtp-user' or 'sendemail.smtpUser'),
244 then authentication is not attempted.
245
246 --smtp-debug=0|1::
247 Enable (1) or disable (0) debug output. If enabled, SMTP
248 commands and replies will be printed. Useful to debug TLS
249 connection and authentication problems.
250
251 Automating
252 ~~~~~~~~~~
253
254 --to-cmd=<command>::
255 Specify a command to execute once per patch file which
256 should generate patch file specific "To:" entries.
257 Output of this command must be single email address per line.
258 Default is the value of 'sendemail.tocmd' configuration value.
259
260 --cc-cmd=<command>::
261 Specify a command to execute once per patch file which
262 should generate patch file specific "Cc:" entries.
263 Output of this command must be single email address per line.
264 Default is the value of 'sendemail.ccCmd' configuration value.
265
266 --[no-]chain-reply-to::
267 If this is set, each email will be sent as a reply to the previous
268 email sent. If disabled with "--no-chain-reply-to", all emails after
269 the first will be sent as replies to the first email sent. When using
270 this, it is recommended that the first file given be an overview of the
271 entire patch series. Disabled by default, but the 'sendemail.chainReplyTo'
272 configuration variable can be used to enable it.
273
274 --identity=<identity>::
275 A configuration identity. When given, causes values in the
276 'sendemail.<identity>' subsection to take precedence over
277 values in the 'sendemail' section. The default identity is
278 the value of 'sendemail.identity'.
279
280 --[no-]signed-off-by-cc::
281 If this is set, add emails found in Signed-off-by: or Cc: lines to the
282 cc list. Default is the value of 'sendemail.signedoffbycc' configuration
283 value; if that is unspecified, default to --signed-off-by-cc.
284
285 --[no-]cc-cover::
286 If this is set, emails found in Cc: headers in the first patch of
287 the series (typically the cover letter) are added to the cc list
288 for each email set. Default is the value of 'sendemail.cccover'
289 configuration value; if that is unspecified, default to --no-cc-cover.
290
291 --[no-]to-cover::
292 If this is set, emails found in To: headers in the first patch of
293 the series (typically the cover letter) are added to the to list
294 for each email set. Default is the value of 'sendemail.tocover'
295 configuration value; if that is unspecified, default to --no-to-cover.
296
297 --suppress-cc=<category>::
298 Specify an additional category of recipients to suppress the
299 auto-cc of:
300 +
301 --
302 - 'author' will avoid including the patch author
303 - 'self' will avoid including the sender
304 - 'cc' will avoid including anyone mentioned in Cc lines in the patch header
305 except for self (use 'self' for that).
306 - 'bodycc' will avoid including anyone mentioned in Cc lines in the
307 patch body (commit message) except for self (use 'self' for that).
308 - 'sob' will avoid including anyone mentioned in Signed-off-by lines except
309 for self (use 'self' for that).
310 - 'cccmd' will avoid running the --cc-cmd.
311 - 'body' is equivalent to 'sob' + 'bodycc'
312 - 'all' will suppress all auto cc values.
313 --
314 +
315 Default is the value of 'sendemail.suppresscc' configuration value; if
316 that is unspecified, default to 'self' if --suppress-from is
317 specified, as well as 'body' if --no-signed-off-cc is specified.
318
319 --[no-]suppress-from::
320 If this is set, do not add the From: address to the cc: list.
321 Default is the value of 'sendemail.suppressFrom' configuration
322 value; if that is unspecified, default to --no-suppress-from.
323
324 --[no-]thread::
325 If this is set, the In-Reply-To and References headers will be
326 added to each email sent. Whether each mail refers to the
327 previous email (`deep` threading per 'git format-patch'
328 wording) or to the first email (`shallow` threading) is
329 governed by "--[no-]chain-reply-to".
330 +
331 If disabled with "--no-thread", those headers will not be added
332 (unless specified with --in-reply-to). Default is the value of the
333 'sendemail.thread' configuration value; if that is unspecified,
334 default to --thread.
335 +
336 It is up to the user to ensure that no In-Reply-To header already
337 exists when 'git send-email' is asked to add it (especially note that
338 'git format-patch' can be configured to do the threading itself).
339 Failure to do so may not produce the expected result in the
340 recipient's MUA.
341
342
343 Administering
344 ~~~~~~~~~~~~~
345
346 --confirm=<mode>::
347 Confirm just before sending:
348 +
349 --
350 - 'always' will always confirm before sending
351 - 'never' will never confirm before sending
352 - 'cc' will confirm before sending when send-email has automatically
353 added addresses from the patch to the Cc list
354 - 'compose' will confirm before sending the first message when using --compose.
355 - 'auto' is equivalent to 'cc' + 'compose'
356 --
357 +
358 Default is the value of 'sendemail.confirm' configuration value; if that
359 is unspecified, default to 'auto' unless any of the suppress options
360 have been specified, in which case default to 'compose'.
361
362 --dry-run::
363 Do everything except actually send the emails.
364
365 --[no-]format-patch::
366 When an argument may be understood either as a reference or as a file name,
367 choose to understand it as a format-patch argument ('--format-patch')
368 or as a file name ('--no-format-patch'). By default, when such a conflict
369 occurs, git send-email will fail.
370
371 --quiet::
372 Make git-send-email less verbose. One line per email should be
373 all that is output.
374
375 --[no-]validate::
376 Perform sanity checks on patches.
377 Currently, validation means the following:
378 +
379 --
380 * Warn of patches that contain lines longer than 998 characters; this
381 is due to SMTP limits as described by http://www.ietf.org/rfc/rfc2821.txt.
382 --
383 +
384 Default is the value of 'sendemail.validate'; if this is not set,
385 default to '--validate'.
386
387 --force::
388 Send emails even if safety checks would prevent it.
389
390
391 Information
392 ~~~~~~~~~~~
393
394 --dump-aliases::
395 Instead of the normal operation, dump the shorthand alias names from
396 the configured alias file(s), one per line in alphabetical order. Note,
397 this only includes the alias name and not its expanded email addresses.
398 See 'sendemail.aliasesfile' for more information about aliases.
399
400
401 CONFIGURATION
402 -------------
403
404 sendemail.aliasesFile::
405 To avoid typing long email addresses, point this to one or more
406 email aliases files. You must also supply 'sendemail.aliasFileType'.
407
408 sendemail.aliasFileType::
409 Format of the file(s) specified in sendemail.aliasesFile. Must be
410 one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
411 +
412 What an alias file in each format looks like can be found in
413 the documentation of the email program of the same name. The
414 differences and limitations from the standard formats are
415 described below:
416 +
417 --
418 sendmail;;
419 * Quoted aliases and quoted addresses are not supported: lines that
420 contain a `"` symbol are ignored.
421 * Redirection to a file (`/path/name`) or pipe (`|command`) is not
422 supported.
423 * File inclusion (`:include: /path/name`) is not supported.
424 * Warnings are printed on the standard error output for any
425 explicitly unsupported constructs, and any other lines that are not
426 recognized by the parser.
427 --
428
429 sendemail.multiEdit::
430 If true (default), a single editor instance will be spawned to edit
431 files you have to edit (patches when '--annotate' is used, and the
432 summary when '--compose' is used). If false, files will be edited one
433 after the other, spawning a new editor each time.
434
435 sendemail.confirm::
436 Sets the default for whether to confirm before sending. Must be
437 one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
438 in the previous section for the meaning of these values.
439
440 EXAMPLE
441 -------
442 Use gmail as the smtp server
443 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
444 To use 'git send-email' to send your patches through the GMail SMTP server,
445 edit ~/.gitconfig to specify your account settings:
446
447 [sendemail]
448 smtpEncryption = tls
449 smtpServer = smtp.gmail.com
450 smtpUser = yourname@gmail.com
451 smtpServerPort = 587
452
453 Once your commits are ready to be sent to the mailing list, run the
454 following commands:
455
456 $ git format-patch --cover-letter -M origin/master -o outgoing/
457 $ edit outgoing/0000-*
458 $ git send-email outgoing/*
459
460 Note: the following perl modules are required
461 Net::SMTP::SSL, MIME::Base64 and Authen::SASL
462
463 SEE ALSO
464 --------
465 linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
466
467 GIT
468 ---
469 Part of the linkgit:git[1] suite