stable clippy.toml: Create RFC #15630

blyxyas · 2025-09-07T16:27:54Z

This PR creates an RFC for how clippy.toml should be handled. I made some improvements to some parts of the system. These are better to get fixed today than to wait until someone has a problem with them and then have to make a breaking change.

Based on Philipp's RFC. This would be the first stage of 3 to completely stabilize clippy.toml

Being that Philipp is on vacation, I'm not sure who could review this, it's a team-wide thing anyways.

changelog:none

Rendered

rustbot · 2025-09-07T16:27:59Z

flip1995 is not on the review rotation at the moment.
They may take a while to respond.

rustbot · 2025-09-07T16:27:59Z

r? @flip1995

rustbot has assigned @flip1995.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

This PR creates a public RFC for how clippy.toml should be handled. I made some improvements to some parts of the system. These are better to get fixed today than to wait until someone has a problem with them and then have to make a breaking change. Based on Philipp's RFC. This would be the first stage of 3 to completely stabilize clippy.toml

blyxyas · 2025-09-07T18:32:21Z

@ojeda Is this more or less what you need?

The RFC stabilizes the existence of the Clippy configuration file, the algorithm to find it, the existence of CLIPPY_CONF_DIR and its behaviour, the existence of a new CLIPPY_CONF_PATH (which will be the preferred way to pass configuration into Clippy, but CLIPPY_CONF_DIR will not be removed anytime soon), and the format of the configuration itself as a subset of TOML.

The only thing needed apart from this would be stabilizing the configuration options themselves. Which, because of your usecase, the first ones will be msrv, check-private-items, disallowed-macros and doc-valid-idents.

ojeda · 2025-09-07T21:50:36Z

Thanks for working on this!

The only thing needed apart from this would be stabilizing the configuration options themselves. Which, because of your usecase, the first ones will be msrv, check-private-items, disallowed-macros and doc-valid-idents.

That would be great.

It may be good to mention in the RFC what would be the "stable mode" -- IIUC it would fail on unknown keys (like Clippy today), but it would not allow to use unstable keys (unlike Clippy today). Is that correct?

If so, then does that mean that unless all those options (msrv etc.) are stabilized before the default behavior changes, we would need to have 2 files to be able to make it work with old and new Clippy?

There isn't a good way to specify configuration values from the terminal, for the time being.

If Clippy plans to support that eventually, then an alternative would be to not stabilize the file and go for flags directly -- for us it would make it easier to pass flags to Clippy depending e.g. on the version.

But, of course, that would open again the questions about how to pass all what the TOML allows for non-trivial keys. IIRC we discussed it in Zulip a while ago.

book/src/development/proposals/clippy-toml-stabilization.md

blyxyas · 2025-09-21T15:03:01Z

If Clippy plans to support that eventually, then an alternative would be to not stabilize the file and go for flags directly -- for us it would make it easier to pass flags to Clippy depending e.g. on the version.

The problem with this is passing complex values to the flag. That's why this RFC changes CLIPPY_CONF_DIR into CLIPPY_CONF_PATH, allowing for having several configuration files depending on version or whatever metric you want to use.

I can see that this approach has some ergonomic issues, but it's not that different than having to maintain different CLI flags depending on version.

book/src/development/proposals/clippy-toml-stabilization.md

blyxyas · 2025-11-24T23:32:46Z

Is there anything left? I'll nominate this and see if in today's meeting we can sort this out.

@rustbot label +I-nominate

rustbot · 2025-11-24T23:32:57Z

Error: Unknown labels: I-nominate

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

flip1995

A bit late, but I finally got to reading this. Sorry for the long delay.

View changes since this review

flip1995 · 2025-12-01T16:56:54Z

book/src/development/proposals/clippy-toml-stabilization.md

+
+Some Clippy lints can be tweaked via a configuration file commonly named `clippy.toml` or `.clippy.toml`.
+
+Clippy looks for this file in the current directory and all parents up to the root of the workspace if there is one.


I would prefer, if we do the same as cargo and rustfmt and not only search up to the workspace, but just any parent dir.

flip1995 · 2025-12-01T16:57:57Z

book/src/development/proposals/clippy-toml-stabilization.md

+For crates in a workspace, the Clippy configuration files would be merged with the ones in their parent directories.
+A Clippy configuration file will always overwrite one in a parent directory


Isn't this contradicting? Or are you proposing different behavior between a workspace and non-workspace setups?

Yes, I'm proposing that for crates in a workspace, we merge clippy.tomls and for those without a workspace, we overwrite them. That could be a little confusing if not communicated well to the user, though.

I think this is too confusing. I would default to always overwrite or always merge and then provide a setting. I would follow the behavior of .cargo/config.toml and/or rustfmt.toml here.

clang-format has something similar with the InheritParentConfig option. By default it will overwrite, but with that set, it will be merged.

In that case, I'll remove the logic part in the RFC and just say that we follow the .cargo/config.toml specification

flip1995 · 2025-12-01T17:02:32Z

book/src/development/proposals/clippy-toml-stabilization.md

+The list of available configurations along their default values is
+[here](https://doc.rust-lang.org/nightly/clippy/lint_configuration.html).
+You can enable unstable features via the `unstable-conf` configuration option. If this configuration is set to `true`,
+Clippy will warn about unknown or renamed keys, and will allow the modification of unstable configuration options. One


and will allow the modification of unstable configuration options

by this, do you mean that Clippy (the project) is allowed to change unstable config options? and will allow sounds like the Clippy will allow the user to modify these.

flip1995 · 2025-12-01T17:04:12Z

book/src/development/proposals/clippy-toml-stabilization.md

+a directory (in which it performs the known algorithm, looking for all parents up to `/`, merging them...). If
+`CLIPPY_CONF_PATH` is a file, just read it as we'd do with `clippy.toml`.


I think if a user specifies CLIPPY_CONF_PATH, that we should only search that directory and not also upwards. Not a strong opinion though.

flip1995 · 2025-12-01T17:05:30Z

book/src/development/proposals/clippy-toml-stabilization.md

+
+## Stabilization process for keys
+
+Each key needs to be independently stabilized, or it won't be active on configurations without `unstable-conf` enabled.


Suggested change

Each key needs to be independently stabilized, or it won't be active on configurations without `unstable-conf` enabled.

Each key needs to be independently stabilized, or it won't be active on configurations with `unstable-conf = false`.

flip1995 · 2025-12-01T17:08:43Z

book/src/development/proposals/clippy-toml-stabilization.md

+# Drawbacks
+
+- There isn't a good way to specify configuration values from the terminal, for the time being.
+- In stable mode, typos and/or deprecated and/or renamed configuration keys being renamed cannot be warned against.


Why is that not possible? 🤔

flip1995 · 2025-12-01T17:09:40Z

book/src/development/proposals/clippy-toml-stabilization.md

+in plain text. Here's an example.
+
+```toml
+unstable-conf = false


Maybe I missed it, but what's the default value for this? I agree with Manish, that it should be opt-out, so the default should be true.

flip1995 · 2025-12-01T17:22:15Z

book/src/development/proposals/clippy-toml-stabilization.md

Regarding CLI flags, we could copy cargo --config and accept TOML key/value pairs under a --clippy-config or similar

Outside of that, what exactly are we promising here by making a configuration value stable? If it can never be removed that is quite a commitment, it's possible the lint it applies to is removed from clippy in a future change for example e.g. by an uplift into rustc

Copying @Alexendoo comment into a thread, so we don't cross-reply in the main convo.

it's possible the lint it applies to is removed from clippy in a future change for example e.g. by an uplift into rustc

Good point! I think removal isn't really a problem. Uplifting might break something for our users. But I'd say that's something the person uplifting the lint has to take into account.

rustbot assigned flip1995 Sep 7, 2025

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties label Sep 7, 2025

blyxyas force-pushed the rfc-stable-clippytoml branch from d64c47e to e5a9868 Compare September 7, 2025 16:47

blyxyas force-pushed the rfc-stable-clippytoml branch from e5a9868 to fb11b83 Compare September 7, 2025 16:49

ojeda mentioned this pull request Sep 7, 2025

Rust unstable features needed for the kernel Rust-for-Linux/linux#2

Open

lucab reviewed Sep 8, 2025

View reviewed changes

book/src/development/proposals/clippy-toml-stabilization.md Outdated Show resolved Hide resolved

book/src/development/proposals/clippy-toml-stabilization.md Outdated Show resolved Hide resolved

blyxyas added 2 commits September 20, 2025 12:07

Fix a couple typos

5445a47

Add section about stable mode

28346a3

Manishearth reviewed Oct 3, 2025

View reviewed changes

book/src/development/proposals/clippy-toml-stabilization.md Show resolved Hide resolved

blyxyas added the I-nominated Issue: Nominated to be discussed at the next Clippy meeting label Nov 24, 2025

This comment was marked as duplicate.

Sign in to view

flip1995 reviewed Dec 1, 2025

View reviewed changes

flip1995 removed the I-nominated Issue: Nominated to be discussed at the next Clippy meeting label Dec 1, 2025


		Some Clippy lints can be tweaked via a configuration file commonly named `clippy.toml` or `.clippy.toml`.

		Clippy looks for this file in the current directory and all parents up to the root of the workspace if there is one.

		For crates in a workspace, the Clippy configuration files would be merged with the ones in their parent directories.
		A Clippy configuration file will always overwrite one in a parent directory

		a directory (in which it performs the known algorithm, looking for all parents up to `/`, merging them...). If
		`CLIPPY_CONF_PATH` is a file, just read it as we'd do with `clippy.toml`.


		## Stabilization process for keys

		Each key needs to be independently stabilized, or it won't be active on configurations without `unstable-conf` enabled.

stable clippy.toml: Create RFC #15630

Are you sure you want to change the base?

stable clippy.toml: Create RFC #15630

Uh oh!

Conversation

blyxyas commented Sep 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Sep 7, 2025

Uh oh!

rustbot commented Sep 7, 2025

Uh oh!

blyxyas commented Sep 7, 2025

Uh oh!

ojeda commented Sep 7, 2025

Uh oh!

Uh oh!

Uh oh!

blyxyas commented Sep 21, 2025

Uh oh!

Uh oh!

blyxyas commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Nov 24, 2025

Uh oh!

This comment was marked as duplicate.

flip1995 left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

blyxyas commented Sep 7, 2025 •

edited

Loading

blyxyas commented Nov 24, 2025 •

edited

Loading

flip1995 left a comment •

edited by rustbot

Loading