Add note about Cargo.lock behavior with [replace]

The Cargo.lock behavior when using [replace] can be misleading if one
does not expect multiple versions of the crate to be included. This note
is intended to assure users that this behavior is expected, and it
suggests a way to verify their `[replace]` override is preferred.

diff --git a/src/doc/specifying-dependencies.md b/src/doc/specifying-dependencies.md
index cc6e1b34a5dbe5729e56087e52d254578fe73f94..248d4fe024fd675fa608b970c593954fffd51f5f 100644 (file)
--- a/src/doc/specifying-dependencies.md
+++ b/src/doc/specifying-dependencies.md
@@ -216,6 +216,10 @@ repository. While you're waiting for the PR to get merged you can continue to
 work locally with a `[replace]`, and then once the PR is merged and published
 you can remove `[replace]` and use the newly-published version.
 
+Note: The `Cargo.lock` file will list two versions of the replaced crate: one
+for the original crate, and one for the version specified in `[replace]`.
+`cargo build -v` can verify that only one version is used in the build.
+
 ### Overriding with local dependencies
 
 Sometimes you're only temporarily working on a crate and you don't want to have