skip to content

In a Cargo workspace, why does `cargo clippy` reject `[workspace.lints.clippy]` setting `pedantic = "warn"` beside `cast_possible_truncation = "allow"`, and how do members inherit it?

level: middleimportance: should knowfreq 40%

answer

  1. same priority, order ignored
  2. lint_groups_priority is deny
  3. the group at priority -1
  4. lints.workspace = true per member
  5. no overrides beside it

basics

~20 s

Cargo ignores the order of keys in a lints table, so a group and a lint at the same priority conflict and Clippy's deny-by-default lint_groups_priority fails the run. Give the group priority = -1, and put lints.workspace = true in every member.

solid answer

~50 s

`[workspace.lints]` (Cargo 1.74) holds lint levels for the `rust`, `clippy` and `rustdoc` tools once, in the root manifest. Cargo turns the table into `--warn`/`--allow` flags for each member, but it ignores the order the keys are written in and sorts them by `priority`, a signed integer that defaults to 0. A group such as `pedantic` and one of its own lints at the same priority leave the winner unclear, so Clippy's deny-by-default `clippy::lint_groups_priority` stops the run and suggests `pedantic = { level = "warn", priority = -1 }`; lower priorities are passed first and overridden by higher ones. Inheritance is opt-in: each member needs a `[lints]` table with `workspace = true` (`cargo new` adds it inside such a workspace), and it cannot list its own lints beside that key. A virtual manifest cannot carry a plain `[lints]` table at all.

code

toml · 10 lines
toml
[workspace]
members = ["crates/*"]
resolver = "3"

[workspace.lints.rust]
unsafe_code = "forbid"

[workspace.lints.clippy]
pedantic = { level = "warn", priority = -1 }
cast_possible_truncation = "allow"

go deeper

for a junior

Recall that lint levels can live in Cargo.toml under [lints.rust] and [lints.clippy], and that a workspace shares them through [workspace.lints].

for a middle

Explain priority: Cargo ignores key order, so groups go at -1 and named lints at 0, and lint_groups_priority rejects a tie. Explain that each member opts in with lints.workspace = true.

for a senior

Show how you handle the exception crate (its own full table or an attribute) and how you verify with cargo clippy -v which flags each crate really receives.

for a principal

Argue for one workspace-wide lint policy in the root manifest, reviewed like code, against per-crate drift, and decide how rare exceptions are approved.

## The `[lints]` table and its workspace form Since **Cargo 1.74**, a manifest can set lint levels in a `[lints]` table instead of crate-level attributes such as `#![warn(clippy::pedantic)]`. The table has one sub-table per tool, named after the part of the lint name before `::`: - `[lints.rust]` for rustc lints such as `unsafe_code` or `missing_docs`; - `[lints.clippy]` for Clippy lints such as `enum_glob_use`; - `[lints.rustdoc]` for rustdoc lints such as `broken_intra_doc_links`. Each entry is either a level (`"forbid"`, `"deny"`, `"warn"`, `"allow"`) or an inline table with `level` and `priority`; `unsafe_code = "forbid"` is short for `{ level = "forbid", priority = 0 }`. Cargo applies these levels to the current package only, never to its dependencies. In a workspace the root manifest can hold the same table as `[workspace.lints]`, so every crate shares one policy. That is the reserved scenario here: a repository adopting Clippy's pedantic group for all of its crates. ## Why the example fails 1. Cargo converts the table into command-line flags such as `--warn=clippy::pedantic` and `--allow=clippy::cast_possible_truncation`. 2. The order of keys in the TOML is **ignored**. Cargo orders the flags by `priority`, and both entries here have the implicit priority 0. 3. For rustc and Clippy, the last flag for a lint wins, so equal priorities leave it unclear whether the single `allow` survives the group's `warn`. 4. Clippy's `lint_groups_priority`, which is deny-by-default, catches exactly that case: `lint group `pedantic` has the same priority (0) as a lint`. Every member that inherits the table fails to compile. 5. The fix is the one Clippy prints: `pedantic = { level = "warn", priority = -1 }`. ## How priority works - `priority` is a signed integer, 0 by default. - Lower numbers are passed to the tool first and are overridden by higher numbers. - The common pattern is every **group** at `-1` and every individual lint at the default `0`, so exceptions always beat the group they belong to. - `cargo clippy -v` shows the result on the `clippy-driver` command line: `--forbid=unsafe_code '--warn=clippy::pedantic' '--allow=clippy::cast_possible_truncation'`. ## Inheritance is opt-in A member does not pick up `[workspace.lints]` by itself. It needs: ```toml [lints] workspace = true ``` - `cargo new` inside a workspace whose root has `[workspace.lints]` writes that table into the new member for you (cargo 1.99.1 does). - A member **without** it gets no workspace lints at all. In the test workspace, a member with no `[lints]` table compiled an `unsafe` block despite `unsafe_code = "forbid"` in the root; adding the two lines turned it into an error. - A member cannot inherit and override at once. Adding `[lints.clippy]` next to `workspace = true` fails with ``cannot override `workspace.lints` in `lints`, either remove the overrides or `lints.workspace = true` and manually specify the lints``. - A **virtual manifest** (a root with `[workspace]` and no `[package]`) rejects a plain `[lints]` table: `this virtual manifest specifies a `lints` section, which is not allowed`, with a hint pointing at `[workspace.lints]`. Cargo 1.76 made this an error; before that the table was silently ignored. | manifest | `[lints]` | `[workspace.lints]` | |---|---|---| | package outside a workspace | yes | no effect | | workspace member | yes, or `workspace = true` | not here | | root package of a workspace | yes, for the root package | yes | | virtual manifest | rejected | yes | ## Checking what each crate really receives - `cargo clippy -v` prints the full `clippy-driver` command for every crate, so you can read the `--warn`, `--allow` and `--forbid` flags the table produced and the order they come in. - Plain `cargo build` passes the same flags to rustc, which ignores the `clippy::` entries; they only take effect when Clippy runs. The `rust` entries, such as `unsafe_code`, apply in every build. - `[workspace.lints.rustdoc]` entries are passed to rustdoc, so lints such as `broken_intra_doc_links` take effect in `cargo doc`, not in `cargo build` or `cargo clippy`. - A member that opted in but still behaves differently usually has crate-level attributes such as `#![allow(...)]` in its root file, which override the flags for that crate. ## Practical layout 1. Put every lint level in the root `[workspace.lints]`, groups at `priority = -1`. 2. Give each member `[lints]` with `workspace = true`. 3. When one crate truly needs a different rule (generated code, a test-support crate), allow the lint with an attribute in that crate, or give it its own full `[lints]` table instead of inheriting. 4. Keep the `rust`, `clippy` and `rustdoc` sections together so reviewers see the whole policy in one place.

  • One member of the workspace is generated code that must not get the pedantic lints; how do you handle it?
    It cannot inherit and override: `[lints.clippy]` beside `workspace = true` is a manifest error. Either drop `workspace = true` in that member and give it its own complete `[lints]` table, or keep inheriting and put `#![allow(clippy::pedantic)]` at the generated crate's root.
  • Do the levels in `[workspace.lints]` also apply to the workspace's dependencies from crates.io?
    No. Cargo applies a `[lints]` table only to the package that declares or inherits it. Registry dependencies are built with their lints capped by Cargo, so a pedantic policy in your workspace never produces warnings from someone else's crate.

  • Cargo applies lint table entries in the order they are written
  • Every workspace member inherits [workspace.lints] automatically
  • A member can inherit the workspace lints and add its own entries beside them
  • A virtual manifest can hold the shared lints in a plain [lints] table
  • Workspace lint levels also apply to dependencies from crates.io

Assumes Cargo 1.99; [lints] and [workspace.lints] are stable since Cargo 1.74, and a virtual manifest rejects a plain [lints] table since Cargo 1.76.