Hi all,
This patch series includes four patches:
1. The first patch adds a link to the `git-credential-yahoo` helper for
Yahoo accounts and links Google's `sendgmail` tool as an alternative
method for sending emails through Gmail.
2. The second patch improves the formatting of the `git-send-email`
documentation, making it more readable and consistent.
3. The third patch removes the email credential helper links from the
`gitcredentials` page. The links are still available in the
`git-send-email` documentation, which is the right place for them.
4. The fourth patch clarifies the purpose of using an app password for
Gmail in the `git-send-email` documentation. It also encourages
users to use OAuth2.0 over app passwords for better security.
Detailed explanation of the changes has been done in individual patch.
v2: - Removed instructions for Yahoo SMTP server since I've realised that
Yahoo *was* a popular email service. Also, the instructions were
just making the docs more crowded. I've also added a link to
Google's `sendgmail` tool in the first patch. The second patch has been
added to address the issues that came up here:
https://github.com/git/git-scm.com/pull/2005
v3: - Added a patch to improve the formatting of the `git-send-email`
documentation.
v4: - Added cpan links of the perl modules requires for `git-send-email`
to work.
v5: - Added a patch to make the purpose of using app password for Gmail
more clear in `send-email` documentation.
v6: - Reword the documentation a bit more in last patch.
- Markdown Git: -> 'Git:' in the second patch.
- Restore the non-existent link (atleast what I believed that to be) in the
second patch.
- Remove the unnecessary use of $ with <num> and <int> placeholders in the
second patch.
- White at it, also prefer using the word "mechanism" over "method" for
`OAUTHBEARER` and `XOAUTH2` in git-send-email docs since that is what
official docs use. This changes has been done in the last patch.
- Sign-off the last patch.
v7: - Use backticks consistently for all headers as well in second patch.
Aditya Garg (4):
docs: add credential helper for yahoo and link Google's sendgmail tool
docs: improve formatting in git-send-email documentation
docs: remove credential helper links for emails from gitcredentials
docs: make the purpose of using app password for Gmail more clear in
send-email
Documentation/config/sendemail.adoc | 20 +--
Documentation/git-send-email.adoc | 257 +++++++++++++++-------------
Documentation/gitcredentials.adoc | 4 -
3 files changed, 147 insertions(+), 134 deletions(-)
Range-diff against v6:
-: ---------- > 1: 2c47cc5396 docs: add credential helper for yahoo and link Google's sendgmail tool
1: 20da5d6a58 ! 2: 660305721d docs: improve formatting in git-send-email documentation
@@ Commit message
Signed-off-by: Aditya Garg <gargaditya08@xxxxxxxx>
## Documentation/config/sendemail.adoc ##
-@@ Documentation/config/sendemail.adoc: sendemail.<identity>.*::
+@@
+ sendemail.identity::
+ A configuration identity. When given, causes values in the
+- 'sendemail.<identity>' subsection to take precedence over
+- values in the 'sendemail' section. The default identity is
++ `sendemail.<identity>` subsection to take precedence over
++ values in the `sendemail` section. The default identity is
+ the value of `sendemail.identity`.
+
+ sendemail.smtpEncryption::
+ See linkgit:git-send-email[1] for description. Note that this
+- setting is not subject to the 'identity' mechanism.
++ setting is not subject to the `identity` mechanism.
+
+ sendemail.smtpSSLCertPath::
+ Path to ca-certificates (either a directory or a single file).
+ Set it to an empty string to disable certificate verification.
+
+ sendemail.<identity>.*::
+- Identity-specific versions of the 'sendemail.*' parameters
++ Identity-specific versions of the `sendemail.*` parameters
+ found below, taking precedence over those when this
+ identity is selected, through either the command-line or
`sendemail.identity`.
sendemail.multiEdit::
@@ Documentation/config/sendemail.adoc: sendemail.<identity>.*::
after the other, spawning a new editor each time.
sendemail.confirm::
+ Sets the default for whether to confirm before sending. Must be
+- one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
++ one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm`
+ in the linkgit:git-send-email[1] documentation for the meaning of these
+ values.
+
+@@ Documentation/config/sendemail.adoc: sendemail.aliasesFile::
+
+ sendemail.aliasFileType::
+ Format of the file(s) specified in sendemail.aliasesFile. Must be
+- one of 'mutt', 'mailrc', 'pine', 'elm', 'gnus', or 'sendmail'.
++ one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`.
+ +
+ What an alias file in each format looks like can be found in
+ the documentation of the email program of the same name. The
@@ Documentation/config/sendemail.adoc: sendemail.signedOffCc (deprecated)::
sendemail.smtpBatchSize::
@@ Documentation/git-send-email.adoc: There are two formats accepted for patch file
+
-This format expects the first line of the file to contain the "Cc:" value
-and the "Subject:" of the message as the second line.
-+This format expects the first line of the file to contain the 'Cc:' value
-+and the 'Subject:' of the message as the second line.
++This format expects the first line of the file to contain the `Cc:` value
++and the `Subject:` of the message as the second line.
OPTIONS
@@ Documentation/git-send-email.adoc: Composing
--bcc=<address>,...::
- Specify a "Bcc:" value for each email. Default is the value of
-+ Specify a 'Bcc:' value for each email. Default is the value of
++ Specify a `Bcc:` value for each email. Default is the value of
`sendemail.bcc`.
+
This option may be specified multiple times.
--cc=<address>,...::
- Specify a starting "Cc:" value for each email.
-+ Specify a starting 'Cc:' value for each email.
++ Specify a starting `Cc:` value for each email.
Default is the value of `sendemail.cc`.
+
This option may be specified multiple times.
@@ Documentation/git-send-email.adoc: This option may be specified multiple times.
-Subject, Reply-To, and In-Reply-To headers specified in the message. If
-the body of the message (what you type after the headers and a blank
-line) only contains blank (or Git: prefixed) lines, the summary won't be
-+When `--compose` is used, `git send-email` will use the 'From', 'To', 'Cc',
-+'Bcc', 'Subject', 'Reply-To', and 'In-Reply-To' headers specified in the
++When `--compose` is used, `git send-email` will use the `From`, `To`, `Cc`,
++`Bcc`, `Subject`, `Reply-To`, and `In-Reply-To` headers specified in the
+message. If the body of the message (what you type after the headers and a
-+blank line) only contains blank (or 'Git:' prefixed) lines, the summary won't be
++blank line) only contains blank (or `Git:` prefixed) lines, the summary won't be
sent, but the headers mentioned above will be used unless they are
removed.
+
-Missing From or In-Reply-To headers will be prompted for.
-+Missing 'From' or 'In-Reply-To' headers will be prompted for.
++Missing `From` or `In-Reply-To` headers will be prompted for.
+
See the CONFIGURATION section for `sendemail.multiEdit`.
@@ Documentation/git-send-email.adoc: This option may be specified multiple times.
--transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::
Specify the transfer encoding to be used to send the message over SMTP.
- 7bit will fail upon encountering a non-ASCII message. quoted-printable
-+ '7bit' will fail upon encountering a non-ASCII message. 'quoted-printable'
++ `7bit` will fail upon encountering a non-ASCII message. `quoted-printable`
can be useful when the repository contains files that contain carriage
- returns, but makes the raw patch email file (as saved from a MUA) much
- harder to inspect manually. base64 is even more fool proof, but also
- even more opaque. auto will use 8bit when possible, and quoted-printable
- otherwise.
+ returns, but makes the raw patch email file (as saved from an MUA) much
-+ harder to inspect manually. 'base64' is even more fool proof, but also
-+ even more opaque. 'auto' will use '8bit' when possible, and
-+ 'quoted-printable' otherwise.
++ harder to inspect manually. `base64` is even more fool proof, but also
++ even more opaque. `auto` will use `8bit` when possible, and
++ `quoted-printable` otherwise.
+
Default is the value of the `sendemail.transferEncoding` configuration
--value; if that is unspecified, default to `auto`.
-+value; if that is unspecified, default to 'auto'.
+ value; if that is unspecified, default to `auto`.
--xmailer::
--no-xmailer::
- Add (or prevent adding) the "X-Mailer:" header. By default,
-+ Add (or prevent adding) the 'X-Mailer:' header. By default,
++ Add (or prevent adding) the `X-Mailer:` header. By default,
the header is added, but it can be turned off by setting the
`sendemail.xmailer` configuration variable to `false`.
@@ Documentation/git-send-email.adoc: Sending
+ --envelope-sender=<address>::
Specify the envelope sender used to send the emails.
This is useful if your default address is not the address that is
- subscribed to a list. In order to use the 'From' address, set the
+- subscribed to a list. In order to use the 'From' address, set the
- value to "auto". If you use the sendmail binary, you must have
- suitable privileges for the -f parameter. Default is the value of the
++ subscribed to a list. In order to use the `From` address, set the
+ value to `auto`. If you use the `sendmail` binary, you must have
+ suitable privileges for the `-f` parameter. Default is the value of the
`sendemail.envelopeSender` configuration variable; if that is
@@ Documentation/git-send-email.adoc: Sending
--smtp-encryption=<encryption>::
Specify in what way encrypting begins for the SMTP connection.
-@@ Documentation/git-send-email.adoc: Sending
+- Valid values are 'ssl' and 'tls'. Any other value reverts to plain
++ Valid values are `ssl` and `tls`. Any other value reverts to plain
+ (unencrypted) SMTP, which defaults to port 25.
+ Despite the names, both values will use the same newer version of TLS,
+- but for historic reasons have these names. 'ssl' refers to "implicit"
++ but for historic reasons have these names. `ssl` refers to "implicit"
+ encryption (sometimes called SMTPS), that uses port 465 by default.
+- 'tls' refers to "explicit" encryption (often known as STARTTLS),
++ `tls` refers to "explicit" encryption (often known as STARTTLS),
+ that uses port 25 by default. Other ports might be used by the SMTP
+ server, which are not the default. Commonly found alternative port for
+- 'tls' and unencrypted is 587. You need to check your provider's
++ `tls` and unencrypted is 587. You need to check your provider's
+ documentation or your server configuration to make sure
+ for your own case. Default is the value of `sendemail.smtpEncryption`.
+
--smtp-domain=<FQDN>::
Specifies the Fully Qualified Domain Name (FQDN) used in the
HELO/EHLO command to the SMTP server. Some servers require the
@@ Documentation/git-send-email.adoc: instead.
to pass to the server. Likewise, different lines in the configuration files
must be used for each option.
-@@ Documentation/git-send-email.adoc: must be used for each option.
+ --smtp-ssl::
+- Legacy alias for '--smtp-encryption ssl'.
++ Legacy alias for `--smtp-encryption ssl`.
+
--smtp-ssl-cert-path::
Path to a store of trusted CA certificates for SMTP SSL/TLS
certificate validation (either a directory that has been processed
@@ Documentation/git-send-email.adoc: Automating
--no-cc::
--no-bcc::
- Clears any list of "To:", "Cc:", "Bcc:" addresses previously
-+ Clears any list of 'To:', 'Cc:', 'Bcc:' addresses previously
++ Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously
set via config.
--no-identity::
@@ Documentation/git-send-email.adoc: Automating
--to-cmd=<command>::
Specify a command to execute once per patch file which
- should generate patch file specific "To:" entries.
-+ should generate patch file specific 'To:' entries.
++ should generate patch file specific `To:` entries.
Output of this command must be single email address per line.
- Default is the value of 'sendemail.toCmd' configuration value.
+ Default is the value of `sendemail.toCmd` configuration value.
@@ Documentation/git-send-email.adoc: Automating
--cc-cmd=<command>::
Specify a command to execute once per patch file which
- should generate patch file specific "Cc:" entries.
-+ should generate patch file specific 'Cc:' entries.
++ should generate patch file specific `Cc:` entries.
Output of this command must be single email address per line.
Default is the value of `sendemail.ccCmd` configuration value.
@@ Documentation/git-send-email.adoc: Automating
this, it is recommended that the first file given be an overview of the
entire patch series. Disabled by default, but the `sendemail.chainReplyTo`
@@ Documentation/git-send-email.adoc: Automating
+
+ --identity=<identity>::
+ A configuration identity. When given, causes values in the
+- 'sendemail.<identity>' subsection to take precedence over
+- values in the 'sendemail' section. The default identity is
++ `sendemail.<identity>` subsection to take precedence over
++ values in the `sendemail` section. The default identity is
the value of `sendemail.identity`.
--[no-]signed-off-by-cc::
- If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the
- cc list. Default is the value of `sendemail.signedOffByCc` configuration
- value; if that is unspecified, default to --signed-off-by-cc.
-+ If this is set, add emails found in the `Signed-off-by` trailer or 'Cc:'
++ If this is set, add emails found in the `Signed-off-by` trailer or `Cc:`
+ lines to the cc list. Default is the value of `sendemail.signedOffByCc`
+ configuration value; if that is unspecified, default to
+ `--signed-off-by-cc`.
--[no-]cc-cover::
- If this is set, emails found in Cc: headers in the first patch of
-+ If this is set, emails found in 'Cc:' headers in the first patch of
++ If this is set, emails found in `Cc:` headers in the first patch of
the series (typically the cover letter) are added to the cc list
- for each email set. Default is the value of 'sendemail.ccCover'
- configuration value; if that is unspecified, default to --no-cc-cover.
@@ Documentation/git-send-email.adoc: Automating
--[no-]to-cover::
- If this is set, emails found in To: headers in the first patch of
-+ If this is set, emails found in 'To:' headers in the first patch of
++ If this is set, emails found in `To:` headers in the first patch of
the series (typically the cover letter) are added to the to list
- for each email set. Default is the value of 'sendemail.toCover'
- configuration value; if that is unspecified, default to --no-to-cover.
@@ Documentation/git-send-email.adoc: Automating
--suppress-cc=<category>::
Specify an additional category of recipients to suppress the
-@@ Documentation/git-send-email.adoc: Automating
+ auto-cc of:
+ +
+ --
+-- 'author' will avoid including the patch author.
+-- 'self' will avoid including the sender.
+-- 'cc' will avoid including anyone mentioned in Cc lines in the patch header
+- except for self (use 'self' for that).
+-- 'bodycc' will avoid including anyone mentioned in Cc lines in the
+- patch body (commit message) except for self (use 'self' for that).
+-- 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except
+- for self (use 'self' for that).
+-- 'misc-by' will avoid including anyone mentioned in Acked-by,
++- `author` will avoid including the patch author.
++- `self` will avoid including the sender.
++- `cc` will avoid including anyone mentioned in Cc lines in the patch header
++ except for self (use `self` for that).
++- `bodycc` will avoid including anyone mentioned in Cc lines in the
++ patch body (commit message) except for self (use `self` for that).
++- `sob` will avoid including anyone mentioned in the Signed-off-by trailers except
++ for self (use `self` for that).
++- `misc-by` will avoid including anyone mentioned in Acked-by,
+ Reviewed-by, Tested-by and other "-by" lines in the patch body,
+- except Signed-off-by (use 'sob' for that).
+-- 'cccmd' will avoid running the --cc-cmd.
+-- 'body' is equivalent to 'sob' + 'bodycc' + 'misc-by'.
+-- 'all' will suppress all auto cc values.
++ except Signed-off-by (use `sob` for that).
++- `cccmd` will avoid running the --cc-cmd.
++- `body` is equivalent to `sob` + `bodycc` + `misc-by`.
++- `all` will suppress all auto cc values.
--
+
Default is the value of `sendemail.suppressCc` configuration value; if
-that is unspecified, default to 'self' if --suppress-from is
-specified, as well as 'body' if --no-signed-off-cc is specified.
-+that is unspecified, default to 'self' if `--suppress-from` is
-+specified, as well as 'body' if `--no-signed-off-cc` is specified.
++that is unspecified, default to `self` if `--suppress-from` is
++specified, as well as `body` if `--no-signed-off-cc` is specified.
--[no-]suppress-from::
- If this is set, do not add the From: address to the cc: list.
-+ If this is set, do not add the 'From:' address to the 'Cc:' list.
++ If this is set, do not add the `From:` address to the `Cc:` list.
Default is the value of `sendemail.suppressFrom` configuration
- value; if that is unspecified, default to --no-suppress-from.
+ value; if that is unspecified, default to `--no-suppress-from`.
--[no-]thread::
- If this is set, the In-Reply-To and References headers will be
-+ If this is set, the 'In-Reply-To' and 'References' headers will be
++ If this is set, the `In-Reply-To` and `References` headers will be
added to each email sent. Whether each mail refers to the
- previous email (`deep` threading per 'git format-patch'
+ previous email (`deep` threading per `git format-patch`
@@ Documentation/git-send-email.adoc: Administering
--
-- 'always' will always confirm before sending
-- 'never' will never confirm before sending
-+- 'always' will always confirm before sending.
-+- 'never' will never confirm before sending.
- - 'cc' will confirm before sending when send-email has automatically
+-- 'cc' will confirm before sending when send-email has automatically
- added addresses from the patch to the Cc list
-+ added addresses from the patch to the Cc list.
- - 'compose' will confirm before sending the first message when using --compose.
+-- 'compose' will confirm before sending the first message when using --compose.
-- 'auto' is equivalent to 'cc' + 'compose'
-+- 'auto' is equivalent to 'cc' + 'compose'.
++- `always` will always confirm before sending.
++- `never` will never confirm before sending.
++- `cc` will confirm before sending when send-email has automatically
++ added addresses from the patch to the Cc list.
++- `compose` will confirm before sending the first message when using --compose.
++- `auto` is equivalent to `cc` + `compose`.
--
+
Default is the value of `sendemail.confirm` configuration value; if that
+-is unspecified, default to 'auto' unless any of the suppress options
+-have been specified, in which case default to 'compose'.
++is unspecified, default to `auto` unless any of the suppress options
++have been specified, in which case default to `compose`.
+
+ --dry-run::
+ Do everything except actually send the emails.
@@ Documentation/git-send-email.adoc: have been specified, in which case default to 'compose'.
When an argument may be understood either as a reference or as a file name,
choose to understand it as a format-patch argument (`--format-patch`)
@@ Documentation/git-send-email.adoc: have been specified, in which case default to
all that is output.
--[no-]validate::
+@@ Documentation/git-send-email.adoc: have been specified, in which case default to 'compose'.
+ * Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
+ * Warn of patches that contain lines longer than
+ 998 characters unless a suitable transfer encoding
+- ('auto', 'base64', or 'quoted-printable') is used;
++ (`auto`, `base64`, or `quoted-printable`) is used;
+ this is due to SMTP limits as described by
+ https://www.ietf.org/rfc/rfc5322.txt.
+ --
+@@ Documentation/git-send-email.adoc: Information
+ Instead of the normal operation, dump the shorthand alias names from
+ the configured alias file(s), one per line in alphabetical order. Note
+ that this only includes the alias name and not its expanded email addresses.
+- See 'sendemail.aliasesFile' for more information about aliases.
++ See `sendemail.aliasesFile` for more information about aliases.
+
+ --translate-aliases::
+ Instead of the normal operation, read from standard input and
+ interpret each line as an email alias. Translate it according to the
+ configured alias file(s). Output each translated name and email
+- address to standard output, one per line. See 'sendemail.aliasFile'
++ address to standard output, one per line. See `sendemail.aliasFile`
+ for more information about aliases.
+
+ CONFIGURATION
@@ Documentation/git-send-email.adoc: edit `~/.gitconfig` to specify your account settings:
----
2: a05958c7aa = 3: 4916bde9e5 docs: remove credential helper links for emails from gitcredentials
3: e2dd5d9d81 = 4: 66c75485e2 docs: make the purpose of using app password for Gmail more clear in send-email
--
2.49.0.639.ge2dd5d9d81
