Skip to content

Commit 26b2e74

Browse files
weihangloweihanglo
committed
docs: clarify --locked disallows changes in Cargo.lock 
1 parent e549bc8 commit 26b2e74

File tree

109 files changed

+806
-412
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

109 files changed

+806
-412
lines changed

‎src/bin/cargo/cli.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -640,7 +640,7 @@ See '<cyan,bold>cargo help</> <cyan><<command>></>' for more information on a sp
640640
.value_parser(clap::builder::ValueParser::path_buf()),
641641
)
642642
.arg(
643-
flag("locked", "Require Cargo.lock to be up-to-date")
643+
flag("locked", "Assert that `Cargo.lock` will remain unchanged")
644644
.help_heading(heading::MANIFEST_OPTIONS)
645645
.global(true),
646646
)

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -172,13 +172,18 @@ OPTIONS
172172
Add dependencies to only the specified package.
173173

174174
--locked
175-
Requires the Cargo.lock file be up-to-date. If the lock file is
176-
missing, or it needs to be updated due to changes in the Cargo.toml
177-
file, for example a new dependency is added, Cargo will exit with an
178-
error.
175+
Asserts that the exact same dependencies and versions are used as
176+
when the existing Cargo.lock file was originally generated. Cargo
177+
will exit with an error when either of the following scenarios
178+
arises:
179179

180-
It may be used in environments where you want to assert that the
181-
Cargo.lock file is up-to-date (such as a CI build).
180+
o The lock file is missing.
181+
182+
o Cargo attempted to change the lock file due to a different
183+
dependency resolution.
184+
185+
It may be used in environments where deterministic builds are
186+
desired, such as in CI pipelines.
182187

183188
--offline
184189
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -339,13 +339,18 @@ OPTIONS
339339
Cargo.toml file in the current directory or any parent directory.
340340

341341
--locked
342-
Requires the Cargo.lock file be up-to-date. If the lock file is
343-
missing, or it needs to be updated due to changes in the Cargo.toml
344-
file, for example a new dependency is added, Cargo will exit with an
345-
error.
342+
Asserts that the exact same dependencies and versions are used as
343+
when the existing Cargo.lock file was originally generated. Cargo
344+
will exit with an error when either of the following scenarios
345+
arises:
346346

347-
It may be used in environments where you want to assert that the
348-
Cargo.lock file is up-to-date (such as a CI build).
347+
o The lock file is missing.
348+
349+
o Cargo attempted to change the lock file due to a different
350+
dependency resolution.
351+
352+
It may be used in environments where deterministic builds are
353+
desired, such as in CI pipelines.
349354

350355
--offline
351356
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -273,13 +273,18 @@ OPTIONS
273273
Cargo.toml file in the current directory or any parent directory.
274274

275275
--locked
276-
Requires the Cargo.lock file be up-to-date. If the lock file is
277-
missing, or it needs to be updated due to changes in the Cargo.toml
278-
file, for example a new dependency is added, Cargo will exit with an
279-
error.
276+
Asserts that the exact same dependencies and versions are used as
277+
when the existing Cargo.lock file was originally generated. Cargo
278+
will exit with an error when either of the following scenarios
279+
arises:
280280

281-
It may be used in environments where you want to assert that the
282-
Cargo.lock file is up-to-date (such as a CI build).
281+
o The lock file is missing.
282+
283+
o Cargo attempted to change the lock file due to a different
284+
dependency resolution.
285+
286+
It may be used in environments where deterministic builds are
287+
desired, such as in CI pipelines.
283288

284289
--offline
285290
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -258,13 +258,18 @@ OPTIONS
258258
Cargo.toml file in the current directory or any parent directory.
259259

260260
--locked
261-
Requires the Cargo.lock file be up-to-date. If the lock file is
262-
missing, or it needs to be updated due to changes in the Cargo.toml
263-
file, for example a new dependency is added, Cargo will exit with an
264-
error.
261+
Asserts that the exact same dependencies and versions are used as
262+
when the existing Cargo.lock file was originally generated. Cargo
263+
will exit with an error when either of the following scenarios
264+
arises:
265265

266-
It may be used in environments where you want to assert that the
267-
Cargo.lock file is up-to-date (such as a CI build).
266+
o The lock file is missing.
267+
268+
o Cargo attempted to change the lock file due to a different
269+
dependency resolution.
270+
271+
It may be used in environments where deterministic builds are
272+
desired, such as in CI pipelines.
268273

269274
--offline
270275
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -92,13 +92,18 @@ OPTIONS
9292
Cargo.toml file in the current directory or any parent directory.
9393

9494
--locked
95-
Requires the Cargo.lock file be up-to-date. If the lock file is
96-
missing, or it needs to be updated due to changes in the Cargo.toml
97-
file, for example a new dependency is added, Cargo will exit with an
98-
error.
95+
Asserts that the exact same dependencies and versions are used as
96+
when the existing Cargo.lock file was originally generated. Cargo
97+
will exit with an error when either of the following scenarios
98+
arises:
9999

100-
It may be used in environments where you want to assert that the
101-
Cargo.lock file is up-to-date (such as a CI build).
100+
o The lock file is missing.
101+
102+
o Cargo attempted to change the lock file due to a different
103+
dependency resolution.
104+
105+
It may be used in environments where deterministic builds are
106+
desired, such as in CI pipelines.
102107

103108
--offline
104109
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -229,13 +229,18 @@ OPTIONS
229229
Cargo.toml file in the current directory or any parent directory.
230230

231231
--locked
232-
Requires the Cargo.lock file be up-to-date. If the lock file is
233-
missing, or it needs to be updated due to changes in the Cargo.toml
234-
file, for example a new dependency is added, Cargo will exit with an
235-
error.
232+
Asserts that the exact same dependencies and versions are used as
233+
when the existing Cargo.lock file was originally generated. Cargo
234+
will exit with an error when either of the following scenarios
235+
arises:
236236

237-
It may be used in environments where you want to assert that the
238-
Cargo.lock file is up-to-date (such as a CI build).
237+
o The lock file is missing.
238+
239+
o Cargo attempted to change the lock file due to a different
240+
dependency resolution.
241+
242+
It may be used in environments where deterministic builds are
243+
desired, such as in CI pipelines.
239244

240245
--offline
241246
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -72,13 +72,18 @@ OPTIONS
7272
Cargo.toml file in the current directory or any parent directory.
7373

7474
--locked
75-
Requires the Cargo.lock file be up-to-date. If the lock file is
76-
missing, or it needs to be updated due to changes in the Cargo.toml
77-
file, for example a new dependency is added, Cargo will exit with an
78-
error.
75+
Asserts that the exact same dependencies and versions are used as
76+
when the existing Cargo.lock file was originally generated. Cargo
77+
will exit with an error when either of the following scenarios
78+
arises:
7979

80-
It may be used in environments where you want to assert that the
81-
Cargo.lock file is up-to-date (such as a CI build).
80+
o The lock file is missing.
81+
82+
o Cargo attempted to change the lock file due to a different
83+
dependency resolution.
84+
85+
It may be used in environments where deterministic builds are
86+
desired, such as in CI pipelines.
8287

8388
--offline
8489
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -331,13 +331,18 @@ OPTIONS
331331
Cargo.toml file in the current directory or any parent directory.
332332

333333
--locked
334-
Requires the Cargo.lock file be up-to-date. If the lock file is
335-
missing, or it needs to be updated due to changes in the Cargo.toml
336-
file, for example a new dependency is added, Cargo will exit with an
337-
error.
334+
Asserts that the exact same dependencies and versions are used as
335+
when the existing Cargo.lock file was originally generated. Cargo
336+
will exit with an error when either of the following scenarios
337+
arises:
338338

339-
It may be used in environments where you want to assert that the
340-
Cargo.lock file is up-to-date (such as a CI build).
339+
o The lock file is missing.
340+
341+
o Cargo attempted to change the lock file due to a different
342+
dependency resolution.
343+
344+
It may be used in environments where deterministic builds are
345+
desired, such as in CI pipelines.
341346

342347
--offline
343348
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,18 @@ OPTIONS
4747
Cargo.toml file in the current directory or any parent directory.
4848

4949
--locked
50-
Requires the Cargo.lock file be up-to-date. If the lock file is
51-
missing, or it needs to be updated due to changes in the Cargo.toml
52-
file, for example a new dependency is added, Cargo will exit with an
53-
error.
50+
Asserts that the exact same dependencies and versions are used as
51+
when the existing Cargo.lock file was originally generated. Cargo
52+
will exit with an error when either of the following scenarios
53+
arises:
5454

55-
It may be used in environments where you want to assert that the
56-
Cargo.lock file is up-to-date (such as a CI build).
55+
o The lock file is missing.
56+
57+
o Cargo attempted to change the lock file due to a different
58+
dependency resolution.
59+
60+
It may be used in environments where deterministic builds are
61+
desired, such as in CI pipelines.
5762

5863
--offline
5964
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -243,13 +243,18 @@ OPTIONS
243243

244244
Manifest Options
245245
--locked
246-
Requires the Cargo.lock file be up-to-date. If the lock file is
247-
missing, or it needs to be updated due to changes in the Cargo.toml
248-
file, for example a new dependency is added, Cargo will exit with an
249-
error.
246+
Asserts that the exact same dependencies and versions are used as
247+
when the existing Cargo.lock file was originally generated. Cargo
248+
will exit with an error when either of the following scenarios
249+
arises:
250250

251-
It may be used in environments where you want to assert that the
252-
Cargo.lock file is up-to-date (such as a CI build).
251+
o The lock file is missing.
252+
253+
o Cargo attempted to change the lock file due to a different
254+
dependency resolution.
255+
256+
It may be used in environments where deterministic builds are
257+
desired, such as in CI pipelines.
253258

254259
--offline
255260
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -405,13 +405,18 @@ OPTIONS
405405
Cargo.toml file in the current directory or any parent directory.
406406

407407
--locked
408-
Requires the Cargo.lock file be up-to-date. If the lock file is
409-
missing, or it needs to be updated due to changes in the Cargo.toml
410-
file, for example a new dependency is added, Cargo will exit with an
411-
error.
408+
Asserts that the exact same dependencies and versions are used as
409+
when the existing Cargo.lock file was originally generated. Cargo
410+
will exit with an error when either of the following scenarios
411+
arises:
412412

413-
It may be used in environments where you want to assert that the
414-
Cargo.lock file is up-to-date (such as a CI build).
413+
o The lock file is missing.
414+
415+
o Cargo attempted to change the lock file due to a different
416+
dependency resolution.
417+
418+
It may be used in environments where deterministic builds are
419+
desired, such as in CI pipelines.
415420

416421
--offline
417422
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -159,13 +159,18 @@ OPTIONS
159159
Cargo.toml file in the current directory or any parent directory.
160160

161161
--locked
162-
Requires the Cargo.lock file be up-to-date. If the lock file is
163-
missing, or it needs to be updated due to changes in the Cargo.toml
164-
file, for example a new dependency is added, Cargo will exit with an
165-
error.
162+
Asserts that the exact same dependencies and versions are used as
163+
when the existing Cargo.lock file was originally generated. Cargo
164+
will exit with an error when either of the following scenarios
165+
arises:
166166

167-
It may be used in environments where you want to assert that the
168-
Cargo.lock file is up-to-date (such as a CI build).
167+
o The lock file is missing.
168+
169+
o Cargo attempted to change the lock file due to a different
170+
dependency resolution.
171+
172+
It may be used in environments where deterministic builds are
173+
desired, such as in CI pipelines.
169174

170175
--offline
171176
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -85,13 +85,18 @@ OPTIONS
8585
Cargo.toml file in the current directory or any parent directory.
8686

8787
--locked
88-
Requires the Cargo.lock file be up-to-date. If the lock file is
89-
missing, or it needs to be updated due to changes in the Cargo.toml
90-
file, for example a new dependency is added, Cargo will exit with an
91-
error.
88+
Asserts that the exact same dependencies and versions are used as
89+
when the existing Cargo.lock file was originally generated. Cargo
90+
will exit with an error when either of the following scenarios
91+
arises:
9292

93-
It may be used in environments where you want to assert that the
94-
Cargo.lock file is up-to-date (such as a CI build).
93+
o The lock file is missing.
94+
95+
o Cargo attempted to change the lock file due to a different
96+
dependency resolution.
97+
98+
It may be used in environments where deterministic builds are
99+
desired, such as in CI pipelines.
95100

96101
--offline
97102
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -129,13 +129,18 @@ OPTIONS
129129
Cargo.toml file in the current directory or any parent directory.
130130

131131
--locked
132-
Requires the Cargo.lock file be up-to-date. If the lock file is
133-
missing, or it needs to be updated due to changes in the Cargo.toml
134-
file, for example a new dependency is added, Cargo will exit with an
135-
error.
132+
Asserts that the exact same dependencies and versions are used as
133+
when the existing Cargo.lock file was originally generated. Cargo
134+
will exit with an error when either of the following scenarios
135+
arises:
136136

137-
It may be used in environments where you want to assert that the
138-
Cargo.lock file is up-to-date (such as a CI build).
137+
o The lock file is missing.
138+
139+
o Cargo attempted to change the lock file due to a different
140+
dependency resolution.
141+
142+
It may be used in environments where deterministic builds are
143+
desired, such as in CI pipelines.
139144

140145
--offline
141146
Prevents Cargo from accessing the network for any reason. Without

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -62,13 +62,18 @@ OPTIONS
6262
Cargo.toml file in the current directory or any parent directory.
6363

6464
--locked
65-
Requires the Cargo.lock file be up-to-date. If the lock file is
66-
missing, or it needs to be updated due to changes in the Cargo.toml
67-
file, for example a new dependency is added, Cargo will exit with an
68-
error.
65+
Asserts that the exact same dependencies and versions are used as
66+
when the existing Cargo.lock file was originally generated. Cargo
67+
will exit with an error when either of the following scenarios
68+
arises:
6969

70-
It may be used in environments where you want to assert that the
71-
Cargo.lock file is up-to-date (such as a CI build).
70+
o The lock file is missing.
71+
72+
o Cargo attempted to change the lock file due to a different
73+
dependency resolution.
74+
75+
It may be used in environments where deterministic builds are
76+
desired, such as in CI pipelines.
7277

7378
--offline
7479
Prevents Cargo from accessing the network for any reason. Without

0 commit comments

Comments
 (0)