Improve the uv lock CLI documentation (#5932)

astral-sh · Aug 9, 2024 · 892bbe8 · 892bbe8
1 parent 448e488
commit 892bbe8
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 2 deletions.
diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs
@@ -586,6 +586,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 = ""
@@ -2287,6 +2294,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
@@ -1278,7 +1278,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>
 
@@ -1379,7 +1383,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>