README.md

   1 # Clippy
   2
   3 [![Clippy Test](https://github.com/rust-lang/rust-clippy/workflows/Clippy%20Test%20(bors)/badge.svg?branch=auto&event=push)](https://github.com/rust-lang/rust-clippy/actions?query=workflow%3A%22Clippy+Test+(bors)%22+event%3Apush+branch%3Aauto)
   4 [![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/clippy.svg)](#license)
   5
   6 A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code.
   7
   8 [There are over 550 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html)
   9
  10 Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html).
  11 You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category.
  12
  13 | Category              | Description                                                                         | Default level |
  14 | --------------------- | ----------------------------------------------------------------------------------- | ------------- |
  15 | `clippy::all`         | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** |
  16 | `clippy::correctness` | code that is outright wrong or useless                                              | **deny**      |
  17 | `clippy::suspicious`  | code that is most likely wrong or useless                                           | **warn**      |
  18 | `clippy::style`       | code that should be written in a more idiomatic way                                 | **warn**      |
  19 | `clippy::complexity`  | code that does something simple but in a complex way                                | **warn**      |
  20 | `clippy::perf`        | code that can be written to run faster                                              | **warn**      |
  21 | `clippy::pedantic`    | lints which are rather strict or have occasional false positives                    | allow         |
  22 | `clippy::nursery`     | new lints that are still under development                                          | allow         |
  23 | `clippy::cargo`       | lints for the cargo manifest                                                        | allow         |
  24
  25 More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas!
  26
  27 The [lint list](https://rust-lang.github.io/rust-clippy/master/index.html) also contains "restriction lints", which are
  28 for things which are usually not considered "bad", but may be useful to turn on in specific cases. These should be used
  29 very selectively, if at all.
  30
  31 Table of contents:
  32
  33 *   [Usage instructions](#usage)
  34 *   [Configuration](#configuration)
  35 *   [Contributing](#contributing)
  36 *   [License](#license)
  37
  38 ## Usage
  39
  40 Below are instructions on how to use Clippy as a cargo subcommand,
  41 in projects that do not use cargo, or in Travis CI.
  42
  43 ### As a cargo subcommand (`cargo clippy`)
  44
  45 One way to use Clippy is by installing Clippy through rustup as a cargo
  46 subcommand.
  47
  48 #### Step 1: Install Rustup
  49
  50 You can install [Rustup](https://rustup.rs/) on supported platforms. This will help
  51 us install Clippy and its dependencies.
  52
  53 If you already have Rustup installed, update to ensure you have the latest
  54 Rustup and compiler:
  55
  56 ```terminal
  57 rustup update
  58 ```
  59
  60 #### Step 2: Install Clippy
  61
  62 Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command:
  63
  64 ```terminal
  65 rustup component add clippy
  66 ```
  67 If it says that it can't find the `clippy` component, please run `rustup self update`.
  68
  69 #### Step 3: Run Clippy
  70
  71 Now you can run Clippy by invoking the following command:
  72
  73 ```terminal
  74 cargo clippy
  75 ```
  76
  77 #### Automatically applying Clippy suggestions
  78
  79 Clippy can automatically apply some lint suggestions, just like the compiler.
  80
  81 ```terminal
  82 cargo clippy --fix
  83 ```
  84
  85 #### Workspaces
  86
  87 All the usual workspace options should work with Clippy. For example the following command
  88 will run Clippy on the `example` crate:
  89
  90 ```terminal
  91 cargo clippy -p example
  92 ```
  93
  94 As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies.
  95 If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this:
  96
  97 ```terminal
  98 cargo clippy -p example -- --no-deps
  99 ```
 100
 101 ### Using `clippy-driver`
 102
 103 Clippy can also be used in projects that do not use cargo. To do so, run `clippy-driver`
 104 with the same arguments you use for `rustc`. For example:
 105
 106 ```terminal
 107 clippy-driver --edition 2018 -Cpanic=abort foo.rs
 108 ```
 109
 110 Note that `clippy-driver` is designed for running Clippy only and should not be used as a general
 111 replacement for `rustc`. `clippy-driver` may produce artifacts that are not optimized as expected,
 112 for example.
 113
 114 ### Travis CI
 115
 116 You can add Clippy to Travis CI in the same way you use it locally:
 117
 118 ```yml
 119 language: rust
 120 rust:
 121   - stable
 122   - beta
 123 before_script:
 124   - rustup component add clippy
 125 script:
 126   - cargo clippy
 127   # if you want the build job to fail when encountering warnings, use
 128   - cargo clippy -- -D warnings
 129   # in order to also check tests and non-default crate features, use
 130   - cargo clippy --all-targets --all-features -- -D warnings
 131   - cargo test
 132   # etc.
 133 ```
 134
 135 Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code.
 136 That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause
 137 an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command
 138 line. (You can swap `clippy::all` with the specific lint category you are targeting.)
 139
 140 ## Configuration
 141
 142 ### Allowing/denying lints
 143
 144 You can add options to your code to `allow`/`warn`/`deny` Clippy lints:
 145
 146 *   the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`).
 147     Note that `rustc` has additional [lint groups](https://doc.rust-lang.org/rustc/lints/groups.html).
 148
 149 *   all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`,
 150     `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive
 151     lints prone to false positives.
 152
 153 *   only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.)
 154
 155 *   `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc.
 156
 157 Note: `allow` means to suppress the lint for your code. With `warn` the lint
 158 will only emit a warning, while with `deny` the lint will emit an error, when
 159 triggering for your code. An error causes clippy to exit with an error code, so
 160 is useful in scripts like CI/CD.
 161
 162 If you do not want to include your lint levels in your code, you can globally
 163 enable/disable lints by passing extra flags to Clippy during the run:
 164
 165 To allow `lint_name`, run
 166
 167 ```terminal
 168 cargo clippy -- -A clippy::lint_name
 169 ```
 170
 171 And to warn on `lint_name`, run
 172
 173 ```terminal
 174 cargo clippy -- -W clippy::lint_name
 175 ```
 176
 177 This also works with lint groups. For example, you
 178 can run Clippy with warnings for all lints enabled:
 179 ```terminal
 180 cargo clippy -- -W clippy::pedantic
 181 ```
 182
 183 If you care only about a single lint, you can allow all others and then explicitly warn on
 184 the lint(s) you are interested in:
 185 ```terminal
 186 cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...
 187 ```
 188
 189 ### Configure the behavior of some lints
 190
 191 Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable =
 192 value` mapping e.g.
 193
 194 ```toml
 195 avoid-breaking-exported-api = false
 196 disallowed-names = ["toto", "tata", "titi"]
 197 ```
 198
 199 See the [list of configurable lints](https://rust-lang.github.io/rust-clippy/master/index.html#Configuration),
 200 the lint descriptions contain the names and meanings of these configuration variables.
 201
 202 For configurations that are a list type with default values such as
 203 [disallowed-names](https://rust-lang.github.io/rust-clippy/master/index.html#disallowed_names),
 204 you can use the unique value `".."` to extend the default values instead of replacing them.
 205
 206 ```toml
 207 # default of disallowed-names is ["foo", "baz", "quux"]
 208 disallowed-names = ["bar", ".."] # -> ["bar", "foo", "baz", "quux"]
 209 ```
 210
 211 > **Note**
 212 >
 213 > `clippy.toml` or `.clippy.toml` cannot be used to allow/deny lints.
 214
 215 To deactivate the “for further information visit *lint-link*” message you can
 216 define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
 217
 218 ### Specifying the minimum supported Rust version
 219
 220 Projects that intend to support old versions of Rust can disable lints pertaining to newer features by
 221 specifying the minimum supported Rust version (MSRV) in the clippy configuration file.
 222
 223 ```toml
 224 msrv = "1.30.0"
 225 ```
 226
 227 Alternatively, the [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
 228 in the `Cargo.toml` can be used.
 229
 230 ```toml
 231 # Cargo.toml
 232 rust-version = "1.30"
 233 ```
 234
 235 The MSRV can also be specified as an attribute, like below.
 236
 237 ```rust
 238 #![feature(custom_inner_attributes)]
 239 #![clippy::msrv = "1.30.0"]
 240
 241 fn main() {
 242   ...
 243 }
 244 ```
 245
 246 You can also omit the patch version when specifying the MSRV, so `msrv = 1.30`
 247 is equivalent to `msrv = 1.30.0`.
 248
 249 Note: `custom_inner_attributes` is an unstable feature, so it has to be enabled explicitly.
 250
 251 Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv)
 252
 253 ## Contributing
 254
 255 If you want to contribute to Clippy, you can find more information in [CONTRIBUTING.md](https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md).
 256
 257 ## License
 258
 259 Copyright 2014-2022 The Rust Project Developers
 260
 261 Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
 262 [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license
 263 <LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your
 264 option. Files in the project may not be
 265 copied, modified, or distributed except according to those terms.