Auto merge of #13665 - weihanglo:locked-frozen, r=epage

docs: clarify `--locked` ensures Cargo uses dependency versions in lockfile

src/bin/cargo/cli.rs

@@ -640,17 +640,17 @@ See '<cyan,bold>cargo help</> <cyan><<command>></>' for more information on a sp
                 .value_parser(clap::builder::ValueParser::path_buf()),
         )
         .arg(
-            flag("frozen", "Require Cargo.lock and cache to be up-to-date")
+            flag("locked", "Assert that `Cargo.lock` will remain unchanged")
                 .help_heading(heading::MANIFEST_OPTIONS)
                 .global(true),
         )
         .arg(
-            flag("locked", "Require Cargo.lock to be up-to-date")
+            flag("offline", "Run without accessing the network")
                 .help_heading(heading::MANIFEST_OPTIONS)
                 .global(true),
         )
         .arg(
-            flag("offline", "Run without accessing the network")
+            flag("frozen", "Equivalent to specifying both --locked and --offline")
                 .help_heading(heading::MANIFEST_OPTIONS)
                 .global(true),
         )

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

@@ -171,16 +171,19 @@ OPTIONS
        -p spec, --package spec
            Add dependencies to only the specified package.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -197,6 +200,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -338,16 +338,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -364,6 +367,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -272,16 +272,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -298,6 +301,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -257,16 +257,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -283,6 +286,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -91,16 +91,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -117,6 +120,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -228,16 +228,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -254,6 +257,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -71,16 +71,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -96,6 +99,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -330,16 +330,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -356,6 +359,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

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

@@ -46,16 +46,19 @@ OPTIONS
            Path to the Cargo.toml file. By default, Cargo searches for the
            Cargo.toml file in the current directory or any parent directory.
 
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file be
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           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:
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           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
@@ -72,6 +75,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to