Docs: Add an appendix on git authentication.

Author: ehuss

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
+> `git@example.com/user/repo.git`. Use a full SSH URL like
+> `ssh://git@example.com/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