From 4330f9718b81c24bc440cd74fc3212abf48e7de2 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Fri, 9 Aug 2024 08:51:03 -0500
Subject: [PATCH] Improve the `uv lock` CLI documentation (#5932)

---
 crates/uv-cli/src/lib.rs | 10 ++++++++++
 docs/reference/cli.md    | 10 ++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs
index 67d142ddc..3c5f2e371 100644
--- a/crates/uv-cli/src/lib.rs
+++ b/crates/uv-cli/src/lib.rs
@@ -573,6 +573,13 @@ pub enum ProjectCommand {
     )]
     Sync(SyncArgs),
     /// Update the project's lockfile (experimental).
+    ///
+    /// If the project lockfile (`uv.lock`) does not exist, it will be created.
+    /// If a lockfile is present, its contents will be used as preferences for
+    /// the resolution.
+    ///
+    /// If there are no changes to the project's dependencies, locking will have
+    /// no effect unless the `--upgrade` flag is provided.
     #[command(
         after_help = "Use `uv help lock` for more details.",
         after_long_help = ""
@@ -2257,6 +2264,9 @@ pub struct SyncArgs {
 #[allow(clippy::struct_excessive_bools)]
 pub struct LockArgs {
     /// Assert that the `uv.lock` will remain unchanged.
+    ///
+    /// Requires that the lockfile is up-to-date. If the lockfile is missing or
+    /// needs to be updated, uv will exit with an error.
     #[arg(long, conflicts_with = "frozen")]
     pub locked: bool,
 
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index d12116f6d..57f870ed9 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -1262,7 +1262,11 @@ uv sync [OPTIONS]
 
 ## uv lock
 
-Update the project's lockfile (experimental)
+Update the project's lockfile (experimental).
+
+If the project lockfile (`uv.lock`) does not exist, it will be created. If a lockfile is present, its contents will be used as preferences for the resolution.
+
+If there are no changes to the project's dependencies, locking will have no effect unless the `--upgrade` flag is provided.
 
 <h3 class="cli-reference">Usage</h3>
 
@@ -1363,7 +1367,9 @@ uv lock [OPTIONS]
 
 <li><code>symlink</code>:  Symbolically link packages from the wheel into the <code>site-packages</code> directory</li>
 </ul>
-</dd><dt><code>--locked</code></dt><dd><p>Assert that the <code>uv.lock</code> will remain unchanged</p>
+</dd><dt><code>--locked</code></dt><dd><p>Assert that the <code>uv.lock</code> will remain unchanged.</p>
+
+<p>Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.</p>
 
 </dd><dt><code>--native-tls</code></dt><dd><p>Whether to load TLS certificates from the platform&#8217;s native certificate store.</p>