docs: clarify --locked disallows changes in 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", "Assert that `Cargo.lock` will remain unchanged")
                 .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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --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.
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
 
-           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).
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without