1# Clippy23[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/clippy.svg)](#license)45A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code.67[There are over 800 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html)89Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html).10You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category.1112| Category              | Description                                                                         | Default level |13|-----------------------|-------------------------------------------------------------------------------------|---------------|14| `clippy::all`         | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** |15| `clippy::correctness` | code that is outright wrong or useless                                              | **deny**      |16| `clippy::suspicious`  | code that is most likely wrong or useless                                           | **warn**      |17| `clippy::style`       | code that should be written in a more idiomatic way                                 | **warn**      |18| `clippy::complexity`  | code that does something simple but in a complex way                                | **warn**      |19| `clippy::perf`        | code that can be written to run faster                                              | **warn**      |20| `clippy::pedantic`    | lints which are rather strict or have occasional false positives                    | allow         |21| `clippy::restriction` | lints which prevent the use of language and library features[^restrict]             | allow         |22| `clippy::nursery`     | new lints that are still under development                                          | allow         |23| `clippy::cargo`       | lints for the cargo manifest                                                        | allow         |2425More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas!2627The `restriction` category should, *emphatically*, not be enabled as a whole. The contained28lints may lint against perfectly reasonable code, may not have an alternative suggestion,29and may contradict any other lints (including other categories). Lints should be considered30on a case-by-case basis before enabling.3132[^restrict]: Some use cases for `restriction` lints include:33    - Strict coding styles (e.g. [`clippy::else_if_without_else`]).34    - Additional restrictions on CI (e.g. [`clippy::todo`]).35    - Preventing panicking in certain functions (e.g. [`clippy::unwrap_used`]).36    - Running a lint only on a subset of code (e.g. `#[forbid(clippy::float_arithmetic)]` on a module).3738[`clippy::else_if_without_else`]: https://rust-lang.github.io/rust-clippy/master/index.html#else_if_without_else39[`clippy::todo`]: https://rust-lang.github.io/rust-clippy/master/index.html#todo40[`clippy::unwrap_used`]: https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used4142---4344Table of contents:4546* [Usage instructions](#usage)47* [Configuration](#configuration)48* [Contributing](#contributing)49* [License](#license)5051## Usage5253Below are instructions on how to use Clippy as a cargo subcommand,54in projects that do not use cargo, or in Travis CI.5556### As a cargo subcommand (`cargo clippy`)5758One way to use Clippy is by installing Clippy through rustup as a cargo59subcommand.6061#### Step 1: Install Rustup6263You can install [Rustup](https://rustup.rs/) on supported platforms. This will help64us install Clippy and its dependencies.6566If you already have Rustup installed, update to ensure you have the latest67Rustup and compiler:6869```terminal70rustup update71```7273#### Step 2: Install Clippy7475Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command:7677```terminal78rustup component add clippy79```8081If it says that it can't find the `clippy` component, please run `rustup self update`.8283#### Step 3: Run Clippy8485Now you can run Clippy by invoking the following command:8687```terminal88cargo clippy89```9091#### Automatically applying Clippy suggestions9293Clippy can automatically apply some lint suggestions, just like the compiler. Note that `--fix` implies94`--all-targets`, so it can fix as much code as it can.9596```terminal97cargo clippy --fix98```99100#### Workspaces101102All the usual workspace options should work with Clippy. For example the following command103will run Clippy on the `example` crate:104105```terminal106cargo clippy -p example107```108109As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies.110If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this:111112```terminal113cargo clippy -p example -- --no-deps114```115116### Using `clippy-driver`117118Clippy can also be used in projects that do not use cargo. To do so, run `clippy-driver`119with the same arguments you use for `rustc`. For example:120121```terminal122clippy-driver --edition 2018 -Cpanic=abort foo.rs123```124125Note that `clippy-driver` is designed for running Clippy only and should not be used as a general126replacement for `rustc`. `clippy-driver` may produce artifacts that are not optimized as expected,127for example.128129### Travis CI130131You can add Clippy to Travis CI in the same way you use it locally:132133```yaml134language: rust135rust:136  - stable137  - beta138before_script:139  - rustup component add clippy140script:141  - cargo clippy142  # if you want the build job to fail when encountering warnings, use143  - cargo clippy -- -D warnings144  # in order to also check tests and non-default crate features, use145  - cargo clippy --all-targets --all-features -- -D warnings146  - cargo test147  # etc.148```149150Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code.151That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause152an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command153line. (You can swap `clippy::all` with the specific lint category you are targeting.)154155## Configuration156157### Allowing/denying lints158159You can add options to your code to `allow`/`warn`/`deny` Clippy lints:160161* the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`).162  Note that `rustc` has additional [lint groups](https://doc.rust-lang.org/rustc/lints/groups.html).163164* all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`,165  `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive166  lints prone to false positives.167168* only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.)169170* `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc.171172Note: `allow` means to suppress the lint for your code. With `warn` the lint173will only emit a warning, while with `deny` the lint will emit an error, when174triggering for your code. An error causes Clippy to exit with an error code, so175is useful in scripts like CI/CD.176177If you do not want to include your lint levels in your code, you can globally178enable/disable lints by passing extra flags to Clippy during the run:179180To allow `lint_name`, run181182```terminal183cargo clippy -- -A clippy::lint_name184```185186And to warn on `lint_name`, run187188```terminal189cargo clippy -- -W clippy::lint_name190```191192This also works with lint groups. For example, you193can run Clippy with warnings for all lints enabled:194195```terminal196cargo clippy -- -W clippy::pedantic197```198199If you care only about a single lint, you can allow all others and then explicitly warn on200the lint(s) you are interested in:201202```terminal203cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...204```205206### Configure the behavior of some lints207208Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable =209value` mapping e.g.210211```toml212avoid-breaking-exported-api = false213disallowed-names = ["toto", "tata", "titi"]214```215216The [table of configurations](https://doc.rust-lang.org/nightly/clippy/lint_configuration.html)217contains all config values, their default, and a list of lints they affect.218Each [configurable lint](https://rust-lang.github.io/rust-clippy/master/index.html#Configuration)219, also contains information about these values.220221For configurations that are a list type with default values such as222[disallowed-names](https://rust-lang.github.io/rust-clippy/master/index.html#disallowed_names),223you can use the unique value `".."` to extend the default values instead of replacing them.224225```toml226# default of disallowed-names is ["foo", "baz", "quux"]227disallowed-names = ["bar", ".."] # -> ["bar", "foo", "baz", "quux"]228```229230> **Note**231>232> `clippy.toml` or `.clippy.toml` cannot be used to allow/deny lints.233234To deactivate the “for further information visit *lint-link*” message you can235define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.236237### Specifying the minimum supported Rust version238239Projects that intend to support old versions of Rust can disable lints pertaining to newer features by240specifying the minimum supported Rust version (MSRV) in the Clippy configuration file.241242```toml243msrv = "1.30.0"244```245246Alternatively, the [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)247in the `Cargo.toml` can be used.248249```toml250# Cargo.toml251rust-version = "1.30"252```253254The MSRV can also be specified as an attribute, like below.255256```rust,ignore257#![feature(custom_inner_attributes)]258#![clippy::msrv = "1.30.0"]259260fn main() {261  ...262}263```264265You can also omit the patch version when specifying the MSRV, so `msrv = 1.30`266is equivalent to `msrv = 1.30.0`.267268Note: `custom_inner_attributes` is an unstable feature, so it has to be enabled explicitly.269270Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv)271272## Contributing273274If 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).275276## License277278<!-- REUSE-IgnoreStart -->279280Copyright (c) The Rust Project Contributors281282Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or283[https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license284<LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your285option. Files in the project may not be286copied, modified, or distributed except according to those terms.287288<!-- REUSE-IgnoreEnd -->