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' 36script 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. 194 195--smtp-pass[=<password>]:: 196 Password for SMTP-AUTH. The argument is optional: If no 197 argument is specified, then the empty string is used as 198 the password. Default is the value of `sendemail.smtpPass`, 199 however `--smtp-pass` always overrides this value. 200+ 201Furthermore, passwords need not be specified in configuration files 202or on the command line. If a username has been specified (with 203`--smtp-user` or a `sendemail.smtpUser`), but no password has been 204specified (with `--smtp-pass` or `sendemail.smtpPass`), then 205a password is obtained using 'git-credential'. 206 207--smtp-server=<host>:: 208 If set, specifies the outgoing SMTP server to use (e.g. 209 `smtp.example.com` or a raw IP address). Alternatively it can 210 specify a full pathname of a sendmail-like program instead; 211 the program must support the `-i` option. Default value can 212 be specified by the `sendemail.smtpServer` configuration 213 option; the built-in default is to search for `sendmail` in 214 `/usr/sbin`, `/usr/lib` and $PATH if such program is 215 available, falling back to `localhost` otherwise. 216 217--smtp-server-port=<port>:: 218 Specifies a port different from the default port (SMTP 219 servers typically listen to smtp port 25, but may also listen to 220 submission port 587, or the common SSL smtp port 465); 221 symbolic port names (e.g. "submission" instead of 587) 222 are also accepted. The port can also be set with the 223 `sendemail.smtpServerPort` configuration variable. 224 225--smtp-server-option=<option>:: 226 If set, specifies the outgoing SMTP server option to use. 227 Default value can be specified by the `sendemail.smtpServerOption` 228 configuration option. 229+ 230The --smtp-server-option option must be repeated for each option you want 231to pass to the server. Likewise, different lines in the configuration files 232must be used for each option. 233 234--smtp-ssl:: 235 Legacy alias for '--smtp-encryption ssl'. 236 237--smtp-ssl-cert-path:: 238 Path to a store of trusted CA certificates for SMTP SSL/TLS 239 certificate validation (either a directory that has been processed 240 by 'c_rehash', or a single file containing one or more PEM format 241 certificates concatenated together: see verify(1) -CAfile and 242 -CApath for more information on these). Set it to an empty string 243 to disable certificate verification. Defaults to the value of the 244 `sendemail.smtpsslcertpath` configuration variable, if set, or the 245 backing SSL library's compiled-in default otherwise (which should 246 be the best choice on most platforms). 247 248--smtp-user=<user>:: 249 Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`; 250 if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`), 251 then authentication is not attempted. 252 253--smtp-debug=0|1:: 254 Enable (1) or disable (0) debug output. If enabled, SMTP 255 commands and replies will be printed. Useful to debug TLS 256 connection and authentication problems. 257 258--batch-size=<num>:: 259 Some email servers (e.g. smtp.163.com) limit the number emails to be 260 sent per session (connection) and this will lead to a failure when 261 sending many messages. With this option, send-email will disconnect after 262 sending $<num> messages and wait for a few seconds (see --relogin-delay) 263 and reconnect, to work around such a limit. You may want to 264 use some form of credential helper to avoid having to retype 265 your password every time this happens. Defaults to the 266 `sendemail.smtpBatchSize` configuration variable. 267 268--relogin-delay=<int>:: 269 Waiting $<int> seconds before reconnecting to SMTP server. Used together 270 with --batch-size option. Defaults to the `sendemail.smtpReloginDelay` 271 configuration variable. 272 273Automating 274~~~~~~~~~~ 275 276--to-cmd=<command>:: 277 Specify a command to execute once per patch file which 278 should generate patch file specific "To:" entries. 279 Output of this command must be single email address per line. 280 Default is the value of 'sendemail.tocmd' configuration value. 281 282--cc-cmd=<command>:: 283 Specify a command to execute once per patch file which 284 should generate patch file specific "Cc:" entries. 285 Output of this command must be single email address per line. 286 Default is the value of `sendemail.ccCmd` configuration value. 287 288--[no-]chain-reply-to:: 289 If this is set, each email will be sent as a reply to the previous 290 email sent. If disabled with "--no-chain-reply-to", all emails after 291 the first will be sent as replies to the first email sent. When using 292 this, it is recommended that the first file given be an overview of the 293 entire patch series. Disabled by default, but the `sendemail.chainReplyTo` 294 configuration variable can be used to enable it. 295 296--identity=<identity>:: 297 A configuration identity. When given, causes values in the 298 'sendemail.<identity>' subsection to take precedence over 299 values in the 'sendemail' section. The default identity is 300 the value of `sendemail.identity`. 301 302--[no-]signed-off-by-cc:: 303 If this is set, add emails found in Signed-off-by: or Cc: lines to the 304 cc list. Default is the value of `sendemail.signedoffbycc` configuration 305 value; if that is unspecified, default to --signed-off-by-cc. 306 307--[no-]cc-cover:: 308 If this is set, emails found in Cc: headers in the first patch of 309 the series (typically the cover letter) are added to the cc list 310 for each email set. Default is the value of 'sendemail.cccover' 311 configuration value; if that is unspecified, default to --no-cc-cover. 312 313--[no-]to-cover:: 314 If this is set, emails found in To: headers in the first patch of 315 the series (typically the cover letter) are added to the to list 316 for each email set. Default is the value of 'sendemail.tocover' 317 configuration value; if that is unspecified, default to --no-to-cover. 318 319--suppress-cc=<category>:: 320 Specify an additional category of recipients to suppress the 321 auto-cc of: 322+ 323-- 324- 'author' will avoid including the patch author 325- 'self' will avoid including the sender 326- 'cc' will avoid including anyone mentioned in Cc lines in the patch header 327 except for self (use 'self' for that). 328- 'bodycc' will avoid including anyone mentioned in Cc lines in the 329 patch body (commit message) except for self (use 'self' for that). 330- 'sob' will avoid including anyone mentioned in Signed-off-by lines except 331 for self (use 'self' for that). 332- 'cccmd' will avoid running the --cc-cmd. 333- 'body' is equivalent to 'sob' + 'bodycc' 334- 'all' will suppress all auto cc values. 335-- 336+ 337Default is the value of `sendemail.suppresscc` configuration value; if 338that is unspecified, default to 'self' if --suppress-from is 339specified, as well as 'body' if --no-signed-off-cc is specified. 340 341--[no-]suppress-from:: 342 If this is set, do not add the From: address to the cc: list. 343 Default is the value of `sendemail.suppressFrom` configuration 344 value; if that is unspecified, default to --no-suppress-from. 345 346--[no-]thread:: 347 If this is set, the In-Reply-To and References headers will be 348 added to each email sent. Whether each mail refers to the 349 previous email (`deep` threading per 'git format-patch' 350 wording) or to the first email (`shallow` threading) is 351 governed by "--[no-]chain-reply-to". 352+ 353If disabled with "--no-thread", those headers will not be added 354(unless specified with --in-reply-to). Default is the value of the 355`sendemail.thread` configuration value; if that is unspecified, 356default to --thread. 357+ 358It is up to the user to ensure that no In-Reply-To header already 359exists when 'git send-email' is asked to add it (especially note that 360'git format-patch' can be configured to do the threading itself). 361Failure to do so may not produce the expected result in the 362recipient's MUA. 363 364 365Administering 366~~~~~~~~~~~~~ 367 368--confirm=<mode>:: 369 Confirm just before sending: 370+ 371-- 372- 'always' will always confirm before sending 373- 'never' will never confirm before sending 374- 'cc' will confirm before sending when send-email has automatically 375 added addresses from the patch to the Cc list 376- 'compose' will confirm before sending the first message when using --compose. 377- 'auto' is equivalent to 'cc' + 'compose' 378-- 379+ 380Default is the value of `sendemail.confirm` configuration value; if that 381is unspecified, default to 'auto' unless any of the suppress options 382have been specified, in which case default to 'compose'. 383 384--dry-run:: 385 Do everything except actually send the emails. 386 387--[no-]format-patch:: 388 When an argument may be understood either as a reference or as a file name, 389 choose to understand it as a format-patch argument (`--format-patch`) 390 or as a file name (`--no-format-patch`). By default, when such a conflict 391 occurs, git send-email will fail. 392 393--quiet:: 394 Make git-send-email less verbose. One line per email should be 395 all that is output. 396 397--[no-]validate:: 398 Perform sanity checks on patches. 399 Currently, validation means the following: 400+ 401-- 402 * Invoke the sendemail-validate hook if present (see linkgit:githooks[5]). 403 * Warn of patches that contain lines longer than 404 998 characters unless a suitable transfer encoding 405 ('auto', 'base64', or 'quoted-printable') is used; 406 this is due to SMTP limits as described by 407 http://www.ietf.org/rfc/rfc5322.txt. 408-- 409+ 410Default is the value of `sendemail.validate`; if this is not set, 411default to `--validate`. 412 413--force:: 414 Send emails even if safety checks would prevent it. 415 416 417Information 418~~~~~~~~~~~ 419 420--dump-aliases:: 421 Instead of the normal operation, dump the shorthand alias names from 422 the configured alias file(s), one per line in alphabetical order. Note, 423 this only includes the alias name and not its expanded email addresses. 424 See 'sendemail.aliasesfile' for more information about aliases. 425 426 427CONFIGURATION 428------------- 429 430sendemail.aliasesFile:: 431 To avoid typing long email addresses, point this to one or more 432 email aliases files. You must also supply `sendemail.aliasFileType`. 433 434sendemail.aliasFileType:: 435 Format of the file(s) specified in sendemail.aliasesFile. Must be 436 one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'. 437+ 438What an alias file in each format looks like can be found in 439the documentation of the email program of the same name. The 440differences and limitations from the standard formats are 441described below: 442+ 443-- 444sendmail;; 445* Quoted aliases and quoted addresses are not supported: lines that 446 contain a `"` symbol are ignored. 447* Redirection to a file (`/path/name`) or pipe (`|command`) is not 448 supported. 449* File inclusion (`:include: /path/name`) is not supported. 450* Warnings are printed on the standard error output for any 451 explicitly unsupported constructs, and any other lines that are not 452 recognized by the parser. 453-- 454 455sendemail.multiEdit:: 456 If true (default), a single editor instance will be spawned to edit 457 files you have to edit (patches when `--annotate` is used, and the 458 summary when `--compose` is used). If false, files will be edited one 459 after the other, spawning a new editor each time. 460 461sendemail.confirm:: 462 Sets the default for whether to confirm before sending. Must be 463 one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm` 464 in the previous section for the meaning of these values. 465 466EXAMPLES 467-------- 468Use gmail as the smtp server 469~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 470To use 'git send-email' to send your patches through the GMail SMTP server, 471edit ~/.gitconfig to specify your account settings: 472 473 [sendemail] 474 smtpEncryption = tls 475 smtpServer = smtp.gmail.com 476 smtpUser = yourname@gmail.com 477 smtpServerPort = 587 478 479If you have multifactor authentication setup on your gmail account, you will 480need to generate an app-specific password for use with 'git send-email'. Visit 481https://security.google.com/settings/security/apppasswords to create it. 482 483Once your commits are ready to be sent to the mailing list, run the 484following commands: 485 486 $ git format-patch --cover-letter -M origin/master -o outgoing/ 487 $ edit outgoing/0000-* 488 $ git send-email outgoing/* 489 490The first time you run it, you will be prompted for your credentials. Enter the 491app-specific or your regular password as appropriate. If you have credential 492helper configured (see linkgit:git-credential[1]), the password will be saved in 493the credential store so you won't have to type it the next time. 494 495Note: the following perl modules are required 496 Net::SMTP::SSL, MIME::Base64 and Authen::SASL 497 498SEE ALSO 499-------- 500linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5) 501 502GIT 503--- 504Part of the linkgit:git[1] suite