3 This chapter describes how to use Clippy to get the most out of it. Clippy can
4 be used as a `cargo` subcommand or, like `rustc`, directly with the
5 `clippy-driver` binary.
7 > _Note:_ This chapter assumes that you have Clippy installed already. If you're
8 > not sure, take a look at the [Installation] chapter.
12 The easiest and most common way to run Clippy is through `cargo`. To do that,
19 ### Lint configuration
21 The above command will run the default set of lints, which are included in the
22 lint group `clippy::all`. You might want to use even more lints or you might not
23 agree with every Clippy lint, and for that there are ways to configure lint
26 > _Note:_ Clippy is meant to be used with a generous sprinkling of
27 > `#[allow(..)]`s through your code. So if you disagree with a lint, don't feel
28 > bad disabling them for parts of your code or the whole project.
32 You can configure lint levels on the command line by adding
33 `-A/W/D clippy::lint_name` like this:
36 cargo clippy -- -Aclippy::style -Wclippy::double_neg -Dclippy::perf
39 For [CI] all warnings can be elevated to errors which will inturn fail
40 the build and cause Clippy to exit with a code other than `0`.
43 cargo clippy -- -Dwarnings
46 > _Note:_ Adding `-D warnings` will cause your build to fail if **any** warnings
47 > are found in your code. That includes warnings found by rustc (e.g.
50 For more information on configuring lint levels, see the [rustc documentation].
52 [rustc documentation]: https://doc.rust-lang.org/rustc/lints/levels.html#configuring-warning-levels
56 Clippy has lint groups which are allow-by-default. This means, that you will
57 have to enable the lints in those groups manually.
59 For a full list of all lints with their description and examples, please refere
60 to [Clippy's lint list]. The two most important allow-by-default groups are
63 [Clippy's lint list]: https://rust-lang.github.io/rust-clippy/master/index.html
65 ##### `clippy::pedantic`
67 The first group is the `pedantic` group. This group contains really opinionated
68 lints, that may have some intentional false positives in order to prevent false
69 negatives. So while this group is ready to be used in production, you can expect
70 to sprinkle multiple `#[allow(..)]`s in your code. If you find any false
71 positives, you're still welcome to report them to us for future improvements.
73 > FYI: Clippy uses the whole group to lint itself.
75 ##### `clippy::restriction`
77 The second group is the `restriction` group. This group contains lints that
78 "restrict" the language in some way. For example the `clippy::unwrap` lint from
79 this group won't allow you to use `.unwrap()` in your code. You may want to look
80 through the lints in this group and enable the ones that fit your need.
82 > _Note:_ You shouldn't enable the whole lint group, but cherry-pick lints from
83 > this group. Some lints in this group will even contradict other Clippy lints!
87 The most opinionated warn-by-default group of Clippy is the `clippy::style`
88 group. Some people prefer to disable this group completely and then cherry-pick
89 some lints they like from this group. The same is of course possible with every
90 other of Clippy's lint groups.
92 > _Note:_ We try to keep the warn-by-default groups free from false positives
93 > (FP). If you find that a lint wrongly triggers, please report it in an issue
94 > (if there isn't an issue for that FP already)
98 You can configure lint levels in source code the same way you can configure
102 #![allow(clippy::style)]
104 #[warn(clippy::double_neg)]
108 // ^^ warning: double negation
112 ### Automatically applying Clippy suggestions
114 Clippy can automatically apply some lint suggestions, just like the compiler.
122 All the usual workspace options should work with Clippy. For example the
123 following command will run Clippy on the `example` crate in your workspace:
126 cargo clippy -p example
129 As with `cargo check`, this includes dependencies that are members of the
130 workspace, like path dependencies. If you want to run Clippy **only** on the
131 given crate, use the `--no-deps` option like this:
134 cargo clippy -p example -- --no-deps
137 ## Using Clippy without `cargo`: `clippy-driver`
139 Clippy can also be used in projects that do not use cargo. To do so, run
140 `clippy-driver` with the same arguments you use for `rustc`. For example:
143 clippy-driver --edition 2018 -Cpanic=abort foo.rs
146 > _Note:_ `clippy-driver` is designed for running Clippy and should not be used
147 > as a general replacement for `rustc`. `clippy-driver` may produce artifacts
148 > that are not optimized as expected, for example.
150 [Installation]: installation.md
151 [CI]: continuous_integration/index.md