Merge branch 'ag/send-email-docs' · freshlybakedca.ke/git@5b124e7

+10 -10

Documentation/config/sendemail.adoc

··· 1 sendemail.identity:: 2 A configuration identity. When given, causes values in the 3 - 'sendemail.<identity>' subsection to take precedence over 4 - values in the 'sendemail' section. The default identity is 5 the value of `sendemail.identity`. 6 7 sendemail.smtpEncryption:: 8 See linkgit:git-send-email[1] for description. Note that this 9 - setting is not subject to the 'identity' mechanism. 10 11 sendemail.smtpSSLCertPath:: 12 Path to ca-certificates (either a directory or a single file). 13 Set it to an empty string to disable certificate verification. 14 15 sendemail.<identity>.*:: 16 - Identity-specific versions of the 'sendemail.*' parameters 17 found below, taking precedence over those when this 18 identity is selected, through either the command-line or 19 `sendemail.identity`. 20 21 sendemail.multiEdit:: 22 - If true (default), a single editor instance will be spawned to edit 23 files you have to edit (patches when `--annotate` is used, and the 24 - summary when `--compose` is used). If false, files will be edited one 25 after the other, spawning a new editor each time. 26 27 sendemail.confirm:: 28 Sets the default for whether to confirm before sending. Must be 29 - one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm` 30 in the linkgit:git-send-email[1] documentation for the meaning of these 31 values. 32 ··· 51 52 sendemail.aliasFileType:: 53 Format of the file(s) specified in sendemail.aliasesFile. Must be 54 - one of 'mutt', 'mailrc', 'pine', 'elm', 'gnus', or 'sendmail'. 55 + 56 What an alias file in each format looks like can be found in 57 the documentation of the email program of the same name. The ··· 101 102 sendemail.smtpBatchSize:: 103 Number of messages to be sent per connection, after that a relogin 104 - will happen. If the value is 0 or undefined, send all messages in 105 one connection. 106 See also the `--batch-size` option of linkgit:git-send-email[1]. 107 ··· 111 112 sendemail.forbidSendmailVariables:: 113 To avoid common misconfiguration mistakes, linkgit:git-send-email[1] 114 - will abort with a warning if any configuration options for "sendmail" 115 exist. Set this variable to bypass the check.

··· 1 sendemail.identity:: 2 A configuration identity. When given, causes values in the 3 + `sendemail.<identity>` subsection to take precedence over 4 + values in the `sendemail` section. The default identity is 5 the value of `sendemail.identity`. 6 7 sendemail.smtpEncryption:: 8 See linkgit:git-send-email[1] for description. Note that this 9 + setting is not subject to the `identity` mechanism. 10 11 sendemail.smtpSSLCertPath:: 12 Path to ca-certificates (either a directory or a single file). 13 Set it to an empty string to disable certificate verification. 14 15 sendemail.<identity>.*:: 16 + Identity-specific versions of the `sendemail.*` parameters 17 found below, taking precedence over those when this 18 identity is selected, through either the command-line or 19 `sendemail.identity`. 20 21 sendemail.multiEdit:: 22 + If `true` (default), a single editor instance will be spawned to edit 23 files you have to edit (patches when `--annotate` is used, and the 24 + summary when `--compose` is used). If `false`, files will be edited one 25 after the other, spawning a new editor each time. 26 27 sendemail.confirm:: 28 Sets the default for whether to confirm before sending. Must be 29 + one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm` 30 in the linkgit:git-send-email[1] documentation for the meaning of these 31 values. 32 ··· 51 52 sendemail.aliasFileType:: 53 Format of the file(s) specified in sendemail.aliasesFile. Must be 54 + one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`. 55 + 56 What an alias file in each format looks like can be found in 57 the documentation of the email program of the same name. The ··· 101 102 sendemail.smtpBatchSize:: 103 Number of messages to be sent per connection, after that a relogin 104 + will happen. If the value is `0` or undefined, send all messages in 105 one connection. 106 See also the `--batch-size` option of linkgit:git-send-email[1]. 107 ··· 111 112 sendemail.forbidSendmailVariables:: 113 To avoid common misconfiguration mistakes, linkgit:git-send-email[1] 114 + will abort with a warning if any configuration options for `sendmail` 115 exist. Set this variable to bypass the check.

+137 -120

Documentation/git-send-email.adoc

··· 21 Patches can be specified as files, directories (which will send all 22 files in the directory), or directly as a revision list. In the 23 last case, any format accepted by linkgit:git-format-patch[1] can 24 - be passed to git send-email, as well as options understood by 25 linkgit:git-format-patch[1]. 26 27 The header of the email is configurable via command-line options. If not ··· 35 This is what linkgit:git-format-patch[1] generates. Most headers and MIME 36 formatting are ignored. 37 38 - 2. The original format used by Greg Kroah-Hartman's 'send_lots_of_email.pl' 39 script 40 + 41 - This format expects the first line of the file to contain the "Cc:" value 42 - and the "Subject:" of the message as the second line. 43 44 45 OPTIONS ··· 54 `sendemail.multiEdit`. 55 56 --bcc=<address>,...:: 57 - Specify a "Bcc:" value for each email. Default is the value of 58 `sendemail.bcc`. 59 + 60 This option may be specified multiple times. 61 62 --cc=<address>,...:: 63 - Specify a starting "Cc:" value for each email. 64 Default is the value of `sendemail.cc`. 65 + 66 This option may be specified multiple times. ··· 69 Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) 70 to edit an introductory message for the patch series. 71 + 72 - When `--compose` is used, git send-email will use the From, To, Cc, Bcc, 73 - Subject, Reply-To, and In-Reply-To headers specified in the message. If 74 - the body of the message (what you type after the headers and a blank 75 - line) only contains blank (or Git: prefixed) lines, the summary won't be 76 sent, but the headers mentioned above will be used unless they are 77 removed. 78 + 79 - Missing From or In-Reply-To headers will be prompted for. 80 + 81 See the CONFIGURATION section for `sendemail.multiEdit`. 82 ··· 85 the value of the `sendemail.from` configuration option is used. If 86 neither the command-line option nor `sendemail.from` are set, then the 87 user will be prompted for the value. The default for the prompt will be 88 - the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not 89 - set, as returned by "git var -l". 90 91 --reply-to=<address>:: 92 Specify the address where replies from recipients should go to. 93 Use this if replies to messages should go to another address than what 94 - is specified with the --from parameter. 95 96 --in-reply-to=<identifier>:: 97 Make the first mail (or all the mails with `--no-thread`) appear as a ··· 112 [PATCH v2 2/3] New tests 113 [PATCH v2 3/3] Implementation 114 + 115 - Only necessary if --compose is also set. If --compose 116 is not set, this will be prompted for. 117 118 --[no-]outlook-id-fix:: 119 Microsoft Outlook SMTP servers discard the Message-ID sent via email and 120 assign a new random Message-ID, thus breaking threads. 121 + 122 - With `--outlook-id-fix`, 'git send-email' uses a mechanism specific to 123 Outlook servers to learn the Message-ID the server assigned to fix the 124 threading. Use it only when you know that the server reports the 125 rewritten Message-ID the same way as Outlook servers do. ··· 130 131 --subject=<string>:: 132 Specify the initial subject of the email thread. 133 - Only necessary if --compose is also set. If --compose 134 is not set, this will be prompted for. 135 136 --to=<address>,...:: 137 Specify the primary recipient of the emails generated. Generally, this 138 will be the upstream maintainer of the project involved. Default is the 139 value of the `sendemail.to` configuration value; if that is unspecified, 140 - and --to-cmd is not specified, this will be prompted for. 141 + 142 This option may be specified multiple times. 143 ··· 145 When encountering a non-ASCII message or subject that does not 146 declare its encoding, add headers/quoting to indicate it is 147 encoded in <encoding>. Default is the value of the 148 - 'sendemail.assume8bitEncoding'; if that is unspecified, this 149 will be prompted for if any non-ASCII files are encountered. 150 + 151 Note that no attempts whatsoever are made to validate the encoding. 152 153 --compose-encoding=<encoding>:: 154 Specify encoding of compose message. Default is the value of the 155 - 'sendemail.composeEncoding'; if that is unspecified, UTF-8 is assumed. 156 157 --transfer-encoding=(7bit|8bit|quoted-printable|base64|auto):: 158 Specify the transfer encoding to be used to send the message over SMTP. 159 - 7bit will fail upon encountering a non-ASCII message. quoted-printable 160 can be useful when the repository contains files that contain carriage 161 - returns, but makes the raw patch email file (as saved from a MUA) much 162 - harder to inspect manually. base64 is even more fool proof, but also 163 - even more opaque. auto will use 8bit when possible, and quoted-printable 164 - otherwise. 165 + 166 Default is the value of the `sendemail.transferEncoding` configuration 167 value; if that is unspecified, default to `auto`. 168 169 --xmailer:: 170 --no-xmailer:: 171 - Add (or prevent adding) the "X-Mailer:" header. By default, 172 the header is added, but it can be turned off by setting the 173 `sendemail.xmailer` configuration variable to `false`. 174 ··· 178 --envelope-sender=<address>:: 179 Specify the envelope sender used to send the emails. 180 This is useful if your default address is not the address that is 181 - subscribed to a list. In order to use the 'From' address, set the 182 - value to "auto". If you use the sendmail binary, you must have 183 - suitable privileges for the -f parameter. Default is the value of the 184 `sendemail.envelopeSender` configuration variable; if that is 185 unspecified, choosing the envelope sender is left to your MTA. 186 ··· 189 be sendmail-like; specifically, it must support the `-i` option. 190 The command will be executed in the shell if necessary. Default 191 is the value of `sendemail.sendmailCmd`. If unspecified, and if 192 - --smtp-server is also unspecified, git-send-email will search 193 - for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH. 194 195 --smtp-encryption=<encryption>:: 196 Specify in what way encrypting begins for the SMTP connection. 197 - Valid values are 'ssl' and 'tls'. Any other value reverts to plain 198 (unencrypted) SMTP, which defaults to port 25. 199 Despite the names, both values will use the same newer version of TLS, 200 - but for historic reasons have these names. 'ssl' refers to "implicit" 201 encryption (sometimes called SMTPS), that uses port 465 by default. 202 - 'tls' refers to "explicit" encryption (often known as STARTTLS), 203 that uses port 25 by default. Other ports might be used by the SMTP 204 server, which are not the default. Commonly found alternative port for 205 - 'tls' and unencrypted is 587. You need to check your provider's 206 documentation or your server configuration to make sure 207 for your own case. Default is the value of `sendemail.smtpEncryption`. 208 209 --smtp-domain=<FQDN>:: 210 Specifies the Fully Qualified Domain Name (FQDN) used in the 211 HELO/EHLO command to the SMTP server. Some servers require the 212 - FQDN to match your IP address. If not set, git send-email attempts 213 to determine your FQDN automatically. Default is the value of 214 `sendemail.smtpDomain`. 215 ··· 223 + 224 If at least one of the specified mechanisms matches the ones advertised by the 225 SMTP server and if it is supported by the utilized SASL library, the mechanism 226 - is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth` 227 is specified, all mechanisms supported by the SASL library can be used. The 228 - special value 'none' maybe specified to completely disable authentication 229 - independently of `--smtp-user` 230 231 --smtp-pass[=<password>]:: 232 Password for SMTP-AUTH. The argument is optional: If no ··· 238 or on the command line. If a username has been specified (with 239 `--smtp-user` or a `sendemail.smtpUser`), but no password has been 240 specified (with `--smtp-pass` or `sendemail.smtpPass`), then 241 - a password is obtained using 'git-credential'. 242 243 --no-smtp-auth:: 244 - Disable SMTP authentication. Short hand for `--smtp-auth=none` 245 246 --smtp-server=<host>:: 247 If set, specifies the outgoing SMTP server to use (e.g. 248 `smtp.example.com` or a raw IP address). If unspecified, and if 249 `--sendmail-cmd` is also unspecified, the default is to search 250 - for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH if such a 251 program is available, falling back to `localhost` otherwise. 252 + 253 For backward compatibility, this option can also specify a full pathname ··· 260 Specifies a port different from the default port (SMTP 261 servers typically listen to smtp port 25, but may also listen to 262 submission port 587, or the common SSL smtp port 465); 263 - symbolic port names (e.g. "submission" instead of 587) 264 are also accepted. The port can also be set with the 265 `sendemail.smtpServerPort` configuration variable. 266 ··· 269 Default value can be specified by the `sendemail.smtpServerOption` 270 configuration option. 271 + 272 - The --smtp-server-option option must be repeated for each option you want 273 to pass to the server. Likewise, different lines in the configuration files 274 must be used for each option. 275 276 --smtp-ssl:: 277 - Legacy alias for '--smtp-encryption ssl'. 278 279 --smtp-ssl-cert-path:: 280 Path to a store of trusted CA certificates for SMTP SSL/TLS 281 certificate validation (either a directory that has been processed 282 - by 'c_rehash', or a single file containing one or more PEM format 283 certificates concatenated together: see verify(1) -CAfile and 284 -CApath for more information on these). Set it to an empty string 285 to disable certificate verification. Defaults to the value of the ··· 298 connection and authentication problems. 299 300 --batch-size=<num>:: 301 - Some email servers (e.g. smtp.163.com) limit the number emails to be 302 sent per session (connection) and this will lead to a failure when 303 sending many messages. With this option, send-email will disconnect after 304 - sending $<num> messages and wait for a few seconds (see --relogin-delay) 305 - and reconnect, to work around such a limit. You may want to 306 - use some form of credential helper to avoid having to retype 307 - your password every time this happens. Defaults to the 308 `sendemail.smtpBatchSize` configuration variable. 309 310 --relogin-delay=<int>:: 311 - Waiting $<int> seconds before reconnecting to SMTP server. Used together 312 - with --batch-size option. Defaults to the `sendemail.smtpReloginDelay` 313 configuration variable. 314 315 Automating ··· 318 --no-to:: 319 --no-cc:: 320 --no-bcc:: 321 - Clears any list of "To:", "Cc:", "Bcc:" addresses previously 322 set via config. 323 324 --no-identity:: ··· 327 328 --to-cmd=<command>:: 329 Specify a command to execute once per patch file which 330 - should generate patch file specific "To:" entries. 331 Output of this command must be single email address per line. 332 - Default is the value of 'sendemail.toCmd' configuration value. 333 334 --cc-cmd=<command>:: 335 Specify a command to execute once per patch file which 336 - should generate patch file specific "Cc:" entries. 337 Output of this command must be single email address per line. 338 Default is the value of `sendemail.ccCmd` configuration value. 339 ··· 341 Specify a command that is executed once per outgoing message 342 and output RFC 2822 style header lines to be inserted into 343 them. When the `sendemail.headerCmd` configuration variable is 344 - set, its value is always used. When --header-cmd is provided 345 at the command line, its value takes precedence over the 346 `sendemail.headerCmd` configuration variable. 347 ··· 350 351 --[no-]chain-reply-to:: 352 If this is set, each email will be sent as a reply to the previous 353 - email sent. If disabled with "--no-chain-reply-to", all emails after 354 the first will be sent as replies to the first email sent. When using 355 this, it is recommended that the first file given be an overview of the 356 entire patch series. Disabled by default, but the `sendemail.chainReplyTo` ··· 358 359 --identity=<identity>:: 360 A configuration identity. When given, causes values in the 361 - 'sendemail.<identity>' subsection to take precedence over 362 - values in the 'sendemail' section. The default identity is 363 the value of `sendemail.identity`. 364 365 --[no-]signed-off-by-cc:: 366 - If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the 367 - cc list. Default is the value of `sendemail.signedOffByCc` configuration 368 - value; if that is unspecified, default to --signed-off-by-cc. 369 370 --[no-]cc-cover:: 371 - If this is set, emails found in Cc: headers in the first patch of 372 the series (typically the cover letter) are added to the cc list 373 - for each email set. Default is the value of 'sendemail.ccCover' 374 - configuration value; if that is unspecified, default to --no-cc-cover. 375 376 --[no-]to-cover:: 377 - If this is set, emails found in To: headers in the first patch of 378 the series (typically the cover letter) are added to the to list 379 - for each email set. Default is the value of 'sendemail.toCover' 380 - configuration value; if that is unspecified, default to --no-to-cover. 381 382 --suppress-cc=<category>:: 383 Specify an additional category of recipients to suppress the 384 auto-cc of: 385 + 386 -- 387 - - 'author' will avoid including the patch author. 388 - - 'self' will avoid including the sender. 389 - - 'cc' will avoid including anyone mentioned in Cc lines in the patch header 390 - except for self (use 'self' for that). 391 - - 'bodycc' will avoid including anyone mentioned in Cc lines in the 392 - patch body (commit message) except for self (use 'self' for that). 393 - - 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except 394 - for self (use 'self' for that). 395 - - 'misc-by' will avoid including anyone mentioned in Acked-by, 396 Reviewed-by, Tested-by and other "-by" lines in the patch body, 397 - except Signed-off-by (use 'sob' for that). 398 - - 'cccmd' will avoid running the --cc-cmd. 399 - - 'body' is equivalent to 'sob' + 'bodycc' + 'misc-by'. 400 - - 'all' will suppress all auto cc values. 401 -- 402 + 403 Default is the value of `sendemail.suppressCc` configuration value; if 404 - that is unspecified, default to 'self' if --suppress-from is 405 - specified, as well as 'body' if --no-signed-off-cc is specified. 406 407 --[no-]suppress-from:: 408 - If this is set, do not add the From: address to the cc: list. 409 Default is the value of `sendemail.suppressFrom` configuration 410 - value; if that is unspecified, default to --no-suppress-from. 411 412 --[no-]thread:: 413 - If this is set, the In-Reply-To and References headers will be 414 added to each email sent. Whether each mail refers to the 415 - previous email (`deep` threading per 'git format-patch' 416 wording) or to the first email (`shallow` threading) is 417 - governed by "--[no-]chain-reply-to". 418 + 419 - If disabled with "--no-thread", those headers will not be added 420 - (unless specified with --in-reply-to). Default is the value of the 421 `sendemail.thread` configuration value; if that is unspecified, 422 - default to --thread. 423 + 424 It is up to the user to ensure that no In-Reply-To header already 425 - exists when 'git send-email' is asked to add it (especially note that 426 - 'git format-patch' can be configured to do the threading itself). 427 Failure to do so may not produce the expected result in the 428 recipient's MUA. 429 430 --[no-]mailmap:: 431 Use the mailmap file (see linkgit:gitmailmap[5]) to map all 432 addresses to their canonical real name and email address. Additional 433 - mailmap data specific to git-send-email may be provided using the 434 `sendemail.mailmap.file` or `sendemail.mailmap.blob` configuration 435 values. Defaults to `sendemail.mailmap`. 436 ··· 441 Confirm just before sending: 442 + 443 -- 444 - - 'always' will always confirm before sending 445 - - 'never' will never confirm before sending 446 - - 'cc' will confirm before sending when send-email has automatically 447 - added addresses from the patch to the Cc list 448 - - 'compose' will confirm before sending the first message when using --compose. 449 - - 'auto' is equivalent to 'cc' + 'compose' 450 -- 451 + 452 Default is the value of `sendemail.confirm` configuration value; if that 453 - is unspecified, default to 'auto' unless any of the suppress options 454 - have been specified, in which case default to 'compose'. 455 456 --dry-run:: 457 Do everything except actually send the emails. ··· 460 When an argument may be understood either as a reference or as a file name, 461 choose to understand it as a format-patch argument (`--format-patch`) 462 or as a file name (`--no-format-patch`). By default, when such a conflict 463 - occurs, git send-email will fail. 464 465 --quiet:: 466 - Make git-send-email less verbose. One line per email should be 467 all that is output. 468 469 --[no-]validate:: ··· 474 * Invoke the sendemail-validate hook if present (see linkgit:githooks[5]). 475 * Warn of patches that contain lines longer than 476 998 characters unless a suitable transfer encoding 477 - ('auto', 'base64', or 'quoted-printable') is used; 478 this is due to SMTP limits as described by 479 https://www.ietf.org/rfc/rfc5322.txt. 480 -- ··· 493 Instead of the normal operation, dump the shorthand alias names from 494 the configured alias file(s), one per line in alphabetical order. Note 495 that this only includes the alias name and not its expanded email addresses. 496 - See 'sendemail.aliasesFile' for more information about aliases. 497 498 --translate-aliases:: 499 Instead of the normal operation, read from standard input and 500 interpret each line as an email alias. Translate it according to the 501 configured alias file(s). Output each translated name and email 502 - address to standard output, one per line. See 'sendemail.aliasFile' 503 for more information about aliases. 504 505 CONFIGURATION ··· 524 smtpServerPort = 587 525 ---- 526 527 If you have multi-factor authentication set up on your Gmail account, you can 528 - generate an app-specific password for use with 'git send-email'. Visit 529 https://security.google.com/settings/security/apppasswords to create it. 530 531 - You can also use OAuth2.0 authentication with Gmail. `OAUTHBEARER` and 532 - `XOAUTH2` are common methods used for this type of authentication. Gmail 533 - supports both of them. As an example, if you want to use `OAUTHBEARER`, edit 534 - your `~/.gitconfig` file and add `smtpAuth = OAUTHBEARER` to your account 535 - settings: 536 537 ---- 538 [sendemail] ··· 543 smtpAuth = OAUTHBEARER 544 ---- 545 546 Use Microsoft Outlook as the SMTP Server 547 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 548 Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords. 549 Therefore, OAuth2.0 authentication must be used for Outlook. Also, it only 550 - supports `XOAUTH2` authentication method. 551 552 Edit `~/.gitconfig` to specify your account settings for Outlook and use its 553 SMTP server with `git send-email`: ··· 579 580 If you are using OAuth2.0 authentication, you need to use an access token in 581 place of a password when prompted. Various OAuth2.0 token generators are 582 - available online. Community maintained credential helpers for Gmail and Outlook 583 - are also available: 584 585 - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] 586 (cross platform, dedicated helper for authenticating Gmail accounts) ··· 588 - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] 589 (cross platform, dedicated helper for authenticating Microsoft Outlook accounts) 590 591 You can also see linkgit:gitcredentials[7] for more OAuth based authentication 592 helpers. 593 594 Note: the following core Perl modules that may be installed with your 595 distribution of Perl are required: 596 - MIME::Base64, MIME::QuotedPrint, Net::Domain and Net::SMTP. 597 These additional Perl modules are also required: 598 - Authen::SASL and Mail::Address. 599 600 601 SEE ALSO

··· 21 Patches can be specified as files, directories (which will send all 22 files in the directory), or directly as a revision list. In the 23 last case, any format accepted by linkgit:git-format-patch[1] can 24 + be passed to `git send-email`, as well as options understood by 25 linkgit:git-format-patch[1]. 26 27 The header of the email is configurable via command-line options. If not ··· 35 This is what linkgit:git-format-patch[1] generates. Most headers and MIME 36 formatting are ignored. 37 38 + 2. The original format used by Greg Kroah-Hartman's `send_lots_of_email.pl` 39 script 40 + 41 + This format expects the first line of the file to contain the `Cc:` value 42 + and the `Subject:` of the message as the second line. 43 44 45 OPTIONS ··· 54 `sendemail.multiEdit`. 55 56 --bcc=<address>,...:: 57 + Specify a `Bcc:` value for each email. Default is the value of 58 `sendemail.bcc`. 59 + 60 This option may be specified multiple times. 61 62 --cc=<address>,...:: 63 + Specify a starting `Cc:` value for each email. 64 Default is the value of `sendemail.cc`. 65 + 66 This option may be specified multiple times. ··· 69 Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) 70 to edit an introductory message for the patch series. 71 + 72 + When `--compose` is used, `git send-email` will use the `From`, `To`, `Cc`, 73 + `Bcc`, `Subject`, `Reply-To`, and `In-Reply-To` headers specified in the 74 + message. If the body of the message (what you type after the headers and a 75 + blank line) only contains blank (or `Git:` prefixed) lines, the summary won't be 76 sent, but the headers mentioned above will be used unless they are 77 removed. 78 + 79 + Missing `From` or `In-Reply-To` headers will be prompted for. 80 + 81 See the CONFIGURATION section for `sendemail.multiEdit`. 82 ··· 85 the value of the `sendemail.from` configuration option is used. If 86 neither the command-line option nor `sendemail.from` are set, then the 87 user will be prompted for the value. The default for the prompt will be 88 + the value of `GIT_AUTHOR_IDENT`, or `GIT_COMMITTER_IDENT` if that is not 89 + set, as returned by `git var -l`. 90 91 --reply-to=<address>:: 92 Specify the address where replies from recipients should go to. 93 Use this if replies to messages should go to another address than what 94 + is specified with the `--from` parameter. 95 96 --in-reply-to=<identifier>:: 97 Make the first mail (or all the mails with `--no-thread`) appear as a ··· 112 [PATCH v2 2/3] New tests 113 [PATCH v2 3/3] Implementation 114 + 115 + Only necessary if `--compose` is also set. If `--compose` 116 is not set, this will be prompted for. 117 118 --[no-]outlook-id-fix:: 119 Microsoft Outlook SMTP servers discard the Message-ID sent via email and 120 assign a new random Message-ID, thus breaking threads. 121 + 122 + With `--outlook-id-fix`, `git send-email` uses a mechanism specific to 123 Outlook servers to learn the Message-ID the server assigned to fix the 124 threading. Use it only when you know that the server reports the 125 rewritten Message-ID the same way as Outlook servers do. ··· 130 131 --subject=<string>:: 132 Specify the initial subject of the email thread. 133 + Only necessary if `--compose` is also set. If `--compose` 134 is not set, this will be prompted for. 135 136 --to=<address>,...:: 137 Specify the primary recipient of the emails generated. Generally, this 138 will be the upstream maintainer of the project involved. Default is the 139 value of the `sendemail.to` configuration value; if that is unspecified, 140 + and `--to-cmd` is not specified, this will be prompted for. 141 + 142 This option may be specified multiple times. 143 ··· 145 When encountering a non-ASCII message or subject that does not 146 declare its encoding, add headers/quoting to indicate it is 147 encoded in <encoding>. Default is the value of the 148 + `sendemail.assume8bitEncoding`; if that is unspecified, this 149 will be prompted for if any non-ASCII files are encountered. 150 + 151 Note that no attempts whatsoever are made to validate the encoding. 152 153 --compose-encoding=<encoding>:: 154 Specify encoding of compose message. Default is the value of the 155 + `sendemail.composeEncoding`; if that is unspecified, UTF-8 is assumed. 156 157 --transfer-encoding=(7bit|8bit|quoted-printable|base64|auto):: 158 Specify the transfer encoding to be used to send the message over SMTP. 159 + `7bit` will fail upon encountering a non-ASCII message. `quoted-printable` 160 can be useful when the repository contains files that contain carriage 161 + returns, but makes the raw patch email file (as saved from an MUA) much 162 + harder to inspect manually. `base64` is even more fool proof, but also 163 + even more opaque. `auto` will use `8bit` when possible, and 164 + `quoted-printable` otherwise. 165 + 166 Default is the value of the `sendemail.transferEncoding` configuration 167 value; if that is unspecified, default to `auto`. 168 169 --xmailer:: 170 --no-xmailer:: 171 + Add (or prevent adding) the `X-Mailer:` header. By default, 172 the header is added, but it can be turned off by setting the 173 `sendemail.xmailer` configuration variable to `false`. 174 ··· 178 --envelope-sender=<address>:: 179 Specify the envelope sender used to send the emails. 180 This is useful if your default address is not the address that is 181 + subscribed to a list. In order to use the `From` address, set the 182 + value to `auto`. If you use the `sendmail` binary, you must have 183 + suitable privileges for the `-f` parameter. Default is the value of the 184 `sendemail.envelopeSender` configuration variable; if that is 185 unspecified, choosing the envelope sender is left to your MTA. 186 ··· 189 be sendmail-like; specifically, it must support the `-i` option. 190 The command will be executed in the shell if necessary. Default 191 is the value of `sendemail.sendmailCmd`. If unspecified, and if 192 + `--smtp-server` is also unspecified, `git send-email` will search 193 + for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH`. 194 195 --smtp-encryption=<encryption>:: 196 Specify in what way encrypting begins for the SMTP connection. 197 + Valid values are `ssl` and `tls`. Any other value reverts to plain 198 (unencrypted) SMTP, which defaults to port 25. 199 Despite the names, both values will use the same newer version of TLS, 200 + but for historic reasons have these names. `ssl` refers to "implicit" 201 encryption (sometimes called SMTPS), that uses port 465 by default. 202 + `tls` refers to "explicit" encryption (often known as STARTTLS), 203 that uses port 25 by default. Other ports might be used by the SMTP 204 server, which are not the default. Commonly found alternative port for 205 + `tls` and unencrypted is 587. You need to check your provider's 206 documentation or your server configuration to make sure 207 for your own case. Default is the value of `sendemail.smtpEncryption`. 208 209 --smtp-domain=<FQDN>:: 210 Specifies the Fully Qualified Domain Name (FQDN) used in the 211 HELO/EHLO command to the SMTP server. Some servers require the 212 + FQDN to match your IP address. If not set, `git send-email` attempts 213 to determine your FQDN automatically. Default is the value of 214 `sendemail.smtpDomain`. 215 ··· 223 + 224 If at least one of the specified mechanisms matches the ones advertised by the 225 SMTP server and if it is supported by the utilized SASL library, the mechanism 226 + is used for authentication. If neither `sendemail.smtpAuth` nor `--smtp-auth` 227 is specified, all mechanisms supported by the SASL library can be used. The 228 + special value `none` maybe specified to completely disable authentication 229 + independently of `--smtp-user`. 230 231 --smtp-pass[=<password>]:: 232 Password for SMTP-AUTH. The argument is optional: If no ··· 238 or on the command line. If a username has been specified (with 239 `--smtp-user` or a `sendemail.smtpUser`), but no password has been 240 specified (with `--smtp-pass` or `sendemail.smtpPass`), then 241 + a password is obtained using linkgit:git-credential[1]. 242 243 --no-smtp-auth:: 244 + Disable SMTP authentication. Short hand for `--smtp-auth=none`. 245 246 --smtp-server=<host>:: 247 If set, specifies the outgoing SMTP server to use (e.g. 248 `smtp.example.com` or a raw IP address). If unspecified, and if 249 `--sendmail-cmd` is also unspecified, the default is to search 250 + for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a 251 program is available, falling back to `localhost` otherwise. 252 + 253 For backward compatibility, this option can also specify a full pathname ··· 260 Specifies a port different from the default port (SMTP 261 servers typically listen to smtp port 25, but may also listen to 262 submission port 587, or the common SSL smtp port 465); 263 + symbolic port names (e.g. `submission` instead of 587) 264 are also accepted. The port can also be set with the 265 `sendemail.smtpServerPort` configuration variable. 266 ··· 269 Default value can be specified by the `sendemail.smtpServerOption` 270 configuration option. 271 + 272 + The `--smtp-server-option` option must be repeated for each option you want 273 to pass to the server. Likewise, different lines in the configuration files 274 must be used for each option. 275 276 --smtp-ssl:: 277 + Legacy alias for `--smtp-encryption ssl`. 278 279 --smtp-ssl-cert-path:: 280 Path to a store of trusted CA certificates for SMTP SSL/TLS 281 certificate validation (either a directory that has been processed 282 + by `c_rehash`, or a single file containing one or more PEM format 283 certificates concatenated together: see verify(1) -CAfile and 284 -CApath for more information on these). Set it to an empty string 285 to disable certificate verification. Defaults to the value of the ··· 298 connection and authentication problems. 299 300 --batch-size=<num>:: 301 + Some email servers (e.g. 'smtp.163.com') limit the number of emails to be 302 sent per session (connection) and this will lead to a failure when 303 sending many messages. With this option, send-email will disconnect after 304 + sending _<num>_ messages and wait for a few seconds 305 + (see `--relogin-delay`) and reconnect, to work around such a limit. 306 + You may want to use some form of credential helper to avoid having to 307 + retype your password every time this happens. Defaults to the 308 `sendemail.smtpBatchSize` configuration variable. 309 310 --relogin-delay=<int>:: 311 + Waiting _<int>_ seconds before reconnecting to SMTP server. Used together 312 + with `--batch-size` option. Defaults to the `sendemail.smtpReloginDelay` 313 configuration variable. 314 315 Automating ··· 318 --no-to:: 319 --no-cc:: 320 --no-bcc:: 321 + Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously 322 set via config. 323 324 --no-identity:: ··· 327 328 --to-cmd=<command>:: 329 Specify a command to execute once per patch file which 330 + should generate patch file specific `To:` entries. 331 Output of this command must be single email address per line. 332 + Default is the value of `sendemail.toCmd` configuration value. 333 334 --cc-cmd=<command>:: 335 Specify a command to execute once per patch file which 336 + should generate patch file specific `Cc:` entries. 337 Output of this command must be single email address per line. 338 Default is the value of `sendemail.ccCmd` configuration value. 339 ··· 341 Specify a command that is executed once per outgoing message 342 and output RFC 2822 style header lines to be inserted into 343 them. When the `sendemail.headerCmd` configuration variable is 344 + set, its value is always used. When `--header-cmd` is provided 345 at the command line, its value takes precedence over the 346 `sendemail.headerCmd` configuration variable. 347 ··· 350 351 --[no-]chain-reply-to:: 352 If this is set, each email will be sent as a reply to the previous 353 + email sent. If disabled with `--no-chain-reply-to`, all emails after 354 the first will be sent as replies to the first email sent. When using 355 this, it is recommended that the first file given be an overview of the 356 entire patch series. Disabled by default, but the `sendemail.chainReplyTo` ··· 358 359 --identity=<identity>:: 360 A configuration identity. When given, causes values in the 361 + `sendemail.<identity>` subsection to take precedence over 362 + values in the `sendemail` section. The default identity is 363 the value of `sendemail.identity`. 364 365 --[no-]signed-off-by-cc:: 366 + If this is set, add emails found in the `Signed-off-by` trailer or `Cc:` 367 + lines to the cc list. Default is the value of `sendemail.signedOffByCc` 368 + configuration value; if that is unspecified, default to 369 + `--signed-off-by-cc`. 370 371 --[no-]cc-cover:: 372 + If this is set, emails found in `Cc:` headers in the first patch of 373 the series (typically the cover letter) are added to the cc list 374 + for each email set. Default is the value of `sendemail.ccCover` 375 + configuration value; if that is unspecified, default to `--no-cc-cover`. 376 377 --[no-]to-cover:: 378 + If this is set, emails found in `To:` headers in the first patch of 379 the series (typically the cover letter) are added to the to list 380 + for each email set. Default is the value of `sendemail.toCover` 381 + configuration value; if that is unspecified, default to `--no-to-cover`. 382 383 --suppress-cc=<category>:: 384 Specify an additional category of recipients to suppress the 385 auto-cc of: 386 + 387 -- 388 + - `author` will avoid including the patch author. 389 + - `self` will avoid including the sender. 390 + - `cc` will avoid including anyone mentioned in Cc lines in the patch header 391 + except for self (use `self` for that). 392 + - `bodycc` will avoid including anyone mentioned in Cc lines in the 393 + patch body (commit message) except for self (use `self` for that). 394 + - `sob` will avoid including anyone mentioned in the Signed-off-by trailers except 395 + for self (use `self` for that). 396 + - `misc-by` will avoid including anyone mentioned in Acked-by, 397 Reviewed-by, Tested-by and other "-by" lines in the patch body, 398 + except Signed-off-by (use `sob` for that). 399 + - `cccmd` will avoid running the --cc-cmd. 400 + - `body` is equivalent to `sob` + `bodycc` + `misc-by`. 401 + - `all` will suppress all auto cc values. 402 -- 403 + 404 Default is the value of `sendemail.suppressCc` configuration value; if 405 + that is unspecified, default to `self` if `--suppress-from` is 406 + specified, as well as `body` if `--no-signed-off-cc` is specified. 407 408 --[no-]suppress-from:: 409 + If this is set, do not add the `From:` address to the `Cc:` list. 410 Default is the value of `sendemail.suppressFrom` configuration 411 + value; if that is unspecified, default to `--no-suppress-from`. 412 413 --[no-]thread:: 414 + If this is set, the `In-Reply-To` and `References` headers will be 415 added to each email sent. Whether each mail refers to the 416 + previous email (`deep` threading per `git format-patch` 417 wording) or to the first email (`shallow` threading) is 418 + governed by `--[no-]chain-reply-to`. 419 + 420 + If disabled with `--no-thread`, those headers will not be added 421 + (unless specified with `--in-reply-to`). Default is the value of the 422 `sendemail.thread` configuration value; if that is unspecified, 423 + default to `--thread`. 424 + 425 It is up to the user to ensure that no In-Reply-To header already 426 + exists when `git send-email` is asked to add it (especially note that 427 + `git format-patch` can be configured to do the threading itself). 428 Failure to do so may not produce the expected result in the 429 recipient's MUA. 430 431 --[no-]mailmap:: 432 Use the mailmap file (see linkgit:gitmailmap[5]) to map all 433 addresses to their canonical real name and email address. Additional 434 + mailmap data specific to `git send-email` may be provided using the 435 `sendemail.mailmap.file` or `sendemail.mailmap.blob` configuration 436 values. Defaults to `sendemail.mailmap`. 437 ··· 442 Confirm just before sending: 443 + 444 -- 445 + - `always` will always confirm before sending. 446 + - `never` will never confirm before sending. 447 + - `cc` will confirm before sending when send-email has automatically 448 + added addresses from the patch to the Cc list. 449 + - `compose` will confirm before sending the first message when using --compose. 450 + - `auto` is equivalent to `cc` + `compose`. 451 -- 452 + 453 Default is the value of `sendemail.confirm` configuration value; if that 454 + is unspecified, default to `auto` unless any of the suppress options 455 + have been specified, in which case default to `compose`. 456 457 --dry-run:: 458 Do everything except actually send the emails. ··· 461 When an argument may be understood either as a reference or as a file name, 462 choose to understand it as a format-patch argument (`--format-patch`) 463 or as a file name (`--no-format-patch`). By default, when such a conflict 464 + occurs, `git send-email` will fail. 465 466 --quiet:: 467 + Make `git send-email` less verbose. One line per email should be 468 all that is output. 469 470 --[no-]validate:: ··· 475 * Invoke the sendemail-validate hook if present (see linkgit:githooks[5]). 476 * Warn of patches that contain lines longer than 477 998 characters unless a suitable transfer encoding 478 + (`auto`, `base64`, or `quoted-printable`) is used; 479 this is due to SMTP limits as described by 480 https://www.ietf.org/rfc/rfc5322.txt. 481 -- ··· 494 Instead of the normal operation, dump the shorthand alias names from 495 the configured alias file(s), one per line in alphabetical order. Note 496 that this only includes the alias name and not its expanded email addresses. 497 + See `sendemail.aliasesFile` for more information about aliases. 498 499 --translate-aliases:: 500 Instead of the normal operation, read from standard input and 501 interpret each line as an email alias. Translate it according to the 502 configured alias file(s). Output each translated name and email 503 + address to standard output, one per line. See `sendemail.aliasFile` 504 for more information about aliases. 505 506 CONFIGURATION ··· 525 smtpServerPort = 587 526 ---- 527 528 + Gmail does not allow using your regular password for `git send-email`. 529 If you have multi-factor authentication set up on your Gmail account, you can 530 + generate an app-specific password for use with `git send-email`. Visit 531 https://security.google.com/settings/security/apppasswords to create it. 532 533 + Alternatively, instead of using an app-specific password, you can use 534 + OAuth2.0 authentication with Gmail. OAuth2.0 is more secure than 535 + app-specific passwords, and works regardless of whether you have multi-factor 536 + authentication set up. `OAUTHBEARER` and `XOAUTH2` are common mechanisms used 537 + for this type of authentication. Gmail supports both of them. As an example, 538 + if you want to use `OAUTHBEARER`, edit your `~/.gitconfig` file and add 539 + `smtpAuth = OAUTHBEARER` to your account settings: 540 541 ---- 542 [sendemail] ··· 547 smtpAuth = OAUTHBEARER 548 ---- 549 550 + Another alternative is using a tool developed by Google known as 551 + https://github.com/google/gmail-oauth2-tools/tree/master/go/sendgmail[sendgmail] 552 + to send emails using `git send-email`. 553 + 554 Use Microsoft Outlook as the SMTP Server 555 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 556 Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords. 557 Therefore, OAuth2.0 authentication must be used for Outlook. Also, it only 558 + supports `XOAUTH2` authentication mechanism. 559 560 Edit `~/.gitconfig` to specify your account settings for Outlook and use its 561 SMTP server with `git send-email`: ··· 587 588 If you are using OAuth2.0 authentication, you need to use an access token in 589 place of a password when prompted. Various OAuth2.0 token generators are 590 + available online. Community maintained credential helpers are also available: 591 592 - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] 593 (cross platform, dedicated helper for authenticating Gmail accounts) ··· 595 - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] 596 (cross platform, dedicated helper for authenticating Microsoft Outlook accounts) 597 598 + - https://github.com/AdityaGarg8/git-credential-email[git-credential-yahoo] 599 + (cross platform, dedicated helper for authenticating Yahoo accounts) 600 + 601 You can also see linkgit:gitcredentials[7] for more OAuth based authentication 602 helpers. 603 604 Note: the following core Perl modules that may be installed with your 605 distribution of Perl are required: 606 + 607 + https://metacpan.org/pod/MIME::Base64[MIME::Base64], 608 + https://metacpan.org/pod/MIME::QuotedPrint[MIME::QuotedPrint], 609 + https://metacpan.org/pod/Net::Domain[Net::Domain] and 610 + https://metacpan.org/pod/Net::SMTP[Net::SMTP]. 611 + 612 These additional Perl modules are also required: 613 + 614 + https://metacpan.org/pod/Authen::SASL[Authen::SASL] and 615 + https://metacpan.org/pod/Mail::Address[Mail::Address]. 616 617 618 SEE ALSO

-4

Documentation/gitcredentials.adoc

··· 133 134 - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions) 135 136 - - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] (cross platform, dedicated helper to authenticate Gmail accounts for linkgit:git-send-email[1]) 137 - 138 - - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] (cross platform, dedicated helper to authenticate Microsoft Outlook accounts for linkgit:git-send-email[1]) 139 - 140 CREDENTIAL CONTEXTS 141 ------------------- 142

··· 133 134 - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions) 135 136 CREDENTIAL CONTEXTS 137 ------------------- 138