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

+10 -10

Documentation/config/sendemail.adoc

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

+137 -120

Documentation/git-send-email.adoc

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

-4

Documentation/gitcredentials.adoc

··· 133 133 134 134 - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions) 135 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 136 CREDENTIAL CONTEXTS 141 137 ------------------- 142 138