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