From 3229b01ff172f343ba58d5425b8dced0f9859dd6 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 16 Dec 2018 10:08:15 -0800
Subject: [PATCH 1/5] Document registries.

---
 src/doc/src/SUMMARY.md              |   1 +
 src/doc/src/reference/registries.md | 572 ++++++++++++++++++++++++++++
 2 files changed, 573 insertions(+)
 create mode 100644 src/doc/src/reference/registries.md

diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md
index 5b5293be877..3a69c0a312d 100644
--- a/src/doc/src/SUMMARY.md
+++ b/src/doc/src/SUMMARY.md
@@ -27,6 +27,7 @@
     * [Package ID Specifications](reference/pkgid-spec.md)
     * [Source Replacement](reference/source-replacement.md)
     * [External Tools](reference/external-tools.md)
+    * [Registries](reference/registries.md)
     * [Unstable Features](reference/unstable.md)
 
 * [Cargo Commands](commands/index.md)
diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md
new file mode 100644
index 00000000000..45a3481e85f
--- /dev/null
+++ b/src/doc/src/reference/registries.md
@@ -0,0 +1,572 @@
+## Registries
+
+Cargo installs crates and fetches dependencies from a "registry". The default
+registry is [crates.io]. A registry contains an "index" which contains a
+searchable list of available crates. A registry may also provide a web API to
+support publishing new crates directly from Cargo. The registry provides
+permanent access to all versions of a package that have been published to it.
+
+> Note: If you are interested in mirroring or vendoring an existing registry,
+> take a look at [Source Replacement].
+
+### Using an Alternate Registry
+
+To use a registry other than [crates.io], the name and URL of the registry
+must be added to a [`.cargo/config` file][config]. The `registries` table
+has a key for each registry, for example:
+
+```toml
+[registries]
+my-registry = { index = "https://my-intranet:8080/git/index" }
+```
+
+The `index` key should be a URL to a git repository with the registry's index.
+Dependencies in a manifest can then refer to the name of the registry with the
+`registry` key to tell Cargo to fetch from that registry:
+
+```toml
+# Sample Cargo.toml
+[package]
+name = "my-project"
+version = "0.1.0"
+
+[dependencies]
+other-crate = { version = "1.0", registry = "my-registry" }
+```
+
+As with most config values, the index may be specified with an environment
+variable instead of a config file. For example, setting the following
+environment variable will accomplish the same thing as defining a config file:
+
+```
+CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index
+```
+
+> Note: [crates.io] does not accept packages that use other registries.
+
+### Publishing to an Alternate Registry
+
+If the registry supports web API access, then packages can be published
+directly to the registry from Cargo. Several of Cargo's commands such as
+`cargo publish` take a `--registry` command-line flag to indicate which
+registry to use. For example, to publish the package in the current directory:
+
+1. `cargo login --registry=my-registry`
+
+    This only needs to be done once. You must enter the secret API token
+    retrieved from the registry's website. Alternatively the token may be
+    passed directly to the `publish` command with the `--token` command-line
+    flag or and environment variable with the name of the registry such as
+    `CARGO_REGISTRIES_MY_REGISTRY_TOKEN`.
+
+2. `cargo publish --registry=my-registry`
+
+Instead of always passing the `--registry` command-line option, the default
+registry may be set in [`.cargo/config`][config] with the `registry.default`
+key.
+
+Setting the `package.publish` key in `Cargo.toml` manifest restricts which
+registries the package is allowed to be published to. This is useful to
+prevent accidentally publishing a closed-source package to [crates.io]. The
+value may be a list of registry names, for example:
+
+```toml
+[package]
+# ...
+publish = ["my-registry"]
+```
+
+The `publish` value may also be `false` to restrict all publishing, which is
+the same as an empty list.
+
+The authentication information saved by `cargo login` is stored in the
+`credentials` file in the Cargo home directory (default `$HOME/.cargo`). It
+has a separate table for each registry, for example:
+
+```toml
+[registries.my-registry]
+token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy"
+```
+
+### Running a Registry
+
+A minimal registry can be implemented by having a git repository that contains
+an index, and a server that contains the compressed `.crate` files created by
+`cargo package`. Users won't be able to use Cargo to publish to it, but this
+may be sufficient for closed environments.
+
+A full-featured registry that supports publishing will additionally need to
+have a web API service that conforms to the API used by Cargo. The web API is
+documented below.
+
+### Index Format
+
+The following defines the format of the index. New features are occasionally
+added, which are only understood starting with the version of Cargo that
+introduced them. Older versions of Cargo may not be able to use packages that
+make use of new features. However, the format for older packages should not
+change, so older versions of Cargo should be able to use them.
+
+The index is stored in a git repository so that Cargo can efficiently fetch
+incremental updates to the index. In the root of the repository is a file
+named `config.json` which contains JSON information used by Cargo for
+accessing the registry. This is an example of what the [crates.io] config file
+looks like:
+
+```javascript
+{
+    "dl": "https://crates.io/api/v1/crates",
+    "api": "https://crates.io"
+}
+```
+
+The keys are:
+- `dl`: This is the URL for downloading crates listed in the index. The value
+  may have the markers `{crate}` and `{version}` which are replaced with the
+  name and version of the crate to download. If the markers are not present,
+  then the value `/{crate}/{version}/download` is appended to the end.
+- `api`: This is the base URL for the web API. This key is optional, and if it
+  is not specified, commands such as `cargo publish` will not work. The web API
+  is described below.
+
+The download endpoint should send the `.crate` file for the requested package.
+Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2.
+The exact specifics of TLS support depend on the platform that Cargo is
+running on, the version of Cargo, and how it was compiled.
+
+The rest of the index repository contains one file for each package, where the
+filename is the name of the package in lowercase. Each version of the package
+has a separate line in the file. The files are organized in a tier of
+directories:
+
+- Packages with 1 letter names are placed in a directory named `1`.
+- Packages with 2 letter names are placed in a directory named `2`.
+- Packages with 3 letter names are placed in the directory `3/{first-letter}`
+  where `{first-letter}` is the first letter of the package name.
+- All other packages are stored in directories named
+  `{first-two}/{second-two}` where the top directory is the first two letters
+  of the package name, and the next subdirectory is the third and fourth
+  letters of the package name. For example, `cargo` would be stored in a file
+  named `ca/rg/cargo`.
+
+> Note: Although the index filenames are in lowercase, the fields in
+> `Cargo.toml` manifests and the index JSON data are case-sensitive and may
+> contain upper and lower case characters.
+
+Each line in a package file contains a JSON object that describes a published
+version of the package. The following is a pretty-printed example with comments
+explaining the format of the entry.
+
+```javascript
+{
+    // The name of the package.
+    // This must contain alphanumeric, `-`, or `_` characters.
+    "name": "foo",
+    // The version of the package this row is describing.
+    "vers": "0.1.0",
+    // Array of direct dependencies of the package.
+    "deps": [
+        {
+            // Name of the dependency.
+            // If the dependency is renamed from the original package name,
+            // this is the new name. The original package name is stored in
+            // the `package` field.
+            "name": "rand",
+            // The semver requirement for this dependency.
+            "req": "^0.6",
+            // Array of features (as strings) enabled for this dependency.
+            "features": ["i128_support"],
+            // Boolean of whether or not this is an optional dependency.
+            "optional": false,
+            // Boolean of whether or not default features are enabled.
+            "default_features": true,
+            // The target platform for the dependency.
+            // null if not a target dependency.
+            // Otherwise, a string such as "cfg(windows)".
+            "target": null,
+            // The dependency kind.
+            // "dev", "build", or "normal".
+            // Note: this is a required field, but a small number of entries
+            // exist in the crates.io index with either a missing or null
+            // `kind` field due to implementation bugs.
+            "kind": "normal",
+            // The URL of the index of the registry where this dependency is
+            // from as a string. If not specified or null, it is assumed the
+            // dependency is in the current registry.
+            "registry": null,
+            // If the dependency is renamed, this is a string of the actual
+            // package name. If not specified or null, this dependency is not
+            // renamed.
+            "package": null,
+        }
+    ],
+    // A SHA256 checksum of the `.crate` file.
+    "cksum": "d867001db0e2b6e0496f9fac96930e2d42233ecd3ca0413e0753d4c7695d289c",
+    // Set of features defined for the package.
+    // Each feature maps to an array of features or dependencies it enables.
+    "features": {
+        "extras": ["rand/simd_support"]
+    },
+    // Boolean of whether or not this version has been yanked.
+    "yanked": false,
+    // The `links` string value from the package's manifest, or null if not
+    // specified. This field is optional and defaults to null.
+    "links": null
+}
+```
+
+The JSON objects should not be modified after they are added except for the
+`yanked` field whose value may change at any time.
+
+Registries may want to consider enforcing limitations on package names added
+to their index. Cargo itself allows names with any [alphanumeric], `-`, or `_`
+character. For example, [crates.io] imposes relatively strict limitations,
+such as requiring it to be a valid Rust identifier, only allowing ASCII
+characters, under a specific length, and rejects reserved names such as
+Windows special filenames like "nul".
+
+### Web API
+
+A registry may host a web API at the location defined in `config.json` to
+support any of the actions listed below.
+
+Cargo includes the `Authorization` header for requests that require
+authentication. The header value is the API token. The server should respond
+with a 403 response code if the token is not valid. Users are expected to
+visit the registry's website to obtain a token, and Cargo can store the token
+using the `cargo login` command, or by passing the token on the command-line.
+
+Responses use a 200 response code for both success and errors. Cargo looks at
+the JSON response to determine if there was success or failure. Failure
+responses have a JSON object with the following structure:
+
+```javascript
+{
+    // Array of errors to display to the user.
+    "errors": [
+        {
+            // The error message as a string.
+            "detail": "error message text"
+        }
+    ]
+}
+```
+
+Servers may also respond with a 404 response code to indicate the requested
+resource is not found (for example, an unknown crate name). However, using a
+200 response with an `errors` object allows a registry to provide a more
+detailed error message if desired.
+
+For backwards compatibility, servers should ignore any unexpected query
+parameters or JSON fields. If a JSON field is missing, it should be assumed to
+be null. The endpoints are versioned with the `v1` component of the path, and
+Cargo is responsible for handling backwards compatibility fallbacks should any
+be required in the future.
+
+Cargo sets the following headers for all requests:
+
+- `Content-Type`: `application/json`
+- `Accept`: `application/json`
+- `User-Agent`: The Cargo version such as `cargo 1.32.0 (8610973aa
+  2019-01-02)`. This may be modified by the user in a configuration value.
+  Added in 1.29.
+
+#### Publish
+
+- Endpoint: `/api/v1/crates/new`
+- Method: PUT
+- Authorization: Included
+
+The publish endpoint is used to publish a new version of a crate. The server
+should validate the crate, make it available for download, and add it to the
+index.
+
+The body of the data sent by Cargo is:
+
+- 32-bit unsigned little-endian integer of the length of JSON data.
+- Metadata of the package as a JSON object.
+- 32-bit unsigned little-endian integer of the length of the `.crate` file.
+- The `.crate` fle.
+
+The following is a commented example of the JSON object. Some notes of some
+restrictions imposed by [crates.io] are included only to illustrate some
+suggestions on types of validation that may be done, and should not be
+considered as an exhaustive list of restrictions [crates.io] imposes.
+
+```javascript
+{
+    // The name of the package.
+    "name": "foo",
+    // The version of the package being published.
+    "vers": "0.1.0",
+    // Array of direct dependencies of the package.
+    "deps": [
+        {
+            // Name of the dependency.
+            // If the dependency is renamed from the original package name,
+            // this is the original name. The new package name is stored in
+            // the `explicit_name_in_toml` field.
+            "name": "rand",
+            // The semver requirement for this dependency.
+            "version_req": "^0.6",
+            // Array of features (as strings) enabled for this dependency.
+            "features": ["i128_support"],
+            // Boolean of whether or not this is an optional dependency.
+            "optional": false,
+            // Boolean of whether or not default features are enabled.
+            "default_features": true,
+            // The target platform for the dependency.
+            // null if not a target dependency.
+            // Otherwise, a string such as "cfg(windows)".
+            "target": null,
+            // The dependency kind.
+            // "dev", "build", or "normal".
+            "kind": "normal",
+            // The URL of the index of the registry where this dependency is
+            // from as a string. If not specified or null, it is assumed the
+            // dependency is in the current registry.
+            "registry": null,
+            // If the dependency is renamed, this is a string of the new
+            // package name. If not specified or null, this dependency is not
+            // renamed.
+            "explicit_name_in_toml": null,
+        }
+    ],
+    // Set of features defined for the package.
+    // Each feature maps to an array of features or dependencies it enables.
+    // Cargo does not impose limitations on feature names, but crates.io
+    // requires alphanumeric ASCII, `_` or `-` characters.
+    "features": {
+        "extras": ["rand/simd_support"]
+    },
+    // List of strings of the authors.
+    // May be empty. crates.io requires at least one entry.
+    "authors": ["Alice <a@example.com>"],
+    // Description field from the manifest.
+    // May be null. crates.io requires at least some content.
+    "description": null,
+    // String of the URL to the website for this package's documentation.
+    // May be null.
+    "documentation": null,
+    // String of the URL to the website for this package's home page.
+    // May be null.
+    "homepage": null,
+    // String of the content of the README file.
+    // May be null.
+    "readme": null,
+    // String of a relative path to a README file in the crate.
+    // May be null.
+    "readme_file": null,
+    // Array of strings of keywords for the package.
+    "keywords": [],
+    // Array of strings of categories for the package.
+    "categories": [],
+    // String of the license for the package.
+    // May be null. crates.io requires either `license` or `license_file` to be set.
+    "license": null,
+    // String of a relative path to a license file in the crate.
+    // May be null.
+    "license_file": null,
+    // String of the URL to the website for the source repository of this package.
+    // May be null.
+    "repository": null,
+    // Optional object of "status" badges. Each value is an object of
+    // arbitrary string to string mappings.
+    // crates.io has special interpretation of the format of the badges.
+    "badges": {
+        "travis-ci": {
+            "branch": "master",
+            "repository": "rust-lang/cargo"
+        }
+    },
+    // The `links` string value from the package's manifest, or null if not
+    // specified. This field is optional and defaults to null.
+    "links": null,
+}
+```
+
+A successful response includes the JSON object:
+
+```javascript
+{
+    // Optional object of warnings to display to the user.
+    "warnings": {
+        // Array of strings of categories that are invalid and ignored.
+        "invalid_categories": [],
+        // Array of strings of badge names that are invalid and ignored.
+        "invalid_badges": [],
+        // Array of strings of arbitrary warnings to display to the user.
+        "other": []
+    }
+}
+```
+
+#### Yank
+
+- Endpoint: `/api/v1/crates/{crate_name}/{version}/yank`
+- Method: DELETE
+- Authorization: Included
+
+The yank endpoint will set the `yank` field of the given version of a crate to
+`true` in the index.
+
+A successful response includes the JSON object:
+
+```javascript
+{
+    // Indicates the delete succeeded, always true.
+    "ok": true,
+}
+```
+
+#### Unyank
+
+- Endpoint: `/api/v1/crates/{crate_name}/{version}/unyank`
+- Method: PUT
+- Authorization: Included
+
+The unyank endpoint will set the `yank` field of the given version of a crate
+to `false` in the index.
+
+A successful response includes the JSON object:
+
+```javascript
+{
+    // Indicates the delete succeeded, always true.
+    "ok": true,
+}
+```
+
+#### Owners
+
+Cargo does not have an inherent notion of users and owners, but it does
+provide the `owner` command to assist managing who has authorization to
+control a crate. It is up to the registry to decide exactly how users and
+owners are handled. See the [publishing documentation] for a description of
+how [crates.io] handles owners via GitHub users and teams.
+
+##### Owners: List
+
+- Endpoint: `/api/v1/crates/{crate_name}/owners`
+- Method: GET
+- Authorization: Included
+
+The owners endpoint returns a list of owners of the crate.
+
+A successful response includes the JSON object:
+
+```javascript
+{
+    // Array of owners of the crate.
+    "users": [
+        {
+            // Unique unsigned 32-bit integer of the owner.
+            "id": 70,
+            // The unique username of the owner.
+            "login": "github:rust-lang:core",
+            // Name of the owner.
+            // This is optional and may be null.
+            "name": "Core",
+        }
+    ]
+}
+```
+
+##### Owners: Add
+
+- Endpoint: `/api/v1/crates/{crate_name}/owners`
+- Method: PUT
+- Authorization: Included
+
+A PUT request will add a new owner to a crate. The request should include the
+following JSON object:
+
+```javascript
+{
+    // Array of `login` strings of owners to add.
+    "users": ["login_name"]
+}
+```
+
+A successful response includes the JSON object:
+
+```javascript
+{
+    // Indicates the add succeeded, always true.
+    "ok": true,
+    // A string to be displayed to the user.
+    "msg": "user ehuss has been invited to be an owner of crate cargo"
+}
+```
+
+##### Owners: Remove
+
+- Endpoint: `/api/v1/crates/{crate_name}/owners`
+- Method: DELETE
+- Authorization: Included
+
+A DELETE request will remove an owner from a crate. The request should include
+the following JSON object:
+
+```javascript
+{
+    // Array of `login` strings of owners to remove.
+    "users": ["login_name"]
+}
+```
+
+A successful response includes the JSON object:
+
+```javascript
+{
+    // Indicates the remove succeeded, always true.
+    "ok": true
+}
+```
+
+#### Search
+
+- Endpoint: `/api/v1/crates/crates`
+- Method: GET
+- Query Parameters:
+    - `q`: The search query string.
+    - `per_page`: Number of results, default 10, max 100.
+
+The search request will perform a search for crates, using criteria defined on
+the server.
+
+A successful response includes the JSON object:
+
+```javascript
+{
+    // Array of results.
+    "crates": [
+        {
+            // Name of the crate.
+            "name": "rand",
+            // The highest version available.
+            "max_version": "0.6.1",
+            // Textual description of the crate.
+            "description": "Random number generators and other randomness functionality.\n",
+        }
+    ],
+    "meta": {
+        // Total number of results available on the server.
+        "total": 119
+    }
+}
+```
+
+#### Login
+
+- Endpoint: `/me`
+
+The "login" endpoint is not an actual API request. It exists solely for the
+`cargo login` command to display a URL to instruct a user to visit in a web
+browser to log in and retrieve an API token.
+
+[Source Replacement]: reference/source-replacement.html
+[alphanumeric]: https://doc.rust-lang.org/std/primitive.char.html#method.is_alphanumeric
+[config]: reference/config.html
+[crates.io]: https://crates.io/
+[publishing documentation]: reference/publishing.html#cargo-owner

From 8b27a7bda02f9206a7855a0200d629d121984db2 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sat, 26 Jan 2019 11:08:17 -0800
Subject: [PATCH 2/5] Update for review comments.

---
 src/doc/src/reference/registries.md | 68 ++++++++++++++++-------------
 1 file changed, 37 insertions(+), 31 deletions(-)

diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md
index 45a3481e85f..79ac04451b8 100644
--- a/src/doc/src/reference/registries.md
+++ b/src/doc/src/reference/registries.md
@@ -3,17 +3,16 @@
 Cargo installs crates and fetches dependencies from a "registry". The default
 registry is [crates.io]. A registry contains an "index" which contains a
 searchable list of available crates. A registry may also provide a web API to
-support publishing new crates directly from Cargo. The registry provides
-permanent access to all versions of a package that have been published to it.
+support publishing new crates directly from Cargo.
 
 > Note: If you are interested in mirroring or vendoring an existing registry,
 > take a look at [Source Replacement].
 
 ### Using an Alternate Registry
 
-To use a registry other than [crates.io], the name and URL of the registry
-must be added to a [`.cargo/config` file][config]. The `registries` table
-has a key for each registry, for example:
+To use a registry other than [crates.io], the name and index URL of the
+registry must be added to a [`.cargo/config` file][config]. The `registries`
+table has a key for each registry, for example:
 
 ```toml
 [registries]
@@ -21,8 +20,9 @@ my-registry = { index = "https://my-intranet:8080/git/index" }
 ```
 
 The `index` key should be a URL to a git repository with the registry's index.
-Dependencies in a manifest can then refer to the name of the registry with the
-`registry` key to tell Cargo to fetch from that registry:
+A crate can then depend on a crate from another registry by specifying the
+`registry` key and a value of the registry's name in that dependency's entry
+in `Cargo.toml`:
 
 ```toml
 # Sample Cargo.toml
@@ -42,7 +42,8 @@ environment variable will accomplish the same thing as defining a config file:
 CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index
 ```
 
-> Note: [crates.io] does not accept packages that use other registries.
+> Note: [crates.io] does not accept packages that depend on crates from other
+> registries.
 
 ### Publishing to an Alternate Registry
 
@@ -56,7 +57,7 @@ registry to use. For example, to publish the package in the current directory:
     This only needs to be done once. You must enter the secret API token
     retrieved from the registry's website. Alternatively the token may be
     passed directly to the `publish` command with the `--token` command-line
-    flag or and environment variable with the name of the registry such as
+    flag or an environment variable with the name of the registry such as
     `CARGO_REGISTRIES_MY_REGISTRY_TOKEN`.
 
 2. `cargo publish --registry=my-registry`
@@ -65,7 +66,7 @@ Instead of always passing the `--registry` command-line option, the default
 registry may be set in [`.cargo/config`][config] with the `registry.default`
 key.
 
-Setting the `package.publish` key in `Cargo.toml` manifest restricts which
+Setting the `package.publish` key in the `Cargo.toml` manifest restricts which
 registries the package is allowed to be published to. This is useful to
 prevent accidentally publishing a closed-source package to [crates.io]. The
 value may be a list of registry names, for example:
@@ -139,19 +140,27 @@ filename is the name of the package in lowercase. Each version of the package
 has a separate line in the file. The files are organized in a tier of
 directories:
 
-- Packages with 1 letter names are placed in a directory named `1`.
-- Packages with 2 letter names are placed in a directory named `2`.
-- Packages with 3 letter names are placed in the directory `3/{first-letter}`
-  where `{first-letter}` is the first letter of the package name.
+- Packages with 1 character names are placed in a directory named `1`.
+- Packages with 2 character names are placed in a directory named `2`.
+- Packages with 3 character names are placed in the directory
+  `3/{first-character}` where `{first-character}` is the first character of
+  the package name.
 - All other packages are stored in directories named
-  `{first-two}/{second-two}` where the top directory is the first two letters
-  of the package name, and the next subdirectory is the third and fourth
-  letters of the package name. For example, `cargo` would be stored in a file
-  named `ca/rg/cargo`.
+  `{first-two}/{second-two}` where the top directory is the first two
+  characters of the package name, and the next subdirectory is the third and
+  fourth characters of the package name. For example, `cargo` would be stored
+  in a file named `ca/rg/cargo`.
 
-> Note: Although the index filenames are in lowercase, the fields in
-> `Cargo.toml` manifests and the index JSON data are case-sensitive and may
-> contain upper and lower case characters.
+> Note: Although the index filenames are in lowercase, the fields that contain
+> package names in `Cargo.toml` and the index JSON data are case-sensitive and
+> may contain upper and lower case characters.
+
+Registries may want to consider enforcing limitations on package names added
+to their index. Cargo itself allows names with any [alphanumeric], `-`, or `_`
+character. For example, [crates.io] imposes relatively strict limitations,
+such as requiring it to be a valid Rust identifier, only allowing ASCII
+characters, under a specific length, and rejects reserved names such as
+Windows special filenames like "nul".
 
 Each line in a package file contains a JSON object that describes a published
 version of the package. The following is a pretty-printed example with comments
@@ -160,9 +169,11 @@ explaining the format of the entry.
 ```javascript
 {
     // The name of the package.
-    // This must contain alphanumeric, `-`, or `_` characters.
+    // This must only contain alphanumeric, `-`, or `_` characters.
     "name": "foo",
     // The version of the package this row is describing.
+    // This must be a valid version number according to the Semantic
+    // Versioning 2.0.0 spec at https://semver.org/.
     "vers": "0.1.0",
     // Array of direct dependencies of the package.
     "deps": [
@@ -173,6 +184,8 @@ explaining the format of the entry.
             // the `package` field.
             "name": "rand",
             // The semver requirement for this dependency.
+            // This must be a valid version requirement defined at
+            // https://github.com/steveklabnik/semver#requirements.
             "req": "^0.6",
             // Array of features (as strings) enabled for this dependency.
             "features": ["i128_support"],
@@ -218,13 +231,6 @@ explaining the format of the entry.
 The JSON objects should not be modified after they are added except for the
 `yanked` field whose value may change at any time.
 
-Registries may want to consider enforcing limitations on package names added
-to their index. Cargo itself allows names with any [alphanumeric], `-`, or `_`
-character. For example, [crates.io] imposes relatively strict limitations,
-such as requiring it to be a valid Rust identifier, only allowing ASCII
-characters, under a specific length, and rejects reserved names such as
-Windows special filenames like "nul".
-
 ### Web API
 
 A registry may host a web API at the location defined in `config.json` to
@@ -286,7 +292,7 @@ The body of the data sent by Cargo is:
 - 32-bit unsigned little-endian integer of the length of JSON data.
 - Metadata of the package as a JSON object.
 - 32-bit unsigned little-endian integer of the length of the `.crate` file.
-- The `.crate` fle.
+- The `.crate` file.
 
 The following is a commented example of the JSON object. Some notes of some
 restrictions imposed by [crates.io] are included only to illustrate some
@@ -526,7 +532,7 @@ A successful response includes the JSON object:
 
 #### Search
 
-- Endpoint: `/api/v1/crates/crates`
+- Endpoint: `/api/v1/crates`
 - Method: GET
 - Query Parameters:
     - `q`: The search query string.

From 59f27eb72df7021fdd24d3ccb3eaaef311b613a8 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 27 Jan 2019 15:12:10 -0800
Subject: [PATCH 3/5] Clarify behavior of Add Owner.

---
 src/doc/src/reference/registries.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md
index 79ac04451b8..24c425a6d41 100644
--- a/src/doc/src/reference/registries.md
+++ b/src/doc/src/reference/registries.md
@@ -484,8 +484,12 @@ A successful response includes the JSON object:
 - Method: PUT
 - Authorization: Included
 
-A PUT request will add a new owner to a crate. The request should include the
-following JSON object:
+A PUT request will send a request to the registry to add a new owner to a
+crate. It is up to the registry how to handle the request. For example,
+[crates.io] sends an invite to the user that they must accept before being
+added.
+
+The request should include the following JSON object:
 
 ```javascript
 {

From 737382d7e1a27499aa440fd4397716a127bdc608 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Mon, 11 Feb 2019 15:16:13 -0800
Subject: [PATCH 4/5] Stabilize Alternative Registries

---
 src/cargo/core/features.rs                    |   2 +-
 src/cargo/ops/registry.rs                     |  16 +-
 src/cargo/util/command_prelude.rs             |   8 +-
 src/cargo/util/toml/mod.rs                    |  11 +-
 src/doc/man/generated/cargo-init.html         |  11 +-
 src/doc/man/generated/cargo-install.html      |   8 +-
 src/doc/man/generated/cargo-login.html        |   8 +-
 src/doc/man/generated/cargo-new.html          |  11 +-
 src/doc/man/generated/cargo-owner.html        |  17 +-
 src/doc/man/generated/cargo-publish.html      |  17 +-
 src/doc/man/generated/cargo-search.html       |   8 +-
 src/doc/man/generated/cargo-yank.html         |  17 +-
 src/doc/man/options-new.adoc                  |  11 +-
 src/doc/man/options-registry.adoc             |   7 +-
 src/doc/man/options-token.adoc                |   8 +-
 src/doc/src/reference/config.md               |  45 ++++-
 src/doc/src/reference/manifest.md             |  19 +-
 src/doc/src/reference/registries.md           |  18 +-
 .../src/reference/specifying-dependencies.md  |  27 ++-
 src/doc/src/reference/unstable.md             |  53 ------
 src/etc/man/cargo-init.1                      |  18 +-
 src/etc/man/cargo-install.1                   |  12 +-
 src/etc/man/cargo-login.1                     |  12 +-
 src/etc/man/cargo-new.1                       |  18 +-
 src/etc/man/cargo-owner.1                     |  20 ++-
 src/etc/man/cargo-publish.1                   |  20 ++-
 src/etc/man/cargo-search.1                    |  12 +-
 src/etc/man/cargo-yank.1                      |  20 ++-
 tests/testsuite/alt_registry.rs               | 165 +++---------------
 tests/testsuite/publish.rs                    |  61 +------
 tests/testsuite/support/registry.rs           |   2 +-
 31 files changed, 281 insertions(+), 401 deletions(-)

diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs
index 6a90413391f..d19a8e55c2b 100644
--- a/src/cargo/core/features.rs
+++ b/src/cargo/core/features.rs
@@ -173,7 +173,7 @@ features! {
         [unstable] test_dummy_unstable: bool,
 
         // Downloading packages from alternative registry indexes.
-        [unstable] alternative_registries: bool,
+        [stable] alternative_registries: bool,
 
         // Using editions
         [stable] edition: bool,
diff --git a/src/cargo/ops/registry.rs b/src/cargo/ops/registry.rs
index 4447dc9699e..cedda3abc08 100644
--- a/src/cargo/ops/registry.rs
+++ b/src/cargo/ops/registry.rs
@@ -721,7 +721,7 @@ pub fn search(
         prefix
     }
 
-    let (mut registry, _) = registry(config, None, index, reg, false)?;
+    let (mut registry, source_id) = registry(config, None, index, reg, false)?;
     let (crates, total_crates) = registry
         .search(query, limit)
         .chain_err(|| "failed to retrieve search results from the registry")?;
@@ -762,11 +762,15 @@ pub fn search(
             total_crates - limit
         );
     } else if total_crates > limit && limit >= search_max_limit {
-        println!(
-            "... and {} crates more (go to http://crates.io/search?q={} to see more)",
-            total_crates - limit,
-            percent_encode(query.as_bytes(), QUERY_ENCODE_SET)
-        );
+        let extra = if source_id.is_default_registry() {
+            format!(
+                " (go to http://crates.io/search?q={} to see more)",
+                percent_encode(query.as_bytes(), QUERY_ENCODE_SET)
+            )
+        } else {
+            String::new()
+        };
+        println!("... and {} crates more{}", total_crates - limit, extra);
     }
 
     Ok(())
diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs
index 1ad216142a9..a8ddfdb94dd 100644
--- a/src/cargo/util/command_prelude.rs
+++ b/src/cargo/util/command_prelude.rs
@@ -174,7 +174,7 @@ pub trait AppExt: Sized {
     }
 
     fn arg_index(self) -> Self {
-        self._arg(opt("index", "Registry index to upload the package to").value_name("INDEX"))
+        self._arg(opt("index", "Registry index URL to upload the package to").value_name("INDEX"))
             ._arg(
                 opt("host", "DEPRECATED, renamed to '--index'")
                     .value_name("HOST")
@@ -387,12 +387,6 @@ pub trait ArgMatchesExt {
     fn registry(&self, config: &Config) -> CargoResult<Option<String>> {
         match self._value_of("registry") {
             Some(registry) => {
-                if !config.cli_unstable().unstable_options {
-                    return Err(failure::format_err!(
-                        "registry option is an unstable feature and \
-                         requires -Zunstable-options to use."
-                    ));
-                }
                 validate_package_name(registry, "registry name", "")?;
 
                 if registry == CRATES_IO_REGISTRY {
diff --git a/src/cargo/util/toml/mod.rs b/src/cargo/util/toml/mod.rs
index a57a09dfa61..d3e6fd9aa95 100644
--- a/src/cargo/util/toml/mod.rs
+++ b/src/cargo/util/toml/mod.rs
@@ -995,14 +995,7 @@ impl TomlManifest {
         };
         let profiles = Profiles::new(me.profile.as_ref(), config, &features, &mut warnings)?;
         let publish = match project.publish {
-            Some(VecStringOrBool::VecString(ref vecstring)) => {
-                features
-                    .require(Feature::alternative_registries())
-                    .chain_err(|| {
-                        "the `publish` manifest key is unstable for anything other than a value of true or false"
-                    })?;
-                Some(vecstring.clone())
-            }
+            Some(VecStringOrBool::VecString(ref vecstring)) => Some(vecstring.clone()),
             Some(VecStringOrBool::Bool(false)) => Some(vec![]),
             None | Some(VecStringOrBool::Bool(true)) => None,
         };
@@ -1410,12 +1403,10 @@ impl DetailedTomlDependency {
             .set_optional(self.optional.unwrap_or(false))
             .set_platform(cx.platform.clone());
         if let Some(registry) = &self.registry {
-            cx.features.require(Feature::alternative_registries())?;
             let registry_id = SourceId::alt_registry(cx.config, registry)?;
             dep.set_registry_id(registry_id);
         }
         if let Some(registry_index) = &self.registry_index {
-            cx.features.require(Feature::alternative_registries())?;
             let url = registry_index.to_url()?;
             let registry_id = SourceId::for_registry(&url)?;
             dep.set_registry_id(registry_id);
diff --git a/src/doc/man/generated/cargo-init.html b/src/doc/man/generated/cargo-init.html
index b4b893eba23..979b330a4d4 100644
--- a/src/doc/man/generated/cargo-init.html
+++ b/src/doc/man/generated/cargo-init.html
@@ -128,11 +128,14 @@ <h3 id="cargo_init_init_options">Init Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use. This sets the <code>publish</code> field which will
-restrict publishing only to the given registry name.</p>
+<p>This sets the <code>publish</code> field in <code>Cargo.toml</code> to the given registry name
+which will restrict publishing only to that registry.</p>
 <div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
+<p>Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry defined by the <code>registry.default</code>
+config key is used. If the default registry is not set and <code>--registry</code> is not
+used, the <code>publish</code> field will not be set which means that publishing will not
+be restricted.</p>
 </div>
 </dd>
 </dl>
diff --git a/src/doc/man/generated/cargo-install.html b/src/doc/man/generated/cargo-install.html
index 5cbd1f384e1..bd5d6fb24ed 100644
--- a/src/doc/man/generated/cargo-install.html
+++ b/src/doc/man/generated/cargo-install.html
@@ -131,11 +131,9 @@ <h3 id="cargo_install_install_options">Install Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>
diff --git a/src/doc/man/generated/cargo-login.html b/src/doc/man/generated/cargo-login.html
index 9c2b518328c..b44377b34a4 100644
--- a/src/doc/man/generated/cargo-login.html
+++ b/src/doc/man/generated/cargo-login.html
@@ -39,11 +39,9 @@ <h3 id="cargo_login_login_options">Login Options</h3>
 <dl>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>
diff --git a/src/doc/man/generated/cargo-new.html b/src/doc/man/generated/cargo-new.html
index 33bfef758a8..adf6c46d7a8 100644
--- a/src/doc/man/generated/cargo-new.html
+++ b/src/doc/man/generated/cargo-new.html
@@ -121,11 +121,14 @@ <h3 id="cargo_new_new_options">New Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use. This sets the <code>publish</code> field which will
-restrict publishing only to the given registry name.</p>
+<p>This sets the <code>publish</code> field in <code>Cargo.toml</code> to the given registry name
+which will restrict publishing only to that registry.</p>
 <div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
+<p>Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry defined by the <code>registry.default</code>
+config key is used. If the default registry is not set and <code>--registry</code> is not
+used, the <code>publish</code> field will not be set which means that publishing will not
+be restricted.</p>
 </div>
 </dd>
 </dl>
diff --git a/src/doc/man/generated/cargo-owner.html b/src/doc/man/generated/cargo-owner.html
index 41624a0f588..04a3628d891 100644
--- a/src/doc/man/generated/cargo-owner.html
+++ b/src/doc/man/generated/cargo-owner.html
@@ -58,7 +58,14 @@ <h3 id="cargo_owner_owner_options">Owner Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--token</strong> <em>TOKEN</em></dt>
 <dd>
-<p>API token to use when authenticating.</p>
+<p>API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
+<div class="paragraph">
+<p>The token for crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code>
+environment variable. Tokens for other registries may be specified with
+environment variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code>
+is the name of the registry in all capital letters.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--index</strong> <em>INDEX</em></dt>
 <dd>
@@ -66,11 +73,9 @@ <h3 id="cargo_owner_owner_options">Owner Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>
diff --git a/src/doc/man/generated/cargo-publish.html b/src/doc/man/generated/cargo-publish.html
index c233c0e4ed8..7c20c06d527 100644
--- a/src/doc/man/generated/cargo-publish.html
+++ b/src/doc/man/generated/cargo-publish.html
@@ -67,7 +67,14 @@ <h3 id="cargo_publish_publish_options">Publish Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--token</strong> <em>TOKEN</em></dt>
 <dd>
-<p>API token to use when authenticating.</p>
+<p>API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
+<div class="paragraph">
+<p>The token for crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code>
+environment variable. Tokens for other registries may be specified with
+environment variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code>
+is the name of the registry in all capital letters.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--no-verify</strong></dt>
 <dd>
@@ -83,11 +90,9 @@ <h3 id="cargo_publish_publish_options">Publish Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>
diff --git a/src/doc/man/generated/cargo-search.html b/src/doc/man/generated/cargo-search.html
index b21dd04106c..a2121216f2b 100644
--- a/src/doc/man/generated/cargo-search.html
+++ b/src/doc/man/generated/cargo-search.html
@@ -37,11 +37,9 @@ <h3 id="cargo_search_search_options">Search Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>
diff --git a/src/doc/man/generated/cargo-yank.html b/src/doc/man/generated/cargo-yank.html
index 4de0f1486e7..f27024bbe7b 100644
--- a/src/doc/man/generated/cargo-yank.html
+++ b/src/doc/man/generated/cargo-yank.html
@@ -50,7 +50,14 @@ <h3 id="cargo_yank_owner_options">Owner Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--token</strong> <em>TOKEN</em></dt>
 <dd>
-<p>API token to use when authenticating.</p>
+<p>API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
+<div class="paragraph">
+<p>The token for crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code>
+environment variable. Tokens for other registries may be specified with
+environment variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code>
+is the name of the registry in all capital letters.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--index</strong> <em>INDEX</em></dt>
 <dd>
@@ -58,11 +65,9 @@ <h3 id="cargo_yank_owner_options">Owner Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>
diff --git a/src/doc/man/options-new.adoc b/src/doc/man/options-new.adoc
index 6ede49e0208..2218599ae2a 100644
--- a/src/doc/man/options-new.adoc
+++ b/src/doc/man/options-new.adoc
@@ -19,8 +19,11 @@
     `cargo-new.vcs`, or `none` if already inside a VCS repository.
 
 *--registry* _REGISTRY_::
-    Alternative registry to use. This sets the `publish` field which will
-    restrict publishing only to the given registry name.
+    This sets the `publish` field in `Cargo.toml` to the given registry name
+    which will restrict publishing only to that registry.
 +
-This option is unstable and available only on the nightly channel and requires
-the `-Z unstable-options` flag to enable.
+Registry names are defined in linkcargo:reference/config.html[Cargo config files].
+If not specified, the default registry defined by the `registry.default`
+config key is used. If the default registry is not set and `--registry` is not
+used, the `publish` field will not be set which means that publishing will not
+be restricted.
diff --git a/src/doc/man/options-registry.adoc b/src/doc/man/options-registry.adoc
index 79a035ea94f..a0c4c27c8e8 100644
--- a/src/doc/man/options-registry.adoc
+++ b/src/doc/man/options-registry.adoc
@@ -1,5 +1,4 @@
 *--registry* _REGISTRY_::
-    Alternative registry to use.
-+
-This option is unstable and available only on the nightly channel and requires
-the `-Z unstable-options` flag to enable.
+    Name of the registry to use. Registry names are defined in linkcargo:reference/config.html[Cargo config files].
+    If not specified, the default registry is used, which is defined by the
+    `registry.default` config key which defaults to `crates-io`.
diff --git a/src/doc/man/options-token.adoc b/src/doc/man/options-token.adoc
index c303aa77656..c047fcbc984 100644
--- a/src/doc/man/options-token.adoc
+++ b/src/doc/man/options-token.adoc
@@ -1,2 +1,8 @@
 *--token* _TOKEN_::
-    API token to use when authenticating.
+    API token to use when authenticating. This overrides the token stored in
+    the credentials file (which is created by man:cargo-login[1]).
++
+The token for crates.io may be specified with the `CARGO_REGISTRY_TOKEN`
+environment variable. Tokens for other registries may be specified with
+environment variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME`
+is the name of the registry in all capital letters.
diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
index da6b3c5d649..ee3f8426432 100644
--- a/src/doc/src/reference/config.md
+++ b/src/doc/src/reference/config.md
@@ -6,7 +6,6 @@ manifest, see the [manifest format](reference/manifest.html).
 
 ### Hierarchical structure
 
-
 Cargo allows local configuration for a particular package as well as global
 configuration, like git. Cargo extends this to a hierarchical strategy.
 If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the
@@ -17,7 +16,7 @@ following configuration files would be probed for and unified in this order:
 * `/projects/foo/.cargo/config`
 * `/projects/.cargo/config`
 * `/.cargo/config`
-* `$HOME/.cargo/config`
+* `$CARGO_HOME/config` (`$CARGO_HOME` defaults to `$HOME/.cargo`)
 
 With this structure, you can specify configuration per-package, and even
 possibly check it into version control. You can also specify personal defaults
@@ -91,9 +90,16 @@ runner = ".."
 
 # Configuration keys related to the registry
 [registry]
-index = "..."   # URL of the registry index (defaults to the central repository)
-token = "..."   # Access token (found on the central repo’s website)
-default = "..." # Default alternative registry to use (can be overriden with --registry)
+index = "..."   # URL of the registry index (defaults to the index of crates.io)
+default = "..." # Name of the default registry to use (can be overridden with
+                # --registry)
+
+# Configuration keys for registries other than crates.io.
+# `$name` should be the name of the registry, which will be used for
+# dependencies in `Cargo.toml` files and the `--registry` command-line flag.
+# Registry names should only contain alphanumeric characters, `-`, or `_`.
+[registries.$name]
+index = "..."   # URL of the registry index
 
 [http]
 proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
@@ -160,5 +166,34 @@ tables, cannot be configured through environment variables.
 In addition to the system above, Cargo recognizes a few other specific
 [environment variables][env].
 
+### Credentials
+
+Configuration values with sensitive information are stored in the
+`$CARGO_HOME/credentials` file. This file is automatically created and updated
+by [`cargo login`]. It follows the same format as Cargo config files.
+
+```toml
+[registry]
+token = "..."   # Access token for crates.io
+
+# `$name` should be a registry name (see above for more information about
+# configuring registries).
+[registries.$name]
+token = "..."   # Access token for the named registry
+```
+
+Tokens are used by some Cargo commands such as [`cargo publish`] for
+authenticating with remote registries. Care should be taken to protect the
+tokens and to keep them secret.
+
+As with most other config values, tokens may be specified with environment
+variables. The token for crates.io may be specified with the
+`CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may
+be specified with environment variables of the form
+`CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name of the registry in all
+capital letters.
+
+[`cargo login`]: commands/cargo-login.html
+[`cargo publish`]: commands/cargo-publish.html
 [env]: reference/environment-variables.html
 [source]: reference/source-replacement.html
diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 3788037a6de..069fa23e951 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -175,6 +175,15 @@ private in a company.
 publish = false
 ```
 
+The value many also be an array of strings which are registry names that are
+allowed to be published to.
+
+```toml
+[package]
+# ...
+publish = ["some-registry-name"]
+```
+
 #### The `workspace`  field (optional)
 
 The `workspace` field can be used to configure the workspace that this package
@@ -832,11 +841,10 @@ baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }
 ```
 
 The `[patch]` table is made of dependency-like sub-tables. Each key after
-`[patch]` is a URL of the source that's being patched, or `crates-io` if
-you're modifying the https://crates.io registry. In the example above
-`crates-io` could be replaced with a git URL such as
-`https://github.com/rust-lang-nursery/log`; the second `[patch]`
-section in the example uses this to specify a source called `baz`.
+`[patch]` is a URL of the source that is being patched, or the name of a
+registry. The name `crates-io` may be used to override the default registry
+[crates.io]. The first `[patch]` in the example above demonstrates overriding
+[crates.io], and the second `[patch]` demonstrates overriding a git source.
 
 Each entry in these tables is a normal dependency specification, the same as
 found in the `[dependencies]` section of the manifest. The dependencies listed
@@ -856,6 +864,7 @@ dependencies][replace] section of the documentation and [RFC 1969] for the
 technical specification of this feature.
 
 [RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
+[crates.io]: https://crates.io/
 [replace]: reference/specifying-dependencies.html#overriding-dependencies
 
 ### The `[replace]` Section
diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md
index 24c425a6d41..dca40c11af3 100644
--- a/src/doc/src/reference/registries.md
+++ b/src/doc/src/reference/registries.md
@@ -49,7 +49,7 @@ CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index
 
 If the registry supports web API access, then packages can be published
 directly to the registry from Cargo. Several of Cargo's commands such as
-`cargo publish` take a `--registry` command-line flag to indicate which
+[`cargo publish`] take a `--registry` command-line flag to indicate which
 registry to use. For example, to publish the package in the current directory:
 
 1. `cargo login --registry=my-registry`
@@ -80,7 +80,7 @@ publish = ["my-registry"]
 The `publish` value may also be `false` to restrict all publishing, which is
 the same as an empty list.
 
-The authentication information saved by `cargo login` is stored in the
+The authentication information saved by [`cargo login`] is stored in the
 `credentials` file in the Cargo home directory (default `$HOME/.cargo`). It
 has a separate table for each registry, for example:
 
@@ -93,7 +93,7 @@ token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy"
 
 A minimal registry can be implemented by having a git repository that contains
 an index, and a server that contains the compressed `.crate` files created by
-`cargo package`. Users won't be able to use Cargo to publish to it, but this
+[`cargo package`]. Users won't be able to use Cargo to publish to it, but this
 may be sufficient for closed environments.
 
 A full-featured registry that supports publishing will additionally need to
@@ -127,8 +127,8 @@ The keys are:
   name and version of the crate to download. If the markers are not present,
   then the value `/{crate}/{version}/download` is appended to the end.
 - `api`: This is the base URL for the web API. This key is optional, and if it
-  is not specified, commands such as `cargo publish` will not work. The web API
-  is described below.
+  is not specified, commands such as [`cargo publish`] will not work. The web
+  API is described below.
 
 The download endpoint should send the `.crate` file for the requested package.
 Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2.
@@ -240,7 +240,8 @@ Cargo includes the `Authorization` header for requests that require
 authentication. The header value is the API token. The server should respond
 with a 403 response code if the token is not valid. Users are expected to
 visit the registry's website to obtain a token, and Cargo can store the token
-using the `cargo login` command, or by passing the token on the command-line.
+using the [`cargo login`] command, or by passing the token on the
+command-line.
 
 Responses use a 200 response code for both success and errors. Cargo looks at
 the JSON response to determine if there was success or failure. Failure
@@ -572,10 +573,13 @@ A successful response includes the JSON object:
 - Endpoint: `/me`
 
 The "login" endpoint is not an actual API request. It exists solely for the
-`cargo login` command to display a URL to instruct a user to visit in a web
+[`cargo login`] command to display a URL to instruct a user to visit in a web
 browser to log in and retrieve an API token.
 
 [Source Replacement]: reference/source-replacement.html
+[`cargo login`]: commands/cargo-login.html
+[`cargo package`]: commands/cargo-package.html
+[`cargo publish`]: commands/cargo-publish.html
 [alphanumeric]: https://doc.rust-lang.org/std/primitive.char.html#method.is_alphanumeric
 [config]: reference/config.html
 [crates.io]: https://crates.io/
diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md
index 512862e5e9b..daa6533df6e 100644
--- a/src/doc/src/reference/specifying-dependencies.md
+++ b/src/doc/src/reference/specifying-dependencies.md
@@ -1,11 +1,12 @@
 ## Specifying Dependencies
 
-Your crates can depend on other libraries from [crates.io], `git` repositories, or
-subdirectories on your local file system. You can also temporarily override the
-location of a dependency— for example, to be able to test out a bug fix in the
-dependency that you are working on locally. You can have different
-dependencies for different platforms, and dependencies that are only used during
-development. Let's take a look at how to do each of these.
+Your crates can depend on other libraries from [crates.io] or other
+registries, `git` repositories, or subdirectories on your local file system.
+You can also temporarily override the location of a dependency — for example,
+to be able to test out a bug fix in the dependency that you are working on
+locally. You can have different dependencies for different platforms, and
+dependencies that are only used during development. Let's take a look at how
+to do each of these.
 
 ### Specifying dependencies from crates.io
 
@@ -101,6 +102,20 @@ Here are some examples of inequality requirements:
 Multiple version requirements can also be separated with a comma, e.g. `>= 1.2,
 < 1.5`.
 
+### Specifying dependencies from other registries
+
+To specify a dependency from a registry other than [crates.io], first the
+registry must be configured in a `.cargo/config` file. See the [registries
+documentation] for more information. In the dependency, set the `registry` key
+to the name of the registry to use.
+
+```toml
+[dependencies]
+some-crate = { version = "1.0", registry = "my-registry" }
+```
+
+[registries documentation]: reference/registries.html
+
 ### Specifying dependencies from `git` repositories
 
 To depend on a library located in a `git` repository, the minimum information
diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 9a46176cd82..4e3327b029a 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -10,59 +10,6 @@ command-line flags.  Options requiring this will be called out below.
 Some unstable features will require you to specify the `cargo-features` key in
 `Cargo.toml`.
 
-### Alternate Registries
-* RFC: [#2141](https://github.com/rust-lang/rfcs/blob/master/text/2141-alternative-registries.md)
-* Tracking Issue: [rust-lang/rust#44931](https://github.com/rust-lang/rust/issues/44931)
-
-Alternate registries allow you to use registries other than crates.io.
-
-The name of a registry is defined in `.cargo/config` under the `registries`
-table:
-
-```toml
-[registries]
-my-registry = { index = "https://my-intranet:8080/git/index" }
-```
-
-Authentication information for alternate registries can be added to
-`.cargo/credentials`:
-
-```toml
-[registries.my-registry]
-token = "api-token"
-```
-
-Inside `Cargo.toml` you can specify which registry a dependency comes from
-using the `registry` key. First you need to include the appropriate
-`cargo-features` at the top of the file:
-
-```toml
-cargo-features = ["alternative-registries"]
-
-[package]
-...
-
-[dependencies]
-other-create = { version = "1.0", registry = "my-registry"}
-```
-
-A `--registry` flag has been added to commands that interact with registries
-such as `publish`, `login`, etc.  Example:
-
-```
-cargo +nightly publish -Z unstable-options --registry my-registry
-```
-
-The `publish` field in `Cargo.toml` has been extended to accept a list of
-registries that will restrict publishing only to those registries.
-
-```toml
-[package]
-...
-publish = ["my-registry"]
-```
-
-
 ### publish-lockfile
 * Original Issue: [#2263](https://github.com/rust-lang/cargo/issues/2263)
 * PR: [#5093](https://github.com/rust-lang/cargo/pull/5093)
diff --git a/src/etc/man/cargo-init.1 b/src/etc/man/cargo-init.1
index 2d4b87f3fc9..1a55f5c57dc 100644
--- a/src/etc/man/cargo-init.1
+++ b/src/etc/man/cargo-init.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-init
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-20
+.\"      Date: 2019-01-23
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-INIT" "1" "2018-12-20" "\ \&" "\ \&"
+.TH "CARGO\-INIT" "1" "2019-01-23" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -246,11 +246,15 @@ hg, pijul, or fossil) or do not initialize any version control at all
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use. This sets the \fBpublish\fP field which will
-restrict publishing only to the given registry name.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name
+which will restrict publishing only to that registry.
+.sp
+Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry defined by the \fBregistry.default\fP
+config key is used. If the default registry is not set and \fB\-\-registry\fP is not
+used, the \fBpublish\fP field will not be set which means that publishing will not
+be restricted.
 .RE
 .SS "Display Options"
 .sp
diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1
index 23234569b02..e23c41eaa11 100644
--- a/src/etc/man/cargo-install.1
+++ b/src/etc/man/cargo-install.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-install
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-23
+.\"      Date: 2019-01-23
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-INSTALL" "1" "2018-12-23" "\ \&" "\ \&"
+.TH "CARGO\-INSTALL" "1" "2019-01-23" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -191,10 +191,10 @@ Directory to install packages into.
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+Name of the registry to use. Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry is used, which is defined by the
+\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP.
 .RE
 .SS "Feature Selection"
 .sp
diff --git a/src/etc/man/cargo-login.1 b/src/etc/man/cargo-login.1
index 83d7f8f2b15..2f9ec810bf0 100644
--- a/src/etc/man/cargo-login.1
+++ b/src/etc/man/cargo-login.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-login
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-23
+.\"      Date: 2019-01-23
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-LOGIN" "1" "2018-12-23" "\ \&" "\ \&"
+.TH "CARGO\-LOGIN" "1" "2019-01-23" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -50,10 +50,10 @@ Take care to keep the token secret, it should not be shared with anyone else.
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+Name of the registry to use. Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry is used, which is defined by the
+\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP.
 .RE
 .SS "Display Options"
 .sp
diff --git a/src/etc/man/cargo-new.1 b/src/etc/man/cargo-new.1
index 06dc2b1ece2..894b5ab6e2f 100644
--- a/src/etc/man/cargo-new.1
+++ b/src/etc/man/cargo-new.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-new
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-20
+.\"      Date: 2019-01-23
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-NEW" "1" "2018-12-20" "\ \&" "\ \&"
+.TH "CARGO\-NEW" "1" "2019-01-23" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -241,11 +241,15 @@ hg, pijul, or fossil) or do not initialize any version control at all
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use. This sets the \fBpublish\fP field which will
-restrict publishing only to the given registry name.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name
+which will restrict publishing only to that registry.
+.sp
+Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry defined by the \fBregistry.default\fP
+config key is used. If the default registry is not set and \fB\-\-registry\fP is not
+used, the \fBpublish\fP field will not be set which means that publishing will not
+be restricted.
 .RE
 .SS "Display Options"
 .sp
diff --git a/src/etc/man/cargo-owner.1 b/src/etc/man/cargo-owner.1
index 666e746dff7..d287b6d1d5d 100644
--- a/src/etc/man/cargo-owner.1
+++ b/src/etc/man/cargo-owner.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-owner
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-20
+.\"      Date: 2019-02-05
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-OWNER" "1" "2018-12-20" "\ \&" "\ \&"
+.TH "CARGO\-OWNER" "1" "2019-02-05" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -72,7 +72,13 @@ List owners of a crate.
 .sp
 \fB\-\-token\fP \fITOKEN\fP
 .RS 4
-API token to use when authenticating.
+API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by \fBcargo\-login\fP(1)).
+.sp
+The token for crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP
+environment variable. Tokens for other registries may be specified with
+environment variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP
+is the name of the registry in all capital letters.
 .RE
 .sp
 \fB\-\-index\fP \fIINDEX\fP
@@ -82,10 +88,10 @@ The URL of the registry index to use.
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+Name of the registry to use. Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry is used, which is defined by the
+\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP.
 .RE
 .SS "Display Options"
 .sp
diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1
index b3521b1fef2..51e72a7c3ab 100644
--- a/src/etc/man/cargo-publish.1
+++ b/src/etc/man/cargo-publish.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-publish
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2019-01-14
+.\"      Date: 2019-02-05
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-PUBLISH" "1" "2019-01-14" "\ \&" "\ \&"
+.TH "CARGO\-PUBLISH" "1" "2019-02-05" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -115,7 +115,13 @@ Perform all checks without uploading.
 .sp
 \fB\-\-token\fP \fITOKEN\fP
 .RS 4
-API token to use when authenticating.
+API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by \fBcargo\-login\fP(1)).
+.sp
+The token for crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP
+environment variable. Tokens for other registries may be specified with
+environment variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP
+is the name of the registry in all capital letters.
 .RE
 .sp
 \fB\-\-no\-verify\fP
@@ -135,10 +141,10 @@ The URL of the registry index to use.
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+Name of the registry to use. Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry is used, which is defined by the
+\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP.
 .RE
 .SS "Compilation Options"
 .sp
diff --git a/src/etc/man/cargo-search.1 b/src/etc/man/cargo-search.1
index 272f71c4878..a789ac6c09a 100644
--- a/src/etc/man/cargo-search.1
+++ b/src/etc/man/cargo-search.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-search
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-20
+.\"      Date: 2019-01-23
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-SEARCH" "1" "2018-12-20" "\ \&" "\ \&"
+.TH "CARGO\-SEARCH" "1" "2019-01-23" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -54,10 +54,10 @@ The URL of the registry index to use.
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+Name of the registry to use. Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry is used, which is defined by the
+\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP.
 .RE
 .SS "Display Options"
 .sp
diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1
index c5ad056edc8..96ea15aea44 100644
--- a/src/etc/man/cargo-yank.1
+++ b/src/etc/man/cargo-yank.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-yank
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-20
+.\"      Date: 2019-01-23
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-YANK" "1" "2018-12-20" "\ \&" "\ \&"
+.TH "CARGO\-YANK" "1" "2019-01-23" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -62,7 +62,13 @@ Undo a yank, putting a version back into the index.
 .sp
 \fB\-\-token\fP \fITOKEN\fP
 .RS 4
-API token to use when authenticating.
+API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by \fBcargo\-login\fP(1)).
+.sp
+The token for crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP
+environment variable. Tokens for other registries may be specified with
+environment variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP
+is the name of the registry in all capital letters.
 .RE
 .sp
 \fB\-\-index\fP \fIINDEX\fP
@@ -72,10 +78,10 @@ The URL of the registry index to use.
 .sp
 \fB\-\-registry\fP \fIREGISTRY\fP
 .RS 4
-Alternative registry to use.
-.sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+Name of the registry to use. Registry names are defined in \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "."
+If not specified, the default registry is used, which is defined by the
+\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP.
 .RE
 .SS "Display Options"
 .sp
diff --git a/tests/testsuite/alt_registry.rs b/tests/testsuite/alt_registry.rs
index 09098eb0b7f..3e58a92e6ce 100644
--- a/tests/testsuite/alt_registry.rs
+++ b/tests/testsuite/alt_registry.rs
@@ -5,42 +5,12 @@ use cargo::util::ToUrl;
 use std::fs::{self, File};
 use std::io::Write;
 
-#[test]
-fn is_feature_gated() {
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [project]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies.bar]
-            version = "0.0.1"
-            registry = "alternative"
-        "#,
-        )
-        .file("src/main.rs", "fn main() {}")
-        .build();
-
-    Package::new("bar", "0.0.1").alternative(true).publish();
-
-    p.cargo("build")
-        .masquerade_as_nightly_cargo()
-        .with_status(101)
-        .with_stderr_contains("  feature `alternative-registries` is required")
-        .run();
-}
-
 #[test]
 fn depend_on_alt_registry() {
     let p = project()
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -57,7 +27,6 @@ fn depend_on_alt_registry() {
     Package::new("bar", "0.0.1").alternative(true).publish();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr(&format!(
             "\
 [UPDATING] `{reg}` index
@@ -71,11 +40,10 @@ fn depend_on_alt_registry() {
         ))
         .run();
 
-    p.cargo("clean").masquerade_as_nightly_cargo().run();
+    p.cargo("clean").run();
 
     // Don't download a second time
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr(
             "\
 [COMPILING] bar v0.0.1 (registry `[ROOT][..]`)
@@ -92,8 +60,6 @@ fn depend_on_alt_registry_depends_on_same_registry_no_index() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -114,7 +80,6 @@ fn depend_on_alt_registry_depends_on_same_registry_no_index() {
         .publish();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr(&format!(
             "\
 [UPDATING] `{reg}` index
@@ -137,8 +102,6 @@ fn depend_on_alt_registry_depends_on_same_registry() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -159,7 +122,6 @@ fn depend_on_alt_registry_depends_on_same_registry() {
         .publish();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr(&format!(
             "\
 [UPDATING] `{reg}` index
@@ -182,8 +144,6 @@ fn depend_on_alt_registry_depends_on_crates_io() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -204,7 +164,6 @@ fn depend_on_alt_registry_depends_on_crates_io() {
         .publish();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr_unordered(&format!(
             "\
 [UPDATING] `{alt_reg}` index
@@ -231,8 +190,6 @@ fn registry_and_path_dep_works() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -249,7 +206,6 @@ fn registry_and_path_dep_works() {
         .build();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr(
             "\
 [COMPILING] bar v0.0.1 ([CWD]/bar)
@@ -268,8 +224,6 @@ fn registry_incompatible_with_git() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -283,8 +237,13 @@ fn registry_incompatible_with_git() {
         .file("src/main.rs", "fn main() {}")
         .build();
 
-    p.cargo("build").masquerade_as_nightly_cargo().with_status(101)
-                .with_stderr_contains("  dependency (bar) specification is ambiguous. Only one of `git` or `registry` is allowed.").run();
+    p.cargo("build")
+        .with_status(101)
+        .with_stderr_contains(
+            "  dependency (bar) specification is ambiguous. \
+             Only one of `git` or `registry` is allowed.",
+        )
+        .run();
 }
 
 #[test]
@@ -295,7 +254,6 @@ fn cannot_publish_to_crates_io_with_registry_dependency() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
             [project]
             name = "foo"
             version = "0.0.1"
@@ -331,15 +289,13 @@ fn cannot_publish_to_crates_io_with_registry_dependency() {
         )
         .build();
 
-    p.cargo("publish --registry fakeio -Z unstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("publish --registry fakeio")
         .with_status(101)
         .with_stderr_contains("[ERROR] crates cannot be published to crates.io[..]")
         .run();
 
     p.cargo("publish --index")
         .arg(fakeio_url.to_string())
-        .masquerade_as_nightly_cargo()
         .with_status(101)
         .with_stderr_contains("[ERROR] crates cannot be published to crates.io[..]")
         .run();
@@ -351,8 +307,6 @@ fn publish_with_registry_dependency() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -369,13 +323,9 @@ fn publish_with_registry_dependency() {
     Package::new("bar", "0.0.1").alternative(true).publish();
 
     // Login so that we have the token available
-    p.cargo("login --registry alternative TOKEN -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .run();
+    p.cargo("login --registry alternative TOKEN").run();
 
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .run();
+    p.cargo("publish --registry alternative").run();
 
     validate_alt_upload(
         r#"{
@@ -418,8 +368,6 @@ fn alt_registry_and_crates_io_deps() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -442,7 +390,6 @@ fn alt_registry_and_crates_io_deps() {
         .publish();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr_contains(format!(
             "[UPDATING] `{}` index",
             registry::alt_registry_path().to_str().unwrap()
@@ -470,8 +417,7 @@ fn block_publish_due_to_no_token() {
     fs::remove_file(paths::home().join(".cargo/credentials")).unwrap();
 
     // Now perform the actual publish
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("publish --registry alternative")
         .with_status(101)
         .with_stderr_contains("error: no upload token found, please run `cargo login`")
         .run();
@@ -479,33 +425,16 @@ fn block_publish_due_to_no_token() {
 
 #[test]
 fn publish_to_alt_registry() {
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            cargo-features = ["alternative-registries"]
-
-            [project]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-        "#,
-        )
-        .file("src/main.rs", "fn main() {}")
-        .build();
+    let p = project().file("src/main.rs", "fn main() {}").build();
 
     // Setup the registry by publishing a package
     Package::new("bar", "0.0.1").alternative(true).publish();
 
     // Login so that we have the token available
-    p.cargo("login --registry alternative TOKEN -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .run();
+    p.cargo("login --registry alternative TOKEN").run();
 
     // Now perform the actual publish
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .run();
+    p.cargo("publish --registry alternative").run();
 
     validate_alt_upload(
         r#"{
@@ -538,8 +467,6 @@ fn publish_with_crates_io_dep() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -557,13 +484,9 @@ fn publish_with_crates_io_dep() {
     Package::new("bar", "0.0.1").publish();
 
     // Login so that we have the token available
-    p.cargo("login --registry alternative TOKEN -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .run();
+    p.cargo("login --registry alternative TOKEN").run();
 
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .run();
+    p.cargo("publish --registry alternative").run();
 
     validate_alt_upload(
         r#"{
@@ -617,23 +540,9 @@ fn passwords_in_url_forbidden() {
         )
         .unwrap();
 
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            cargo-features = ["alternative-registries"]
-
-            [project]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-        "#,
-        )
-        .file("src/main.rs", "fn main() {}")
-        .build();
+    let p = project().file("src/main.rs", "fn main() {}").build();
 
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("publish --registry alternative")
         .with_status(101)
         .with_stderr_contains("error: Registry URLs may not contain passwords")
         .run();
@@ -646,8 +555,6 @@ fn patch_alt_reg() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [package]
             name = "foo"
             version = "0.0.1"
@@ -671,7 +578,6 @@ fn patch_alt_reg() {
         .build();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr(
             "\
 [UPDATING] `[ROOT][..]` index
@@ -689,8 +595,6 @@ fn bad_registry_name() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -705,7 +609,6 @@ fn bad_registry_name() {
         .build();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_status(101)
         .with_stderr(
             "\
@@ -720,10 +623,8 @@ Caused by:
         "init", "install", "login", "owner", "publish", "search", "yank",
     ] {
         p.cargo(cmd)
-            .arg("-Zunstable-options")
             .arg("--registry")
             .arg("bad name")
-            .masquerade_as_nightly_cargo()
             .with_status(101)
             .with_stderr("[ERROR] Invalid character ` ` in registry name: `bad name`")
             .run();
@@ -749,7 +650,6 @@ fn no_api() {
         .file(
             "Cargo.toml",
             r#"
-             cargo-features = ["alternative-registries"]
              [package]
              name = "foo"
              version = "0.0.1"
@@ -763,7 +663,6 @@ fn no_api() {
         .build();
 
     p.cargo("build")
-        .masquerade_as_nightly_cargo()
         .with_stderr(&format!(
             "\
 [UPDATING] `{reg}` index
@@ -783,38 +682,32 @@ fn no_api() {
         registry::alt_registry_path().display()
     );
 
-    p.cargo("login --registry alternative TOKEN -Zunstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("login --registry alternative TOKEN")
         .with_status(101)
         .with_stderr_contains(&err)
         .run();
 
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("publish --registry alternative")
         .with_status(101)
         .with_stderr_contains(&err)
         .run();
 
-    p.cargo("search --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("search --registry alternative")
         .with_status(101)
         .with_stderr_contains(&err)
         .run();
 
-    p.cargo("owner --registry alternative -Zunstable-options --list")
-        .masquerade_as_nightly_cargo()
+    p.cargo("owner --registry alternative --list")
         .with_status(101)
         .with_stderr_contains(&err)
         .run();
 
-    p.cargo("yank --registry alternative -Zunstable-options --vers=0.0.1 bar")
-        .masquerade_as_nightly_cargo()
+    p.cargo("yank --registry alternative --vers=0.0.1 bar")
         .with_status(101)
         .with_stderr_contains(&err)
         .run();
 
-    p.cargo("yank --registry alternative -Zunstable-options --vers=0.0.1 bar")
-        .masquerade_as_nightly_cargo()
+    p.cargo("yank --registry alternative --vers=0.0.1 bar")
         .with_stderr_contains(&err)
         .with_status(101)
         .run();
@@ -827,7 +720,6 @@ fn alt_reg_metadata() {
         .file(
             "Cargo.toml",
             r#"
-             cargo-features = ["alternative-registries"]
              [package]
              name = "foo"
              version = "0.0.1"
@@ -857,7 +749,6 @@ fn alt_reg_metadata() {
     // altdep -> bar: null (because it is in crates.io)
     // iodep -> altdep2: alternative-registry
     p.cargo("metadata --format-version=1 --no-deps")
-        .masquerade_as_nightly_cargo()
         .with_json(
             r#"
             {
@@ -922,7 +813,6 @@ fn alt_reg_metadata() {
 
     // --no-deps uses a different code path, make sure both work.
     p.cargo("metadata --format-version=1")
-        .masquerade_as_nightly_cargo()
         .with_json(
             r#"
              {
@@ -1104,8 +994,6 @@ fn unknown_registry() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -1132,13 +1020,12 @@ fn unknown_registry() {
     config.insert(start + start_index, '#');
     fs::write(&cfg_path, config).unwrap();
 
-    p.cargo("build").masquerade_as_nightly_cargo().run();
+    p.cargo("build").run();
 
     // Important parts:
     // foo -> bar registry = null
     // bar -> baz registry = alternate
     p.cargo("metadata --format-version=1")
-        .masquerade_as_nightly_cargo()
         .with_json(
             r#"
             {
diff --git a/tests/testsuite/publish.rs b/tests/testsuite/publish.rs
index 66c51b9d152..a140e0e5468 100644
--- a/tests/testsuite/publish.rs
+++ b/tests/testsuite/publish.rs
@@ -616,47 +616,6 @@ See [..]
     assert!(!registry::api_path().join("api/v1/crates/new").exists());
 }
 
-#[test]
-fn block_publish_feature_not_enabled() {
-    registry::init();
-
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [project]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-            license = "MIT"
-            description = "foo"
-            publish = [
-                "test"
-            ]
-        "#,
-        )
-        .file("src/main.rs", "fn main() {}")
-        .build();
-
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .with_status(101)
-        .with_stderr(
-            "\
-error: failed to parse manifest at `[..]`
-
-Caused by:
-  the `publish` manifest key is unstable for anything other than a value of true or false
-
-Caused by:
-  feature `alternative-registries` is required
-
-consider adding `cargo-features = [\"alternative-registries\"]` to the manifest
-",
-        )
-        .run();
-}
-
 #[test]
 fn registry_not_in_publish_list() {
     registry::init();
@@ -665,8 +624,6 @@ fn registry_not_in_publish_list() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -682,10 +639,8 @@ fn registry_not_in_publish_list() {
         .build();
 
     p.cargo("publish")
-        .masquerade_as_nightly_cargo()
         .arg("--registry")
         .arg("alternative")
-        .arg("-Zunstable-options")
         .with_status(101)
         .with_stderr(
             "\
@@ -704,8 +659,6 @@ fn publish_empty_list() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -718,8 +671,7 @@ fn publish_empty_list() {
         .file("src/main.rs", "fn main() {}")
         .build();
 
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("publish --registry alternative")
         .with_status(101)
         .with_stderr(
             "\
@@ -740,8 +692,6 @@ fn publish_allowed_registry() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -757,9 +707,7 @@ fn publish_allowed_registry() {
         .file("src/main.rs", "fn main() {}")
         .build();
 
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
-        .run();
+    p.cargo("publish --registry alternative").run();
 
     publish::validate_alt_upload(
         CLEAN_FOO_JSON,
@@ -781,8 +729,6 @@ fn block_publish_no_registry() {
         .file(
             "Cargo.toml",
             r#"
-            cargo-features = ["alternative-registries"]
-
             [project]
             name = "foo"
             version = "0.0.1"
@@ -795,8 +741,7 @@ fn block_publish_no_registry() {
         .file("src/main.rs", "fn main() {}")
         .build();
 
-    p.cargo("publish --registry alternative -Zunstable-options")
-        .masquerade_as_nightly_cargo()
+    p.cargo("publish --registry alternative")
         .with_status(101)
         .with_stderr(
             "\
diff --git a/tests/testsuite/support/registry.rs b/tests/testsuite/support/registry.rs
index eaf944d2724..26fb50df67f 100644
--- a/tests/testsuite/support/registry.rs
+++ b/tests/testsuite/support/registry.rs
@@ -249,7 +249,7 @@ impl Package {
     ///
     /// The name of the alternative registry is called "alternative".
     ///
-    /// See `unstable.html#alternate-registries` for more details on
+    /// See `src/doc/src/reference/registries.md` for more details on
     /// alternative registries. See `alt_registry.rs` for the tests that use
     /// this.
     pub fn alternative(&mut self, alternative: bool) -> &mut Package {

From 902885c392c419e823099b1eb7a4c5f5f4385dc1 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Tue, 12 Feb 2019 08:40:42 -0800
Subject: [PATCH 5/5] Update for review comments.

---
 src/doc/man/generated/cargo-owner.html   | 10 ++++++----
 src/doc/man/generated/cargo-publish.html | 10 ++++++----
 src/doc/man/generated/cargo-yank.html    | 10 ++++++----
 src/doc/man/options-token.adoc           | 10 ++++++----
 src/doc/src/reference/registries.md      |  4 ++++
 src/etc/man/cargo-owner.1                | 11 +++++++----
 src/etc/man/cargo-publish.1              | 11 +++++++----
 src/etc/man/cargo-yank.1                 | 11 +++++++----
 8 files changed, 49 insertions(+), 28 deletions(-)

diff --git a/src/doc/man/generated/cargo-owner.html b/src/doc/man/generated/cargo-owner.html
index 04a3628d891..21eab2e8d5a 100644
--- a/src/doc/man/generated/cargo-owner.html
+++ b/src/doc/man/generated/cargo-owner.html
@@ -61,10 +61,12 @@ <h3 id="cargo_owner_owner_options">Owner Options</h3>
 <p>API token to use when authenticating. This overrides the token stored in
 the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
 <div class="paragraph">
-<p>The token for crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code>
-environment variable. Tokens for other registries may be specified with
-environment variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code>
-is the name of the registry in all capital letters.</p>
+<p><a href="reference/config.html">Cargo config</a> environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment
+variable. Tokens for other registries may be specified with environment
+variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name
+of the registry in all capital letters.</p>
 </div>
 </dd>
 <dt class="hdlist1"><strong>--index</strong> <em>INDEX</em></dt>
diff --git a/src/doc/man/generated/cargo-publish.html b/src/doc/man/generated/cargo-publish.html
index 7c20c06d527..8e631b2489e 100644
--- a/src/doc/man/generated/cargo-publish.html
+++ b/src/doc/man/generated/cargo-publish.html
@@ -70,10 +70,12 @@ <h3 id="cargo_publish_publish_options">Publish Options</h3>
 <p>API token to use when authenticating. This overrides the token stored in
 the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
 <div class="paragraph">
-<p>The token for crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code>
-environment variable. Tokens for other registries may be specified with
-environment variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code>
-is the name of the registry in all capital letters.</p>
+<p><a href="reference/config.html">Cargo config</a> environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment
+variable. Tokens for other registries may be specified with environment
+variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name
+of the registry in all capital letters.</p>
 </div>
 </dd>
 <dt class="hdlist1"><strong>--no-verify</strong></dt>
diff --git a/src/doc/man/generated/cargo-yank.html b/src/doc/man/generated/cargo-yank.html
index f27024bbe7b..4e1d00965e8 100644
--- a/src/doc/man/generated/cargo-yank.html
+++ b/src/doc/man/generated/cargo-yank.html
@@ -53,10 +53,12 @@ <h3 id="cargo_yank_owner_options">Owner Options</h3>
 <p>API token to use when authenticating. This overrides the token stored in
 the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
 <div class="paragraph">
-<p>The token for crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code>
-environment variable. Tokens for other registries may be specified with
-environment variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code>
-is the name of the registry in all capital letters.</p>
+<p><a href="reference/config.html">Cargo config</a> environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment
+variable. Tokens for other registries may be specified with environment
+variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name
+of the registry in all capital letters.</p>
 </div>
 </dd>
 <dt class="hdlist1"><strong>--index</strong> <em>INDEX</em></dt>
diff --git a/src/doc/man/options-token.adoc b/src/doc/man/options-token.adoc
index c047fcbc984..5f25ffbf243 100644
--- a/src/doc/man/options-token.adoc
+++ b/src/doc/man/options-token.adoc
@@ -2,7 +2,9 @@
     API token to use when authenticating. This overrides the token stored in
     the credentials file (which is created by man:cargo-login[1]).
 +
-The token for crates.io may be specified with the `CARGO_REGISTRY_TOKEN`
-environment variable. Tokens for other registries may be specified with
-environment variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME`
-is the name of the registry in all capital letters.
+linkcargo:reference/config.html[Cargo config] environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the `CARGO_REGISTRY_TOKEN` environment
+variable. Tokens for other registries may be specified with environment
+variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name
+of the registry in all capital letters.
diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md
index dca40c11af3..cc5b040fc4d 100644
--- a/src/doc/src/reference/registries.md
+++ b/src/doc/src/reference/registries.md
@@ -100,6 +100,10 @@ A full-featured registry that supports publishing will additionally need to
 have a web API service that conforms to the API used by Cargo. The web API is
 documented below.
 
+At this time, there is no widely used software for running a custom registry.
+There is interest in documenting projects that implement registry support, or
+existing package caches that add support for Cargo.
+
 ### Index Format
 
 The following defines the format of the index. New features are occasionally
diff --git a/src/etc/man/cargo-owner.1 b/src/etc/man/cargo-owner.1
index d287b6d1d5d..8e798a3b2bf 100644
--- a/src/etc/man/cargo-owner.1
+++ b/src/etc/man/cargo-owner.1
@@ -75,10 +75,13 @@ List owners of a crate.
 API token to use when authenticating. This overrides the token stored in
 the credentials file (which is created by \fBcargo\-login\fP(1)).
 .sp
-The token for crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP
-environment variable. Tokens for other registries may be specified with
-environment variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP
-is the name of the registry in all capital letters.
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " "
+environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment
+variable. Tokens for other registries may be specified with environment
+variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name
+of the registry in all capital letters.
 .RE
 .sp
 \fB\-\-index\fP \fIINDEX\fP
diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1
index 51e72a7c3ab..70e4f506f4e 100644
--- a/src/etc/man/cargo-publish.1
+++ b/src/etc/man/cargo-publish.1
@@ -118,10 +118,13 @@ Perform all checks without uploading.
 API token to use when authenticating. This overrides the token stored in
 the credentials file (which is created by \fBcargo\-login\fP(1)).
 .sp
-The token for crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP
-environment variable. Tokens for other registries may be specified with
-environment variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP
-is the name of the registry in all capital letters.
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " "
+environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment
+variable. Tokens for other registries may be specified with environment
+variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name
+of the registry in all capital letters.
 .RE
 .sp
 \fB\-\-no\-verify\fP
diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1
index 96ea15aea44..c3a637c7ae4 100644
--- a/src/etc/man/cargo-yank.1
+++ b/src/etc/man/cargo-yank.1
@@ -65,10 +65,13 @@ Undo a yank, putting a version back into the index.
 API token to use when authenticating. This overrides the token stored in
 the credentials file (which is created by \fBcargo\-login\fP(1)).
 .sp
-The token for crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP
-environment variable. Tokens for other registries may be specified with
-environment variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP
-is the name of the registry in all capital letters.
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " "
+environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment
+variable. Tokens for other registries may be specified with environment
+variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name
+of the registry in all capital letters.
 .RE
 .sp
 \fB\-\-index\fP \fIINDEX\fP