README.md

   1 # Clippy
   2
   3 [![Clippy Test](https://github.com/rust-lang/rust-clippy/workflows/Clippy%20Test/badge.svg?branch=auto&event=push)](https://github.com/rust-lang/rust-clippy/actions?query=workflow%3A%22Clippy+Test%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 400 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, style, complexity, perf) | **warn/deny**
  16 `clippy::correctness` | code that is outright wrong or very useless | **deny**
  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 might have false positives | allow
  21 `clippy::nursery` | new lints that are still under development | allow
  22 `clippy::cargo` | lints for the cargo manifest | allow
  23
  24 More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas!
  25
  26 The [lint list](https://rust-lang.github.io/rust-clippy/master/index.html) also contains "restriction lints", which are
  27 for things which are usually not considered "bad", but may be useful to turn on in specific cases. These should be used
  28 very selectively, if at all.
  29
  30 Table of contents:
  31
  32 *   [Usage instructions](#usage)
  33 *   [Configuration](#configuration)
  34 *   [Contributing](#contributing)
  35 *   [License](#license)
  36
  37 ## Usage
  38
  39 Below are instructions on how to use Clippy as a subcommand, compiled from source
  40 or in Travis CI.
  41
  42 ### As a cargo subcommand (`cargo clippy`)
  43
  44 One way to use Clippy is by installing Clippy through rustup as a cargo
  45 subcommand.
  46
  47 #### Step 1: Install rustup
  48
  49 You can install [rustup](https://rustup.rs/) on supported platforms. This will help
  50 us install Clippy and its dependencies.
  51
  52 If you already have rustup installed, update to ensure you have the latest
  53 rustup and compiler:
  54
  55 ```terminal
  56 rustup update
  57 ```
  58
  59 #### Step 2: Install Clippy
  60
  61 Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command:
  62
  63 ```terminal
  64 rustup component add clippy
  65 ```
  66 If it says that it can't find the `clippy` component, please run `rustup self update`.
  67
  68 #### Step 3: Run Clippy
  69
  70 Now you can run Clippy by invoking the following command:
  71
  72 ```terminal
  73 cargo clippy
  74 ```
  75
  76 #### Automatically applying Clippy suggestions
  77
  78 Clippy can automatically apply some lint suggestions.
  79 Note that this is still experimental and only supported on the nightly channel:
  80
  81 ```terminal
  82 cargo clippy --fix -Z unstable-options
  83 ```
  84
  85 ### Running Clippy from the command line without installing it
  86
  87 To have cargo compile your crate with Clippy without Clippy installation
  88 in your code, you can use:
  89
  90 ```terminal
  91 cargo run --bin cargo-clippy --manifest-path=path_to_clippys_Cargo.toml
  92 ```
  93
  94 *Note:* Be sure that Clippy was compiled with the same version of rustc that cargo invokes here!
  95
  96 ### Travis CI
  97
  98 You can add Clippy to Travis CI in the same way you use it locally:
  99
 100 ```yml
 101 language: rust
 102 rust:
 103   - stable
 104   - beta
 105 before_script:
 106   - rustup component add clippy
 107 script:
 108   - cargo clippy
 109   # if you want the build job to fail when encountering warnings, use
 110   - cargo clippy -- -D warnings
 111   # in order to also check tests and non-default crate features, use
 112   - cargo clippy --all-targets --all-features -- -D warnings
 113   - cargo test
 114   # etc.
 115 ```
 116
 117 If you are on nightly, It might happen that Clippy is not available for a certain nightly release.
 118 In this case you can try to conditionally install Clippy from the Git repo.
 119
 120 ```yaml
 121 language: rust
 122 rust:
 123   - nightly
 124 before_script:
 125    - rustup component add clippy --toolchain=nightly || cargo install --git https://github.com/rust-lang/rust-clippy/ --force clippy
 126    # etc.
 127 ```
 128
 129 Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code.
 130 That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause
 131 an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command
 132 line. (You can swap `clippy::all` with the specific lint category you are targeting.)
 133
 134 ## Configuration
 135
 136 Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable =
 137 value` mapping eg.
 138
 139 ```toml
 140 blacklisted-names = ["toto", "tata", "titi"]
 141 cognitive-complexity-threshold = 30
 142 ```
 143
 144 See the [list of lints](https://rust-lang.github.io/rust-clippy/master/index.html) for more information about which
 145 lints can be configured and the meaning of the variables.
 146
 147 To deactivate the “for further information visit *lint-link*” message you can
 148 define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
 149
 150 ### Allowing/denying lints
 151
 152 You can add options to your code to `allow`/`warn`/`deny` Clippy lints:
 153
 154 *   the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`)
 155
 156 *   all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`,
 157     `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive
 158     lints prone to false positives.
 159
 160 *   only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.)
 161
 162 *   `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc.
 163
 164 Note: `allow` means to suppress the lint for your code. With `warn` the lint
 165 will only emit a warning, while with `deny` the lint will emit an error, when
 166 triggering for your code. An error causes clippy to exit with an error code, so
 167 is useful in scripts like CI/CD.
 168
 169 If you do not want to include your lint levels in your code, you can globally
 170 enable/disable lints by passing extra flags to Clippy during the run:
 171
 172 To allow `lint_name`, run
 173
 174 ```terminal
 175 cargo clippy -- -A clippy::lint_name
 176 ```
 177
 178 And to warn on `lint_name`, run
 179
 180 ```terminal
 181 cargo clippy -- -W clippy::lint_name
 182 ```
 183
 184 This also works with lint groups. For example you
 185 can run Clippy with warnings for all lints enabled:
 186 ```terminal
 187 cargo clippy -- -W clippy::pedantic
 188 ```
 189
 190 If you care only about a single lint, you can allow all others and then explicitly warn on
 191 the lint(s) you are interested in:
 192 ```terminal
 193 cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...
 194 ```
 195 Note that if you've run clippy before, this may only take effect after you've modified a file or ran `cargo clean`.
 196
 197 ## Contributing
 198
 199 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).
 200
 201 ## License
 202
 203 Copyright 2014-2020 The Rust Project Developers
 204
 205 Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
 206 [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license
 207 <LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your
 208 option. Files in the project may not be
 209 copied, modified, or distributed except according to those terms.