docs: clarify --locked flag only uses deps from Cargo.lock

src/bin/cargo/cli.rs

@@ -640,7 +640,7 @@ See '<cyan,bold>cargo help</> <cyan><<command>></>' for more information on a sp
                 .value_parser(clap::builder::ValueParser::path_buf()),
         )
         .arg(
-            flag("locked", "Require Cargo.lock to be up-to-date")
+            flag("locked", "Ensure the exact dependency versions in Cargo.lock is used")
                 .help_heading(heading::MANIFEST_OPTIONS)
                 .global(true),
         )

src/doc/man/generated_txt/cargo-add.txt

@@ -172,13 +172,18 @@ OPTIONS
            Add dependencies to only the specified package.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-bench.txt

@@ -339,13 +339,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-build.txt

@@ -273,13 +273,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-check.txt

@@ -258,13 +258,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-clean.txt

@@ -92,13 +92,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-doc.txt

@@ -229,13 +229,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-fetch.txt

@@ -72,13 +72,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-fix.txt

@@ -331,13 +331,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-generate-lockfile.txt

@@ -47,13 +47,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-install.txt

@@ -243,13 +243,18 @@ OPTIONS
 
    Manifest Options
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-metadata.txt

@@ -405,13 +405,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-package.txt

@@ -159,13 +159,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-pkgid.txt

@@ -85,13 +85,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-publish.txt

@@ -129,13 +129,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-remove.txt

@@ -62,13 +62,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without

src/doc/man/generated_txt/cargo-run.txt

@@ -177,13 +177,18 @@ OPTIONS
            Cargo.toml file in the current directory or any parent directory.
 
        --locked
-           Requires the Cargo.lock file be up-to-date. If the lock file is
-           missing, or it needs to be updated due to changes in the Cargo.toml
-           file, for example a new dependency is added, Cargo will exit with an
-           error.
+           Ensures that Cargo uses the exact version of every dependency
+           captured in the existing Cargo.lock file. Cargo will exit with an
+           error when either of the following scenarios arises:
+
+           o  The lock file is missing.
+
+           o  The dependency resolution has changed, often caused by modifying
+              dependencies in the Cargo.toml file.
 
            It may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build).
+           Cargo.lock file is up-to-date for reproducibility reasons, such as
+           in a CI build.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without