book/src/usage.md

   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 every 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 #### Command line
  31
  32 You can configure lint levels on the command line by adding
  33 `-A/W/D clippy::lint_name` like this:
  34
  35 ```bash
  36 cargo clippy -- -Aclippy::style -Wclippy::double_neg -Dclippy::perf
  37 ```
  38
  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`.
  41
  42 ```
  43 cargo clippy -- -Dwarnings
  44 ```
  45
  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.
  48 > `dead_code`, etc.).
  49
  50 For more information on configuring lint levels, see the [rustc documentation].
  51
  52 [rustc documentation]: https://doc.rust-lang.org/rustc/lints/levels.html#configuring-warning-levels
  53
  54 #### Even more lints
  55
  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.
  58
  59 For a full list of all lints with their description and examples, please refer
  60 to [Clippy's lint list]. The two most important allow-by-default groups are
  61 described below:
  62
  63 [Clippy's lint list]: https://rust-lang.github.io/rust-clippy/master/index.html
  64
  65 ##### `clippy::pedantic`
  66
  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.
  72
  73 > FYI: Clippy uses the whole group to lint itself.
  74
  75 ##### `clippy::restriction`
  76
  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.
  81
  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!
  84
  85 #### Too many lints
  86
  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.
  91
  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)
  95
  96 #### Source Code
  97
  98 You can configure lint levels in source code the same way you can configure
  99 `rustc` lints:
 100
 101 ```rust
 102 #![allow(clippy::style)]
 103
 104 #[warn(clippy::double_neg)]
 105 fn main() {
 106     let x = 1;
 107     let y = --x;
 108     //      ^^ warning: double negation
 109 }
 110 ```
 111
 112 ### Automatically applying Clippy suggestions
 113
 114 Clippy can automatically apply some lint suggestions, just like the compiler.
 115
 116 ```terminal
 117 cargo clippy --fix
 118 ```
 119
 120 ### Workspaces
 121
 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:
 124
 125 ```terminal
 126 cargo clippy -p example
 127 ```
 128
 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:
 132
 133 ```terminal
 134 cargo clippy -p example -- --no-deps
 135 ```
 136
 137 ## Using Clippy without `cargo`: `clippy-driver`
 138
 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:
 141
 142 ```terminal
 143 clippy-driver --edition 2018 -Cpanic=abort foo.rs
 144 ```
 145
 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.
 149
 150 [Installation]: installation.md
 151 [CI]: continuous_integration/index.md