Auto merge of #7658 - ehuss:doc-git-authentication, r=alexcrichton

Docs: Add an appendix on git authentication.

This adds a short section on how to set up authentication with git.  People seem to occasionally have difficulty with setting it up, so the hope is that this might provide some guidance, and a place for people to get started.  I'm not sure if it will actually be helpful, though.

src/doc/src/SUMMARY.md

@@ -72,3 +72,4 @@
 
 * [FAQ](faq.md)
 * [Appendix: Glossary](appendix/glossary.md)
+* [Appendix: Git Authentication](appendix/git-authentication.md)

src/doc/src/appendix/git-authentication.md

@@ -0,0 +1,56 @@
+# Git Authentication
+
+Cargo supports some forms of authentication when using git dependencies and
+registries. This appendix contains some information for setting up git
+authentication in a way that works with Cargo.
+
+If you need other authentication methods, the [`net.git-fetch-with-cli`]
+config value can be set to cause Cargo to execute the `git` executable to
+handle fetching remote repositories instead of using the built-in support.
+This can be enabled with the `CARGO_NET_GIT_FETCH_WITH_CLI=true` environment
+variable.
+
+## HTTPS authentication
+
+HTTPS authentication requires the [`credential.helper`] mechanism. There are
+multiple credential helpers, and you specify the one you want to use in your
+global git configuration file.
+
+```ini
+# ~/.gitconfig
+
+[credential]
+helper = store
+```
+
+Cargo does not ask for passwords, so for most helpers you will need to give
+the helper the initial username/password before running Cargo. One way to do
+this is to run `git clone` of the private git repo and enter the
+username/password.
+
+> **Tip:**<br>
+> macOS users may want to consider using the osxkeychain helper.<br>
+> Windows users may want to consider using the [GCM] helper.
+
+> **Note:** Windows users will need to make sure that the `sh` shell is
+> available in your `PATH`. This typically is available with the Git for
+> Windows installation.
+
+## SSH authentication
+
+SSH authentication requires `ssh-agent` to be running to acquire the SSH key.
+Make sure the appropriate environment variables are set up (`SSH_AUTH_SOCK` on
+most Unix-like systems), and that the correct keys are added (with `ssh-add`).
+Windows uses Pageant for SSH authentication.
+
+> **Note:** Cargo does not support git's shorthand SSH URLs like
+> `[email protected]/user/repo.git`. Use a full SSH URL like
+> `ssh://[email protected]/user/repo.git`.
+>
+> **Note:** SSH configuration files (like OpenSSH's `~/.ssh/config`) are not
+> used by Cargo's built-in SSH library. More advanced requirements should use
+> [`net.git-fetch-with-cli`].
+
+[`credential.helper`]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage
+[`net.git-fetch-with-cli`]: ../reference/config.md#netgit-fetch-with-cli
+[GCM]: https://github.com/Microsoft/Git-Credential-Manager-for-Windows/

src/doc/src/reference/config.md

@@ -538,7 +538,9 @@ indexes and git dependencies. If `false`, then it uses a built-in `git`
 library.
 
 Setting this to `true` can be helpful if you have special authentication
-requirements that Cargo does not support.
+requirements that Cargo does not support. See [Git
+Authentication](../appendix/git-authentication.md) for more information about
+setting up git authentication.
 
 ##### `net.offline`
 * Type: boolean

src/doc/src/reference/specifying-dependencies.md

@@ -142,6 +142,10 @@ the latest commit on a branch named `next`:
 rand = { git = "https://github.com/rust-lang-nursery/rand", branch = "next" }
 ```
 
+See [Git Authentication] for help with git authentication for private repos.
+
+[Git Authentication]: ../appendix/git-authentication.md
+
 ### Specifying path dependencies
 
 Over time, our `hello_world` package from [the guide](../guide/index.md) has