From 738f5e7b759c436f1fdb968ec6ebf843bceebebb Mon Sep 17 00:00:00 2001
From: Fishrock123 <fishrock123@rocketmail.com>
Date: Thu, 22 May 2025 11:51:08 -0700
Subject: [PATCH] docs: add lock file section to the resolver docs

Adds some documentation about how lockfiles work to the resolver section, particularly regarding when lock files exist in library dependencies.

Effectively re-adds an updated section of docs that was lost here:
https://github.com/rust-lang/cargo/pull/12382/files#diff-197a732275c32bdbdb079bdd92ac8a4ba585ee556ea978e9e661804eb76ce9eeL117-L121

Related to this Zulip thread https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/cargo.20lock.20in.20dependency/with/519679182
---
 src/doc/src/reference/resolver.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/doc/src/reference/resolver.md b/src/doc/src/reference/resolver.md
index efda79d464f..1fff671e522 100644
--- a/src/doc/src/reference/resolver.md
+++ b/src/doc/src/reference/resolver.md
@@ -12,6 +12,25 @@ resolver.
 [dependency specification]: specifying-dependencies.md
 [`cargo tree`]: ../commands/cargo-tree.md
 
+## `Cargo.lock` lock-files
+
+The `Cargo.lock` file provides deterministic builds at different times and on
+different systems, by ensuring that the exact same dependencies, versions, and
+sources are used as when the `Cargo.lock` file was last generated.
+Dependancy resolution is not run when cargo reads from `Cargo.lock`.
+
+Not all cargo commands use `Cargo.lock` by default. Examples include
+`cargo install` and `cargo update`.In these cases, `--locked` can usually be
+passed to force cargo to use the dependency graph from an existing `Cargo.lock`
+(if one exists).
+
+### Libraries with `Cargo.lock`
+
+Cargo treats `Cargo.lock` files differently when a crate is used as a library
+dependency where an upper level `Cargo.lock` would exist. In these cases cargo will
+not inspect the dependency's `Cargo.lock` even if it exists, using only the
+top-level `Cargo.lock`.
+
 ## Constraints and Heuristics
 
 In many cases there is no single "best" dependency resolution.