Document the patch-in-config feature

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 62458edb3a48f91fcb3cd4bd994b814e8158b9c0..4035928635ec237497c9af4d5e65f925bf0ad250 100644 (file)
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -1156,3 +1156,27 @@ absolute path.
 TMPDIR = { value = "/home/tmp", force = true }
 OPENSSL_DIR = { value = "vendor/openssl", relative = true }
 ```
+
+### `[patch]` in .cargo/config.toml
+* Original Pull Request: [#9204](https://github.com/rust-lang/cargo/pull/9204)
+
+The `-Z patch-in-config` flag enables the use of `[patch]` sections in
+cargo configuration files (`.cargo/config.toml`). The format of such
+`[patch]` sections is identical to the one used in `Cargo.toml`.
+
+Since `.cargo/config.toml` files are not usually checked into source
+control, you should prefer patching using `Cargo.toml` where possible to
+ensure that other developers can compile your crate in their own
+environments. Patching through cargo configuration files is generally
+only appropriate when the patch section is automatically generated by an
+external build tool.
+
+If a given dependency is patched both in a cargo configuration file and
+a `Cargo.toml` file, the patch in `Cargo.toml` is used. If multiple
+configuration files patch the same dependency, standard cargo
+configuration merging is used, which prefers the value defined closest
+to the current directory, with `$HOME/.cargo/config.toml` taking the
+lowest precedence.
+
+Relative `path` dependencies in such a `[patch]` section are resolved
+relative to the configuration file they appear in.