Hi all,
This patch series included three 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 removed 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.
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/2005v3: - 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. NOTE: I have not used `` for Headers in the second patch. I think its ok
to deviate a bit from the rules and not be army men here. If I
markdown them as code, the whole doc will be filled with codestyled
blocks, and I think, these headers demand "different treatement"
than rest other code and variables. Codeblocks everywhere are more
of hurting the readability of the documentation than helping it.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 | 8 +-
Documentation/git-send-email.adoc | 203 +++++++++++++++-------------
Documentation/gitcredentials.adoc | 4 -
3 files changed, 114 insertions(+), 101 deletions(-)
Range-diff against v5:
-: ---------- > 1: 2c47cc5396 docs: add credential helper for yahoo and link Google's sendgmail tool
1: bc1d0471ca ! 2: 20da5d6a58 docs: improve formatting in git-send-email documentation
@@ Commit message
The current documentation for git-send-email had an inconsistent use of
"", ``, and '' for quoting. This commit improves the formatting by
- using the same style throughout the documentation.
-
- Also, at some places, minor grammatical errors were fixed, and some
- non existent links were removed.
+ using the same style throughout the documentation. Missing full stops
+ have also been added at some places.
Finally, the cpan links of necessary perl modules have been added to
make their installation easier.
+ While at it, the unecessary use of $ with <num> and <int> placeholders
+ has also been removed.
+
Signed-off-by: Aditya Garg <gargaditya08@live.com>
## Documentation/config/sendemail.adoc ##
@@ Documentation/git-send-email.adoc: This option may be specified multiple times.
+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.
+
@@ Documentation/git-send-email.adoc: must be used for each option.
Path to a store of trusted CA certificates for SMTP SSL/TLS
certificate validation (either a directory that has been processed
- by 'c_rehash', or a single file containing one or more PEM format
-- certificates concatenated together: see verify(1) -CAfile and
-- -CApath for more information on these). Set it to an empty string
+ by `c_rehash`, or a single file containing one or more PEM format
-+ certificates concatenated together). Set it to an empty string
+ certificates concatenated together: see verify(1) -CAfile and
+ -CApath for more information on these). Set it to an empty string
to disable certificate verification. Defaults to the value of the
- `sendemail.smtpSSLCertPath` configuration variable, if set, or the
- backing SSL library's compiled-in default otherwise (which should
@@ Documentation/git-send-email.adoc: must be used for each option.
connection and authentication problems.
@@ Documentation/git-send-email.adoc: must be used for each option.
- and reconnect, to work around such a limit. You may want to
- use some form of credential helper to avoid having to retype
- your password every time this happens. Defaults to the
-+ sending `$<num>` messages and wait for a few seconds
++ sending _<num>_ messages and wait for a few seconds
+ (see `--relogin-delay`) and reconnect, to work around such a limit.
+ You may want to use some form of credential helper to avoid having to
+ retype your password every time this happens. Defaults to the
@@ Documentation/git-send-email.adoc: must be used for each option.
--relogin-delay=<int>::
- Waiting $<int> seconds before reconnecting to SMTP server. Used together
- with --batch-size option. Defaults to the `sendemail.smtpReloginDelay`
-+ Waiting `$<int>` seconds before reconnecting to SMTP server. Used together
++ Waiting _<int>_ seconds before reconnecting to SMTP server. Used together
+ with `--batch-size` option. Defaults to the `sendemail.smtpReloginDelay`
configuration variable.
2: b9e41e2492 = 3: a05958c7aa docs: remove credential helper links for emails from gitcredentials
3: a6ad7ac810 ! 4: 0bf48ac27d docs: make the purpose of using app password for Gmail more clear in send-email
@@ Commit message
enabled. Most likely the example was written in the days when Google
allowed using normal passwords without multi-factor authentication.
- This commit clarifies that app passwords are required and suggests using
- OAuth2 if the user does not want to enable multi-factor authentication.
+ Clarify that regular passwords do not work for Gmail and app-passwords
+ are the only way for basic authentication. Also encourage users to use
+ OAuth2 as a more secure alternative.
+
+ While at it, also prefer using the word "mechanism" over "method" for
+ `OAUTHBEARER` and `XOAUTH2` since that is what official docs use.
+
+ Signed-off-by: Aditya Garg <gargaditya08@live.com>
## Documentation/git-send-email.adoc ##
@@ Documentation/git-send-email.adoc: edit `~/.gitconfig` to specify your account settings:
smtpServerPort = 587
----
-+Gmail does not allow using your account password for `git send-email`.
++Gmail does not allow using your regular password for `git send-email`.
If you have multi-factor authentication set up on your Gmail account, you can
generate an app-specific password for use with `git send-email`. Visit
https://security.google.com/settings/security/apppasswords to create it.
-+If you do not want to enable multi-factor authentication, you can use OAuth2.0
-+authentication as described below.
- You can also use OAuth2.0 authentication with Gmail. `OAUTHBEARER` and
- `XOAUTH2` are common methods used for this type of authentication. Gmail
+-You can also use OAuth2.0 authentication with Gmail. `OAUTHBEARER` and
+-`XOAUTH2` are common methods used for this type of authentication. Gmail
+-supports both of them. As an example, if you want to use `OAUTHBEARER`, edit
+-your `~/.gitconfig` file and add `smtpAuth = OAUTHBEARER` to your account
+-settings:
++Alternatively, instead of using an app-specific password, you can use
++OAuth2.0 authentication with Gmail. OAuth2.0 is more secure than
++app-specific passwords, and works regardless of whether you have multi-factor
++authentication set up. `OAUTHBEARER` and `XOAUTH2` are common mechanisms used
++for this type of authentication. Gmail supports both of them. As an example,
++if you want to use `OAUTHBEARER`, edit your `~/.gitconfig` file and add
++`smtpAuth = OAUTHBEARER` to your account settings:
+
+ ----
+ [sendemail]
+@@ Documentation/git-send-email.adoc: settings:
+ smtpAuth = OAUTHBEARER
+ ----
+
+-Alternatively, you can use a tool developed by Google known as
++Another alternative is using a tool developed by Google known as
+ https://github.com/google/gmail-oauth2-tools/tree/master/go/sendgmail[sendgmail]
+ to send emails using `git send-email`.
+
+@@ Documentation/git-send-email.adoc: Use Microsoft Outlook as the SMTP Server
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords.
+ Therefore, OAuth2.0 authentication must be used for Outlook. Also, it only
+-supports `XOAUTH2` authentication method.
++supports `XOAUTH2` authentication mechanism.
+
+ Edit `~/.gitconfig` to specify your account settings for Outlook and use its
+ SMTP server with `git send-email`:Aditya Garg <gargaditya08@live.com>