Docs: Add an appendix on git authentication.

diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md
index c07392647c37509ab50dbc99fa47c2a5c423a4e1..595fd15d6eee11813c06a3e9ddde8770ccba8663 100644 (file)
--- a/src/doc/src/SUMMARY.md
+++ b/src/doc/src/SUMMARY.md
@@ -72,3 +72,4 @@
 
 * [FAQ](faq.md)
 * [Appendix: Glossary](appendix/glossary.md)
+* [Appendix: Git Authentication](appendix/git-authentication.md)

diff --git a/src/doc/src/appendix/git-authentication.md b/src/doc/src/appendix/git-authentication.md
new file mode 100644 (file)
index 0000000..c77e0e0
--- /dev/null
+++ b/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/

diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
index 054a5b94db911adad71fa3dfffdb7c0a51a154d9..e580e9158b5981a64d07a72d98d650cb15f5a7b6 100644 (file)
--- a/src/doc/src/reference/config.md
+++ b/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

diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md
index 44a3668cde8ae3f217165f8ca6c0931536b3de6d..d1b28a56d0c3dc27b8dccb35fdf287a15ee0b7d9 100644 (file)
--- a/src/doc/src/reference/specifying-dependencies.md
+++ b/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