## File: README.md # Clippy [](#license) A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code. [There are over 800 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html) Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html). You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category. | Category | Description | Default level | |-----------------------|-------------------------------------------------------------------------------------|---------------| | `clippy::all` | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** | | `clippy::correctness` | code that is outright wrong or useless | **deny** | | `clippy::suspicious` | code that is most likely wrong or useless | **warn** | | `clippy::style` | code that should be written in a more idiomatic way | **warn** | | `clippy::complexity` | code that does something simple but in a complex way | **warn** | | `clippy::perf` | code that can be written to run faster | **warn** | | `clippy::pedantic` | lints which are rather strict or have occasional false positives | allow | | `clippy::restriction` | lints which prevent the use of language and library features[^restrict] | allow | | `clippy::nursery` | new lints that are still under development | allow | | `clippy::cargo` | lints for the cargo manifest | allow | More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas! The `restriction` category should, *emphatically*, not be enabled as a whole. The contained lints may lint against perfectly reasonable code, may not have an alternative suggestion, and may contradict any other lints (including other categories). Lints should be considered on a case-by-case basis before enabling. [^restrict]: Some use cases for `restriction` lints include: - Strict coding styles (e.g. [`clippy::else_if_without_else`]). - Additional restrictions on CI (e.g. [`clippy::todo`]). - Preventing panicking in certain functions (e.g. [`clippy::unwrap_used`]). - Running a lint only on a subset of code (e.g. `#[forbid(clippy::float_arithmetic)]` on a module). [`clippy::else_if_without_else`]: https://rust-lang.github.io/rust-clippy/master/index.html#else_if_without_else [`clippy::todo`]: https://rust-lang.github.io/rust-clippy/master/index.html#todo [`clippy::unwrap_used`]: https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used --- Table of contents: * [Usage instructions](#usage) * [Configuration](#configuration) * [Contributing](#contributing) * [License](#license) ## Usage Below are instructions on how to use Clippy as a cargo subcommand, in projects that do not use cargo, or in Travis CI. ### As a cargo subcommand (`cargo clippy`) One way to use Clippy is by installing Clippy through rustup as a cargo subcommand. #### Step 1: Install Rustup You can install [Rustup](https://rustup.rs/) on supported platforms. This will help us install Clippy and its dependencies. If you already have Rustup installed, update to ensure you have the latest Rustup and compiler: ```terminal rustup update ``` #### Step 2: Install Clippy Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command: ```terminal rustup component add clippy ``` If it says that it can't find the `clippy` component, please run `rustup self update`. #### Step 3: Run Clippy Now you can run Clippy by invoking the following command: ```terminal cargo clippy ``` #### Automatically applying Clippy suggestions Clippy can automatically apply some lint suggestions, just like the compiler. Note that `--fix` implies `--all-targets`, so it can fix as much code as it can. ```terminal cargo clippy --fix ``` #### Workspaces All the usual workspace options should work with Clippy. For example the following command will run Clippy on the `example` crate: ```terminal cargo clippy -p example ``` As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies. If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this: ```terminal cargo clippy -p example -- --no-deps ``` ### Using `clippy-driver` Clippy can also be used in projects that do not use cargo. To do so, run `clippy-driver` with the same arguments you use for `rustc`. For example: ```terminal clippy-driver --edition 2018 -Cpanic=abort foo.rs ``` Note that `clippy-driver` is designed for running Clippy only and should not be used as a general replacement for `rustc`. `clippy-driver` may produce artifacts that are not optimized as expected, for example. ### Travis CI You can add Clippy to Travis CI in the same way you use it locally: ```yaml language: rust rust: - stable - beta before_script: - rustup component add clippy script: - cargo clippy # if you want the build job to fail when encountering warnings, use - CARGO_BUILD_WARNINGS=deny cargo clippy # in order to also check tests and non-default crate features, use - CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets --all-features - cargo test # etc. ``` Note that setting `CARGO_BUILD_WARNINGS=deny` will cause your build to fail if **any** warnings are found in your code. That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command line. (You can swap `clippy::all` with the specific lint category you are targeting.) Also note that before Cargo 1.97, the usual way to deny all warnings was by using `-D warnings`: ```shell cargo clippy -- -D warnings ``` However, [`CARGO_BUILD_WARNINGS`] has the benefit of not invalidating build caches, and is thus to be preferred going forward. ## Configuration ### Allowing/denying lints You can add options to your code to `allow`/`warn`/`deny` Clippy lints: * the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`). Note that `rustc` has additional [lint groups](https://doc.rust-lang.org/rustc/lints/groups.html). * all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`, `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive lints prone to false positives. * only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.) * `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc. Note: `allow` means to suppress the lint for your code. With `warn` the lint will only emit a warning, while with `deny` the lint will emit an error, when triggering for your code. An error causes Clippy to exit with an error code, so is useful in scripts like CI/CD. If you do not want to include your lint levels in your code, you can globally enable/disable lints by passing extra flags to Clippy during the run: To allow `lint_name`, run ```terminal cargo clippy -- -A clippy::lint_name ``` And to warn on `lint_name`, run ```terminal cargo clippy -- -W clippy::lint_name ``` This also works with lint groups. For example, you can run Clippy with warnings for all lints enabled: ```terminal cargo clippy -- -W clippy::pedantic ``` If you care only about a single lint, you can allow all others and then explicitly warn on the lint(s) you are interested in: ```terminal cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::... ``` ### Configure the behavior of some lints Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable = value` mapping e.g. ```toml avoid-breaking-exported-api = false disallowed-names = ["toto", "tata", "titi"] ``` The [table of configurations](https://doc.rust-lang.org/nightly/clippy/lint_configuration.html) contains all config values, their default, and a list of lints they affect. Each [configurable lint](https://rust-lang.github.io/rust-clippy/master/index.html#Configuration) , also contains information about these values. For configurations that are a list type with default values such as [disallowed-names](https://rust-lang.github.io/rust-clippy/master/index.html#disallowed_names), you can use the unique value `".."` to extend the default values instead of replacing them. ```toml # default of disallowed-names is ["foo", "baz", "quux"] disallowed-names = ["bar", ".."] # -> ["bar", "foo", "baz", "quux"] ``` > **Note** > > `clippy.toml` or `.clippy.toml` cannot be used to allow/deny lints. To deactivate the “for further information visit *lint-link*” message you can define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable. ### Specifying the minimum supported Rust version Projects that intend to support old versions of Rust can disable lints pertaining to newer features by specifying the minimum supported Rust version (MSRV) in the Clippy configuration file. ```toml msrv = "1.30.0" ``` Alternatively, the [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) in the `Cargo.toml` can be used. ```toml # Cargo.toml rust-version = "1.30" ``` The MSRV can also be specified as an attribute, like below. ```rust,ignore #![feature(custom_inner_attributes)] #![clippy::msrv = "1.30.0"] fn main() { ... } ``` You can also omit the patch version when specifying the MSRV, so `msrv = 1.30` is equivalent to `msrv = 1.30.0`. Note: `custom_inner_attributes` is an unstable feature, so it has to be enabled explicitly. Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv) ## Contributing 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). ## License Copyright (c) The Rust Project Contributors Licensed under the Apache License, Version 2.0 or the MIT license , at your option. Files in the project may not be copied, modified, or distributed except according to those terms. [`CARGO_BUILD_WARNINGS`]: https://doc.rust-lang.org/cargo/reference/config.html#buildwarnings --- ## File: book/src/continuous_integration/README.md # Continuous Integration It is recommended to run Clippy on CI with `-Dwarnings`, so that Clippy lints prevent CI from passing. To enforce errors on warnings on all `cargo` commands not just `cargo clippy`, you can set the env var `RUSTFLAGS="-Dwarnings"`. We recommend to use Clippy from the same toolchain, that you use for compiling your crate for maximum compatibility. E.g. if your crate is compiled with the `stable` toolchain, you should also use `stable` Clippy. > _Note:_ New Clippy lints are first added to the `nightly` toolchain. If you > want to help with improving Clippy and have CI resources left, please consider > adding a `nightly` Clippy check to your CI and report problems like false > positives back to us. With that we can fix bugs early, before they can get to > stable. This chapter will give an overview on how to use Clippy on different popular CI providers. --- ## File: book/src/development/infrastructure/README.md # Infrastructure In order to deploy Clippy over `rustup`, some infrastructure is necessary. This chapter describes the different parts of the Clippy infrastructure that need to be maintained to make this possible. The most important part is the sync between the `rust-lang/rust` repository and the Clippy repository that takes place every two weeks. This process is described in the [Syncing changes between Clippy and `rust-lang/rust`](sync.md) section. A new Clippy release is done together with every Rust release, so every six weeks. The release process is described in the [Release a new Clippy Version](release.md) section. During a release cycle a changelog entry for the next release has to be written. The format of that and how to do that is documented in the [Changelog Update](changelog_update.md) section. > _Note:_ The Clippy CI should also be described in this chapter, but for now is > left as a TODO. --- ## File: book/src/development/proposals/README.md # Proposals This chapter is about accepted proposals for changes that should be worked on in or around Clippy in the long run. Besides adding more and more lints and improve the lints that Clippy already has, Clippy is also interested in making the experience of its users, developers and maintainers better over time. Projects that address bigger picture things like this usually take more time, and it is useful to have a proposal for those first. This is the place where such proposals are collected, so that we can refer to them when working on them. --- ## File: book/src/development/README.md # Clippy Development Hello fellow Rustacean! If you made it here, you're probably interested in making Clippy better by contributing to it. In that case, welcome to the project! > _Note:_ If you're just interested in using Clippy, there's nothing to see from > this point onward, and you should return to one of the earlier chapters. ## Getting started If this is your first time contributing to Clippy, you should first read the [Basics docs](basics.md). This will explain the basics on how to get the source code and how to compile and test the code. ## Additional Readings for Beginners If a dear reader of this documentation has never taken a class on compilers and interpreters, it might be confusing as to why AST level deals with only the language's syntax. And some readers might not even understand what lexing, parsing, and AST mean. This documentation serves by no means as a crash course on compilers or language design. And for details specifically related to Rust, the [Rustc Development Guide][rustc_dev_guide] is a far better choice to peruse. The [Syntax and AST][ast] chapter and the [High-Level IR][hir] chapter are great introduction to the concepts mentioned in this chapter. Some readers might also find the [introductory chapter][map_of_territory] of Robert Nystrom's _Crafting Interpreters_ a helpful overview of compiled and interpreted languages before jumping back to the Rustc guide. ## Writing code If you have done the basic setup, it's time to start hacking. The [Adding lints](adding_lints.md) chapter is a walk through on how to add a new lint to Clippy. This is also interesting if you just want to fix a lint, because it also covers how to test lints and gives an overview of the bigger picture. If you want to add a new lint or change existing ones apart from bugfixing, it's also a good idea to give the [stability guarantees][rfc_stability] and [lint categories][rfc_lint_cats] sections of the [Clippy 1.0 RFC][clippy_rfc] a quick read. The lint categories are also described [earlier in this book](../lints.md). > _Note:_ Some higher level things about contributing to Clippy are still > covered in the [`CONTRIBUTING.md`] document. Some of those will be moved to > the book over time, like: > - Finding something to fix > - IDE setup > - High level overview on how Clippy works > - Triage procedure [ast]: https://rustc-dev-guide.rust-lang.org/syntax-intro.html [hir]: https://rustc-dev-guide.rust-lang.org/hir.html [rustc_dev_guide]: https://rustc-dev-guide.rust-lang.org/ [map_of_territory]: https://craftinginterpreters.com/a-map-of-the-territory.html [clippy_rfc]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md [rfc_stability]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#stability-guarantees [rfc_lint_cats]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#lint-audit-and-categories [`CONTRIBUTING.md`]: https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md --- ## File: book/src/README.md # Clippy [](https://github.com/rust-lang/rust-clippy#license) A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code. [There are over 800 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html) Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html). You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category. | Category | Description | Default level | |-----------------------|-------------------------------------------------------------------------------------|---------------| | `clippy::all` | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** | | `clippy::correctness` | code that is outright wrong or useless | **deny** | | `clippy::suspicious` | code that is most likely wrong or useless | **warn** | | `clippy::style` | code that should be written in a more idiomatic way | **warn** | | `clippy::complexity` | code that does something simple but in a complex way | **warn** | | `clippy::perf` | code that can be written to run faster | **warn** | | `clippy::pedantic` | lints which are rather strict or have occasional false positives | allow | | `clippy::restriction` | lints which prevent the use of language and library features[^restrict] | allow | | `clippy::nursery` | new lints that are still under development | allow | | `clippy::cargo` | lints for the cargo manifest | allow | More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas! The `restriction` category should, *emphatically*, not be enabled as a whole. The contained lints may lint against perfectly reasonable code, may not have an alternative suggestion, and may contradict any other lints (including other categories). Lints should be considered on a case-by-case basis before enabling. [^restrict]: Some use cases for `restriction` lints include: - Strict coding styles (e.g. [`clippy::else_if_without_else`]). - Additional restrictions on CI (e.g. [`clippy::todo`]). - Preventing panicking in certain functions (e.g. [`clippy::unwrap_used`]). - Running a lint only on a subset of code (e.g. `#[forbid(clippy::float_arithmetic)]` on a module). [`clippy::else_if_without_else`]: https://rust-lang.github.io/rust-clippy/master/index.html#else_if_without_else [`clippy::todo`]: https://rust-lang.github.io/rust-clippy/master/index.html#todo [`clippy::unwrap_used`]: https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used --- ## File: book/README.md # Clippy Book This is the source for the Clippy Book. See the [book](src/development/infrastructure/book.md) for more information. --- ## File: clippy_lints/README.md This crate contains Clippy lints. For the main crate, check [GitHub](https://github.com/rust-lang/rust-clippy). --- ## File: clippy_utils/README.md # `clippy-utils` Helpful tools for writing lints, provided as they are used in Clippy. ## Usage This crate is only guaranteed to build with this `nightly` toolchain: ``` nightly-2026-08-20 ``` To use `clippy-utils` in your lint, add the following to your `Cargo.toml`: ``` clippy_utils = "0.1.XY" ``` `XY` is the version of the nightly toolchain above and can be determined with `rustc +nightly-YYYY-MM-DD -V`. ## :warning: Stability :warning: No stability guarantees are made for this crate! Use at your own risk. Function signatures can change or be removed without replacement without any prior notice. ## LICENSE Copyright (c) The Rust Project Contributors Licensed under the Apache License, Version 2.0 <[https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license <[https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your option. Files in the project may not be copied, modified, or distributed except according to those terms. --- ## File: lintcheck/README.md ## `cargo lintcheck` Runs Clippy on a fixed set of crates read from `lintcheck/lintcheck_crates.toml` and saves logs of the lint warnings into the repo. We can then check the diff and spot new or disappearing warnings. From the repo root, run: ``` cargo lintcheck ``` or ``` cargo run --target-dir lintcheck/target --manifest-path lintcheck/Cargo.toml ``` By default, the logs will be saved into `lintcheck-logs/lintcheck_crates_logs.txt`. You can set a custom sources.toml by adding `--crates-toml custom.toml` or using `LINTCHECK_TOML="custom.toml"` where `custom.toml` must be a relative path from the repo root. The results will then be saved to `lintcheck-logs/custom_logs.toml`. The `custom.toml` file may be built using recently most downloaded crates by using `cargo lintcheck popular`. For example, to retrieve the 200 recently most downloaded crates: ``` cargo lintcheck popular -n 200 custom.toml ``` > Note: Lintcheck isn't sandboxed. Only use it to check crates that you trust or > sandbox it manually. ### Configuring the Crate Sources The sources to check are saved in a `toml` file. There are three types of sources. 1. Crates-io Source ```toml bitflags = {name = "bitflags", versions = ['1.2.1']} ``` Requires a "name" and one or multiple "versions" to be checked. 2. `git` Source ````toml puffin = {name = "puffin", git_url = "https://github.com/EmbarkStudios/puffin", git_hash = "02dd4a3"} ```` Requires a name, the url to the repo and unique identifier of a commit, branch or tag which is checked out before linting. There is no way to always check `HEAD` because that would lead to changing lint-results as the repo would get updated. If `git_url` or `git_hash` is missing, an error will be thrown. 3. Local Dependency ```toml clippy = {name = "clippy", path = "/home/user/clippy"} ``` For when you want to add a repository that is not published yet. #### Command Line Options (optional) ```toml clap = {name = "clap", versions = ['4.5.8'], options = ['-Fderive']} ``` It is possible to specify command line options for each crate. This makes it possible to enable or disable features. ### Fix mode You can run `cargo lintcheck --fix` which will run Clippy with `--fix` and print a warning if Clippy's suggestions fail to apply (if the resulting code does not build). This lets us spot bad suggestions or false positives automatically in some cases. > Note: Fix mode implies `--all-targets`, so it can fix as much code as it can. Please note that the target dir should be cleaned afterwards since Clippy will modify the downloaded sources which can lead to unexpected results when running lintcheck again afterwards. ### Recursive mode You can run `cargo lintcheck --recursive` to also run Clippy on the dependencies of the crates listed in the crates source `.toml`. e.g. adding `rand 0.8.5` would also lint `rand_core`, `rand_chacha`, etc. Particularly slow crates in the dependency graph can be ignored using `recursive.ignore`: ```toml [crates] cargo = {name = "cargo", versions = ['0.64.0']} [recursive] ignore = [ "unicode-normalization", ] ```