fork/cargo

git clone https://git.julia.blue/fork/cargo

Weihang LoMake --allow-dirty imply --allow-staged (#15013)53a2fdf0c

0.88.0
19.8 KiB461 linesraw
1CARGO-FIX(1)
2
3NAME
4       cargo-fix — Automatically fix lint warnings reported by rustc
5
6SYNOPSIS
7       cargo fix [options]
8
9DESCRIPTION
10       This Cargo subcommand will automatically take rustc’s suggestions from
11       diagnostics like warnings and apply them to your source code. This is
12       intended to help automate tasks that rustc itself already knows how to
13       tell you to fix!
14
15       Executing cargo fix will under the hood execute cargo-check(1). Any
16       warnings applicable to your crate will be automatically fixed (if
17       possible) and all remaining warnings will be displayed when the check
18       process is finished. For example if you’d like to apply all fixes to
19       the current package, you can run:
20
21           cargo fix
22
23       which behaves the same as cargo check --all-targets.
24
25       cargo fix is only capable of fixing code that is normally compiled with
26       cargo check. If code is conditionally enabled with optional features,
27       you will need to enable those features for that code to be analyzed:
28
29           cargo fix --features foo
30
31       Similarly, other cfg expressions like platform-specific code will need
32       to pass --target to fix code for the given target.
33
34           cargo fix --target x86_64-pc-windows-gnu
35
36       If you encounter any problems with cargo fix or otherwise have any
37       questions or feature requests please don’t hesitate to file an issue
38       at <https://github.com/rust-lang/cargo>.
39
40   Edition migration
41       The cargo fix subcommand can also be used to migrate a package from one
42       edition
43       <https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html>
44       to the next. The general procedure is:
45
46       1. Run cargo fix --edition. Consider also using the --all-features flag
47          if your project has multiple features. You may also want to run cargo
48          fix --edition multiple times with different --target flags if your
49          project has platform-specific code gated by cfg attributes.
50
51       2. Modify Cargo.toml to set the edition field
52          <https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field>
53          to the new edition.
54
55       3. Run your project tests to verify that everything still works. If new
56          warnings are issued, you may want to consider running cargo fix again
57          (without the --edition flag) to apply any suggestions given by the
58          compiler.
59
60       And hopefully that’s it! Just keep in mind of the caveats mentioned
61       above that cargo fix cannot update code for inactive features or cfg
62       expressions. Also, in some rare cases the compiler is unable to
63       automatically migrate all code to the new edition, and this may require
64       manual changes after building with the new edition.
65
66OPTIONS
67   Fix options
68       --broken-code
69           Fix code even if it already has compiler errors. This is useful if
70           cargo fix fails to apply the changes. It will apply the changes and
71           leave the broken code in the working directory for you to inspect
72           and manually fix.
73
74       --edition
75           Apply changes that will update the code to the next edition. This
76           will not update the edition in the Cargo.toml manifest, which must
77           be updated manually after cargo fix --edition has finished.
78
79       --edition-idioms
80           Apply suggestions that will update code to the preferred style for
81           the current edition.
82
83       --allow-no-vcs
84           Fix code even if a VCS was not detected.
85
86       --allow-dirty
87           Fix code even if the working directory has changes (including staged
88           changes).
89
90       --allow-staged
91           Fix code even if the working directory has staged changes.
92
93   Package Selection
94       By default, when no package selection options are given, the packages
95       selected depend on the selected manifest file (based on the current
96       working directory if --manifest-path is not given). If the manifest is
97       the root of a workspace then the workspaces default members are
98       selected, otherwise only the package defined by the manifest will be
99       selected.
100
101       The default members of a workspace can be set explicitly with the
102       workspace.default-members key in the root manifest. If this is not set,
103       a virtual workspace will include all workspace members (equivalent to
104       passing --workspace), and a non-virtual workspace will include only the
105       root crate itself.
106
107       -p spec…, --package spec…
108           Fix only the specified packages. See cargo-pkgid(1) for the SPEC
109           format. This flag may be specified multiple times and supports
110           common Unix glob patterns like *, ? and []. However, to avoid your
111           shell accidentally expanding glob patterns before Cargo handles
112           them, you must use single quotes or double quotes around each
113           pattern.
114
115       --workspace
116           Fix all members in the workspace.
117
118       --all
119           Deprecated alias for --workspace.
120
121       --exclude SPEC…
122           Exclude the specified packages. Must be used in conjunction with the
123           --workspace flag. This flag may be specified multiple times and
124           supports common Unix glob patterns like *, ? and []. However, to
125           avoid your shell accidentally expanding glob patterns before Cargo
126           handles them, you must use single quotes or double quotes around
127           each pattern.
128
129   Target Selection
130       When no target selection options are given, cargo fix will fix all
131       targets (--all-targets implied). Binaries are skipped if they have
132       required-features that are missing.
133
134       Passing target selection flags will fix only the specified targets.
135
136       Note that --bin, --example, --test and --bench flags also support common
137       Unix glob patterns like *, ? and []. However, to avoid your shell
138       accidentally expanding glob patterns before Cargo handles them, you must
139       use single quotes or double quotes around each glob pattern.
140
141       --lib
142           Fix the package’s library.
143
144       --bin name…
145           Fix the specified binary. This flag may be specified multiple times
146           and supports common Unix glob patterns.
147
148       --bins
149           Fix all binary targets.
150
151       --example name…
152           Fix the specified example. This flag may be specified multiple times
153           and supports common Unix glob patterns.
154
155       --examples
156           Fix all example targets.
157
158       --test name…
159           Fix the specified integration test. This flag may be specified
160           multiple times and supports common Unix glob patterns.
161
162       --tests
163           Fix all targets that have the test = true manifest flag set. By
164           default this includes the library and binaries built as unittests,
165           and integration tests. Be aware that this will also build any
166           required dependencies, so the lib target may be built twice (once as
167           a unittest, and once as a dependency for binaries, integration
168           tests, etc.). Targets may be enabled or disabled by setting the test
169           flag in the manifest settings for the target.
170
171       --bench name…
172           Fix the specified benchmark. This flag may be specified multiple
173           times and supports common Unix glob patterns.
174
175       --benches
176           Fix all targets that have the bench = true manifest flag set. By
177           default this includes the library and binaries built as benchmarks,
178           and bench targets. Be aware that this will also build any required
179           dependencies, so the lib target may be built twice (once as a
180           benchmark, and once as a dependency for binaries, benchmarks, etc.).
181           Targets may be enabled or disabled by setting the bench flag in the
182           manifest settings for the target.
183
184       --all-targets
185           Fix all targets. This is equivalent to specifying --lib --bins
186           --tests --benches --examples.
187
188   Feature Selection
189       The feature flags allow you to control which features are enabled. When
190       no feature options are given, the default feature is activated for every
191       selected package.
192
193       See the features documentation
194       <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
195       for more details.
196
197       -F features, --features features
198           Space or comma separated list of features to activate. Features of
199           workspace members may be enabled with package-name/feature-name
200           syntax. This flag may be specified multiple times, which enables all
201           specified features.
202
203       --all-features
204           Activate all available features of all selected packages.
205
206       --no-default-features
207           Do not activate the default feature of the selected packages.
208
209   Compilation Options
210       --target triple
211           Fix for the given architecture. The default is the host
212           architecture. The general format of the triple is
213           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
214           a list of supported targets. This flag may be specified multiple
215           times.
216
217           This may also be specified with the build.target config value
218           <https://doc.rust-lang.org/cargo/reference/config.html>.
219
220           Note that specifying this flag makes Cargo run in a different mode
221           where the target artifacts are placed in a separate directory. See
222           the build cache
223           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
224           documentation for more details.
225
226       -r, --release
227           Fix optimized artifacts with the release profile. See also the
228           --profile option for choosing a specific profile by name.
229
230       --profile name
231           Fix with the given profile.
232
233           As a special case, specifying the test profile will also enable
234           checking in test mode which will enable checking tests and enable
235           the test cfg option. See rustc tests
236           <https://doc.rust-lang.org/rustc/tests/index.html> for more detail.
237
238           See the reference
239           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
240           details on profiles.
241
242       --timings=fmts
243           Output information how long each compilation takes, and track
244           concurrency information over time. Accepts an optional
245           comma-separated list of output formats; --timings without an
246           argument will default to --timings=html. Specifying an output format
247           (rather than the default) is unstable and requires
248           -Zunstable-options. Valid output formats:
249
250           o  html (unstable, requires -Zunstable-options): Write a
251              human-readable file cargo-timing.html to the target/cargo-timings
252              directory with a report of the compilation. Also write a report
253              to the same directory with a timestamp in the filename if you
254              want to look at older runs. HTML output is suitable for human
255              consumption only, and does not provide machine-readable timing
256              data.
257
258           o  json (unstable, requires -Zunstable-options): Emit
259              machine-readable JSON information about timing information.
260
261   Output Options
262       --target-dir directory
263           Directory for all generated artifacts and intermediate files. May
264           also be specified with the CARGO_TARGET_DIR environment variable, or
265           the build.target-dir config value
266           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
267           target in the root of the workspace.
268
269   Display Options
270       -v, --verbose
271           Use verbose output. May be specified twice for “very verbose”
272           output which includes extra output such as dependency warnings and
273           build script output. May also be specified with the term.verbose
274           config value
275           <https://doc.rust-lang.org/cargo/reference/config.html>.
276
277       -q, --quiet
278           Do not print cargo log messages. May also be specified with the
279           term.quiet config value
280           <https://doc.rust-lang.org/cargo/reference/config.html>.
281
282       --color when
283           Control when colored output is used. Valid values:
284
285           o  auto (default): Automatically detect if color support is
286              available on the terminal.
287
288           o  always: Always display colors.
289
290           o  never: Never display colors.
291
292           May also be specified with the term.color config value
293           <https://doc.rust-lang.org/cargo/reference/config.html>.
294
295       --message-format fmt
296           The output format for diagnostic messages. Can be specified multiple
297           times and consists of comma-separated values. Valid values:
298
299           o  human (default): Display in a human-readable text format.
300              Conflicts with short and json.
301
302           o  short: Emit shorter, human-readable text messages. Conflicts with
303              human and json.
304
305           o  json: Emit JSON messages to stdout. See the reference
306              <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
307              for more details. Conflicts with human and short.
308
309           o  json-diagnostic-short: Ensure the rendered field of JSON messages
310              contains the “short” rendering from rustc. Cannot be used
311              with human or short.
312
313           o  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
314              messages contains embedded ANSI color codes for respecting
315              rustc’s default color scheme. Cannot be used with human or
316              short.
317
318           o  json-render-diagnostics: Instruct Cargo to not include rustc
319              diagnostics in JSON messages printed, but instead Cargo itself
320              should render the JSON diagnostics coming from rustc. Cargo’s
321              own JSON diagnostics and others coming from rustc are still
322              emitted. Cannot be used with human or short.
323
324   Manifest Options
325       --manifest-path path
326           Path to the Cargo.toml file. By default, Cargo searches for the
327           Cargo.toml file in the current directory or any parent directory.
328
329       --ignore-rust-version
330           Ignore rust-version specification in packages.
331
332       --locked
333           Asserts that the exact same dependencies and versions are used as
334           when the existing Cargo.lock file was originally generated. Cargo
335           will exit with an error when either of the following scenarios
336           arises:
337
338           o  The lock file is missing.
339
340           o  Cargo attempted to change the lock file due to a different
341              dependency resolution.
342
343           It may be used in environments where deterministic builds are
344           desired, such as in CI pipelines.
345
346       --offline
347           Prevents Cargo from accessing the network for any reason. Without
348           this flag, Cargo will stop with an error if it needs to access the
349           network and the network is not available. With this flag, Cargo will
350           attempt to proceed without the network if possible.
351
352           Beware that this may result in different dependency resolution than
353           online mode. Cargo will restrict itself to crates that are
354           downloaded locally, even if there might be a newer version as
355           indicated in the local copy of the index. See the cargo-fetch(1)
356           command to download dependencies before going offline.
357
358           May also be specified with the net.offline config value
359           <https://doc.rust-lang.org/cargo/reference/config.html>.
360
361       --frozen
362           Equivalent to specifying both --locked and --offline.
363
364       --lockfile-path PATH
365           Changes the path of the lockfile from the default
366           (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock
367           (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that
368           providing --lockfile-path will ignore existing lockfile at the
369           default path, and instead will either use the lockfile from PATH, or
370           write a new lockfile into the provided PATH if it doesn’t exist.
371           This flag can be used to run most commands in read-only directories,
372           writing lockfile into the provided PATH.
373
374           This option is only available on the nightly channel
375           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
376           requires the -Z unstable-options flag to enable (see #14421
377           <https://github.com/rust-lang/cargo/issues/14421>).
378
379   Common Options
380       +toolchain
381           If Cargo has been installed with rustup, and the first argument to
382           cargo begins with +, it will be interpreted as a rustup toolchain
383           name (such as +stable or +nightly). See the rustup documentation
384           <https://rust-lang.github.io/rustup/overrides.html> for more
385           information about how toolchain overrides work.
386
387       --config KEY=VALUE or PATH
388           Overrides a Cargo configuration value. The argument should be in
389           TOML syntax of KEY=VALUE, or provided as a path to an extra
390           configuration file. This flag may be specified multiple times. See
391           the command-line overrides section
392           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
393           for more information.
394
395       -C PATH
396           Changes the current working directory before executing any specified
397           operations. This affects things like where cargo looks by default
398           for the project manifest (Cargo.toml), as well as the directories
399           searched for discovering .cargo/config.toml, for example. This
400           option must appear before the command name, for example cargo -C
401           path/to/my-project build.
402
403           This option is only available on the nightly channel
404           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
405           requires the -Z unstable-options flag to enable (see #10098
406           <https://github.com/rust-lang/cargo/issues/10098>).
407
408       -h, --help
409           Prints help information.
410
411       -Z flag
412           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
413           details.
414
415   Miscellaneous Options
416       -j N, --jobs N
417           Number of parallel jobs to run. May also be specified with the
418           build.jobs config value
419           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
420           the number of logical CPUs. If negative, it sets the maximum number
421           of parallel jobs to the number of logical CPUs plus provided value.
422           If a string default is provided, it sets the value back to defaults.
423           Should not be 0.
424
425       --keep-going
426           Build as many crates in the dependency graph as possible, rather
427           than aborting the build on the first one that fails to build.
428
429           For example if the current package depends on dependencies fails and
430           works, one of which fails to build, cargo fix -j1 may or may not
431           build the one that succeeds (depending on which one of the two
432           builds Cargo picked to run first), whereas cargo fix -j1
433           --keep-going would definitely run both builds, even if the one run
434           first fails.
435
436ENVIRONMENT
437       See the reference
438       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
439       for details on environment variables that Cargo reads.
440
441EXIT STATUS
442       o  0: Cargo succeeded.
443
444       o  101: Cargo failed to complete.
445
446EXAMPLES
447       1. Apply compiler suggestions to the local package:
448
449              cargo fix
450
451       2. Update a package to prepare it for the next edition:
452
453              cargo fix --edition
454
455       3. Apply suggested idioms for the current edition:
456
457              cargo fix --edition-idioms
458
459SEE ALSO
460       cargo(1), cargo-check(1)
461