]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
1 | # Clippy |
2 | ||
487cf647 | 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) |
f20569fa XL |
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 | ||
9ffffee4 | 8 | [There are over 600 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html) |
f20569fa XL |
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 | ||
136023e0 | 13 | | Category | Description | Default level | |
353b0b11 | 14 | |-----------------------|-------------------------------------------------------------------------------------|---------------| |
136023e0 XL |
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** | | |
c295e0f8 | 21 | | `clippy::pedantic` | lints which are rather strict or have occasional false positives | allow | |
9ffffee4 | 22 | | `clippy::restriction` | lints which prevent the use of language and library features[^restrict] | allow | |
136023e0 XL |
23 | | `clippy::nursery` | new lints that are still under development | allow | |
24 | | `clippy::cargo` | lints for the cargo manifest | allow | | |
f20569fa XL |
25 | |
26 | More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas! | |
27 | ||
9ffffee4 FG |
28 | The `restriction` category should, *emphatically*, not be enabled as a whole. The contained |
29 | lints may lint against perfectly reasonable code, may not have an alternative suggestion, | |
30 | and may contradict any other lints (including other categories). Lints should be considered | |
31 | on a case-by-case basis before enabling. | |
32 | ||
33 | [^restrict]: Some use cases for `restriction` lints include: | |
34 | - Strict coding styles (e.g. [`clippy::else_if_without_else`]). | |
35 | - Additional restrictions on CI (e.g. [`clippy::todo`]). | |
36 | - Preventing panicking in certain functions (e.g. [`clippy::unwrap_used`]). | |
37 | - Running a lint only on a subset of code (e.g. `#[forbid(clippy::float_arithmetic)]` on a module). | |
38 | ||
39 | [`clippy::else_if_without_else`]: https://rust-lang.github.io/rust-clippy/master/index.html#else_if_without_else | |
40 | [`clippy::todo`]: https://rust-lang.github.io/rust-clippy/master/index.html#todo | |
41 | [`clippy::unwrap_used`]: https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used | |
42 | ||
43 | --- | |
f20569fa XL |
44 | |
45 | Table of contents: | |
46 | ||
9ffffee4 FG |
47 | * [Usage instructions](#usage) |
48 | * [Configuration](#configuration) | |
49 | * [Contributing](#contributing) | |
50 | * [License](#license) | |
f20569fa XL |
51 | |
52 | ## Usage | |
53 | ||
5099ac24 FG |
54 | Below are instructions on how to use Clippy as a cargo subcommand, |
55 | in projects that do not use cargo, or in Travis CI. | |
f20569fa XL |
56 | |
57 | ### As a cargo subcommand (`cargo clippy`) | |
58 | ||
59 | One way to use Clippy is by installing Clippy through rustup as a cargo | |
60 | subcommand. | |
61 | ||
c295e0f8 | 62 | #### Step 1: Install Rustup |
f20569fa | 63 | |
c295e0f8 | 64 | You can install [Rustup](https://rustup.rs/) on supported platforms. This will help |
f20569fa XL |
65 | us install Clippy and its dependencies. |
66 | ||
c295e0f8 XL |
67 | If you already have Rustup installed, update to ensure you have the latest |
68 | Rustup and compiler: | |
f20569fa XL |
69 | |
70 | ```terminal | |
71 | rustup update | |
72 | ``` | |
73 | ||
74 | #### Step 2: Install Clippy | |
75 | ||
76 | Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command: | |
77 | ||
78 | ```terminal | |
79 | rustup component add clippy | |
80 | ``` | |
9ffffee4 | 81 | |
f20569fa XL |
82 | If it says that it can't find the `clippy` component, please run `rustup self update`. |
83 | ||
84 | #### Step 3: Run Clippy | |
85 | ||
86 | Now you can run Clippy by invoking the following command: | |
87 | ||
88 | ```terminal | |
89 | cargo clippy | |
90 | ``` | |
91 | ||
92 | #### Automatically applying Clippy suggestions | |
93 | ||
136023e0 | 94 | Clippy can automatically apply some lint suggestions, just like the compiler. |
f20569fa XL |
95 | |
96 | ```terminal | |
136023e0 | 97 | cargo clippy --fix |
f20569fa XL |
98 | ``` |
99 | ||
100 | #### Workspaces | |
101 | ||
102 | All the usual workspace options should work with Clippy. For example the following command | |
103 | will run Clippy on the `example` crate: | |
104 | ||
105 | ```terminal | |
106 | cargo clippy -p example | |
107 | ``` | |
108 | ||
109 | As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies. | |
110 | If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this: | |
111 | ||
112 | ```terminal | |
136023e0 | 113 | cargo clippy -p example -- --no-deps |
f20569fa XL |
114 | ``` |
115 | ||
5099ac24 | 116 | ### Using `clippy-driver` |
f20569fa | 117 | |
5099ac24 FG |
118 | Clippy can also be used in projects that do not use cargo. To do so, run `clippy-driver` |
119 | with the same arguments you use for `rustc`. For example: | |
f20569fa XL |
120 | |
121 | ```terminal | |
122 | clippy-driver --edition 2018 -Cpanic=abort foo.rs | |
123 | ``` | |
124 | ||
5099ac24 FG |
125 | Note that `clippy-driver` is designed for running Clippy only and should not be used as a general |
126 | replacement for `rustc`. `clippy-driver` may produce artifacts that are not optimized as expected, | |
127 | for example. | |
f20569fa XL |
128 | |
129 | ### Travis CI | |
130 | ||
131 | You can add Clippy to Travis CI in the same way you use it locally: | |
132 | ||
353b0b11 | 133 | ```yaml |
f20569fa XL |
134 | language: rust |
135 | rust: | |
136 | - stable | |
137 | - beta | |
138 | before_script: | |
139 | - rustup component add clippy | |
140 | script: | |
141 | - cargo clippy | |
142 | # if you want the build job to fail when encountering warnings, use | |
143 | - cargo clippy -- -D warnings | |
144 | # in order to also check tests and non-default crate features, use | |
145 | - cargo clippy --all-targets --all-features -- -D warnings | |
146 | - cargo test | |
147 | # etc. | |
148 | ``` | |
149 | ||
150 | Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code. | |
151 | That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause | |
152 | an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command | |
153 | line. (You can swap `clippy::all` with the specific lint category you are targeting.) | |
154 | ||
155 | ## Configuration | |
156 | ||
f20569fa XL |
157 | ### Allowing/denying lints |
158 | ||
159 | You can add options to your code to `allow`/`warn`/`deny` Clippy lints: | |
160 | ||
9ffffee4 | 161 | * the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`). |
a2a8927a | 162 | Note that `rustc` has additional [lint groups](https://doc.rust-lang.org/rustc/lints/groups.html). |
f20569fa | 163 | |
9ffffee4 | 164 | * all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`, |
f20569fa XL |
165 | `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive |
166 | lints prone to false positives. | |
167 | ||
9ffffee4 | 168 | * only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.) |
f20569fa | 169 | |
9ffffee4 | 170 | * `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc. |
f20569fa XL |
171 | |
172 | Note: `allow` means to suppress the lint for your code. With `warn` the lint | |
173 | will only emit a warning, while with `deny` the lint will emit an error, when | |
174 | triggering for your code. An error causes clippy to exit with an error code, so | |
175 | is useful in scripts like CI/CD. | |
176 | ||
177 | If you do not want to include your lint levels in your code, you can globally | |
178 | enable/disable lints by passing extra flags to Clippy during the run: | |
179 | ||
180 | To allow `lint_name`, run | |
181 | ||
182 | ```terminal | |
183 | cargo clippy -- -A clippy::lint_name | |
184 | ``` | |
185 | ||
186 | And to warn on `lint_name`, run | |
187 | ||
188 | ```terminal | |
189 | cargo clippy -- -W clippy::lint_name | |
190 | ``` | |
191 | ||
a2a8927a | 192 | This also works with lint groups. For example, you |
f20569fa | 193 | can run Clippy with warnings for all lints enabled: |
9ffffee4 | 194 | |
f20569fa XL |
195 | ```terminal |
196 | cargo clippy -- -W clippy::pedantic | |
197 | ``` | |
198 | ||
199 | If you care only about a single lint, you can allow all others and then explicitly warn on | |
200 | the lint(s) you are interested in: | |
9ffffee4 | 201 | |
f20569fa XL |
202 | ```terminal |
203 | cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::... | |
204 | ``` | |
205 | ||
2b03887a FG |
206 | ### Configure the behavior of some lints |
207 | ||
208 | Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable = | |
209 | value` mapping e.g. | |
210 | ||
211 | ```toml | |
212 | avoid-breaking-exported-api = false | |
213 | disallowed-names = ["toto", "tata", "titi"] | |
2b03887a FG |
214 | ``` |
215 | ||
9ffffee4 FG |
216 | The [table of configurations](https://doc.rust-lang.org/nightly/clippy/lint_configuration.html) |
217 | contains all config values, their default, and a list of lints they affect. | |
218 | Each [configurable lint](https://rust-lang.github.io/rust-clippy/master/index.html#Configuration) | |
219 | , also contains information about these values. | |
220 | ||
221 | For configurations that are a list type with default values such as | |
222 | [disallowed-names](https://rust-lang.github.io/rust-clippy/master/index.html#disallowed_names), | |
223 | you can use the unique value `".."` to extend the default values instead of replacing them. | |
224 | ||
225 | ```toml | |
226 | # default of disallowed-names is ["foo", "baz", "quux"] | |
227 | disallowed-names = ["bar", ".."] # -> ["bar", "foo", "baz", "quux"] | |
228 | ``` | |
2b03887a FG |
229 | |
230 | > **Note** | |
231 | > | |
232 | > `clippy.toml` or `.clippy.toml` cannot be used to allow/deny lints. | |
233 | ||
2b03887a FG |
234 | To deactivate the “for further information visit *lint-link*” message you can |
235 | define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable. | |
236 | ||
f20569fa XL |
237 | ### Specifying the minimum supported Rust version |
238 | ||
239 | Projects that intend to support old versions of Rust can disable lints pertaining to newer features by | |
240 | specifying the minimum supported Rust version (MSRV) in the clippy configuration file. | |
241 | ||
242 | ```toml | |
243 | msrv = "1.30.0" | |
244 | ``` | |
245 | ||
064997fb FG |
246 | Alternatively, the [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) |
247 | in the `Cargo.toml` can be used. | |
248 | ||
249 | ```toml | |
250 | # Cargo.toml | |
251 | rust-version = "1.30" | |
252 | ``` | |
253 | ||
487cf647 | 254 | The MSRV can also be specified as an attribute, like below. |
f20569fa | 255 | |
353b0b11 | 256 | ```rust,ignore |
f20569fa XL |
257 | #![feature(custom_inner_attributes)] |
258 | #![clippy::msrv = "1.30.0"] | |
259 | ||
260 | fn main() { | |
261 | ... | |
262 | } | |
263 | ``` | |
264 | ||
265 | You can also omit the patch version when specifying the MSRV, so `msrv = 1.30` | |
266 | is equivalent to `msrv = 1.30.0`. | |
267 | ||
a2a8927a | 268 | Note: `custom_inner_attributes` is an unstable feature, so it has to be enabled explicitly. |
f20569fa XL |
269 | |
270 | Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv) | |
271 | ||
272 | ## Contributing | |
273 | ||
274 | 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). | |
275 | ||
276 | ## License | |
277 | ||
353b0b11 FG |
278 | <!-- REUSE-IgnoreStart --> |
279 | ||
5099ac24 | 280 | Copyright 2014-2022 The Rust Project Developers |
f20569fa XL |
281 | |
282 | Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
283 | [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license | |
284 | <LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your | |
285 | option. Files in the project may not be | |
286 | copied, modified, or distributed except according to those terms. | |
353b0b11 FG |
287 | |
288 | <!-- REUSE-IgnoreEnd --> |