|
| 1 | +# Usage |
| 2 | + |
| 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. |
| 6 | + |
| 7 | +> _Note:_ This chapter assumes that you have Clippy installed already. If you're |
| 8 | +> not sure, take a look at the [Installation] chapter. |
| 9 | +
|
| 10 | +## Cargo subcommand |
| 11 | + |
| 12 | +The easiest and most common way to run Clippy is through `cargo`. To do that, |
| 13 | +just run |
| 14 | + |
| 15 | +```bash |
| 16 | +cargo clippy |
| 17 | +``` |
| 18 | + |
| 19 | +### Lint configuration |
| 20 | + |
| 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 ever Clippy lint, and for that there are ways to configure lint |
| 24 | +levels. |
| 25 | + |
| 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. |
| 29 | +
|
| 30 | +#### Error on lints |
| 31 | + |
| 32 | +Instead of only emitting warnings you may want Clippy to emit errors and abort |
| 33 | +the compilation instead. This is especially useful if you run Clippy in [CI]. |
| 34 | +You can do that with |
| 35 | + |
| 36 | +``` |
| 37 | +cargo clippy -- -Dwarnings |
| 38 | +``` |
| 39 | + |
| 40 | +> _Note:_ that adding `-D warnings` will cause your build to fail if **any** |
| 41 | +> warnings are found in your code. That includes warnings found by rustc (e.g. |
| 42 | +> `dead_code`, etc.). If you want to avoid this and only cause an error for |
| 43 | +> Clippy warnings, use `-D clippy::all` on the command line. (You can swap |
| 44 | +> `clippy::all` with the specific lint category you are targeting.) |
| 45 | +
|
| 46 | +#### Even more lints |
| 47 | + |
| 48 | +Clippy has two lint groups which are allow-by-default. This means, that you will |
| 49 | +have to enable the lints in those groups manually. |
| 50 | + |
| 51 | +##### `clippy::pedantic` |
| 52 | + |
| 53 | +The first group is the `pedantic` group. This group contains really opinionated |
| 54 | +lints, that may have some intentional false positives in order to prevent false |
| 55 | +negatives. Clippy uses the whole group to lint itself. So while this group is |
| 56 | +ready to be used in production, you can expect to sprinkle multiple |
| 57 | +`#[allow(..)]`s in your code. |
| 58 | + |
| 59 | +##### `clippy::restriction` |
| 60 | + |
| 61 | +The second group is the `restriction` group. This group contains lints that |
| 62 | +"restrict" the language in some way. For example the `clippy::unwrap` lint from |
| 63 | +this group won't allow you to use `.unwrap()` in your code. You may want to look |
| 64 | +through the lints in this group and enable the ones that fit your need. |
| 65 | + |
| 66 | +> _Note:_ You shouldn't enable the whole lint group, but cherry-pick lints from |
| 67 | +> this group. Some lints in this group will even contradict other Clippy lints! |
| 68 | +
|
| 69 | +#### Too many lints |
| 70 | + |
| 71 | +The most opinionated warn-by-default group of Clippy is the `clippy::style` |
| 72 | +group. Some people prefer to disable this group completely and then cherry-pick |
| 73 | +some lints they like from this group. The same is of course possible with every |
| 74 | +other of Clippy's lint groups. |
| 75 | + |
| 76 | +> _Note:_ We try to keep the warn-by-default groups free from false positives |
| 77 | +> (FP). If you find that a lint wrongly triggers, please report it in an issue |
| 78 | +> (if there isn't an issue for that FP already) |
| 79 | +
|
| 80 | +#### Command line |
| 81 | + |
| 82 | +You can configure lint levels on the command line by adding |
| 83 | +`-Dclippy::lint_name` like this: |
| 84 | + |
| 85 | +```bash |
| 86 | +cargo clippy -- -Aclippy::style -Wclippy::double_neg |
| 87 | +``` |
| 88 | + |
| 89 | +#### Source Code |
| 90 | + |
| 91 | +You can configure lint levels in source code the same way you can configure |
| 92 | +`rustc` lints: |
| 93 | + |
| 94 | +```rust |
| 95 | +#![allow(clippy::style)] |
| 96 | + |
| 97 | +#[warn(clippy::double_neg)] |
| 98 | +fn main() { |
| 99 | + let x = 1; |
| 100 | + let y = --x; |
| 101 | + // ^^ warning: double negation |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +### Automatically applying Clippy suggestions |
| 106 | + |
| 107 | +Clippy can automatically apply some lint suggestions, just like the compiler. |
| 108 | + |
| 109 | +```terminal |
| 110 | +cargo clippy --fix |
| 111 | +``` |
| 112 | + |
| 113 | +### Workspaces |
| 114 | + |
| 115 | +All the usual workspace options should work with Clippy. For example the following command |
| 116 | +will run Clippy on the `example` crate: |
| 117 | + |
| 118 | +```terminal |
| 119 | +cargo clippy -p example |
| 120 | +``` |
| 121 | + |
| 122 | +As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies. |
| 123 | +If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this: |
| 124 | + |
| 125 | +```terminal |
| 126 | +cargo clippy -p example -- --no-deps |
| 127 | +``` |
| 128 | + |
| 129 | +## Using `clippy-driver` |
| 130 | + |
| 131 | +Clippy can also be used in projects that do not use cargo. To do so, run |
| 132 | +`clippy-driver` with the same arguments you use for `rustc`. For example: |
| 133 | + |
| 134 | +```terminal |
| 135 | +clippy-driver --edition 2018 -Cpanic=abort foo.rs |
| 136 | +``` |
| 137 | + |
| 138 | +Note that `clippy-driver` is designed for running Clippy only and should not be |
| 139 | +used as a general replacement for `rustc`. `clippy-driver` may produce artifacts |
| 140 | +that are not optimized as expected, for example. |
| 141 | + |
| 142 | +[Installation]: installation.md |
| 143 | +[CI]: continuous_integration |
0 commit comments