how to extend project settings from global user/team settings

[nurpax]

Hi,

I'd like to maintain a shared "default settings" ruff.toml among my team mates at work. We'd like to keep this file in a common git repository. In addition to setting the default warning enable/disables, we'd like to optionally extend from this shared ruff.toml file in some of our sub directories.

I could implement this with hardcoded paths:

~/.config/ruff/ruff.toml

work/project_a/   # 'ruff check' uses shared settings normally

work/project_b/   # 'ruff check' inherits shared settings with extend but overrides some settings
work/project_b/pyproject.toml # contains 'extend=~/.config/ruff/ruff.toml' 

However, I'm drawing blanks on how to implement this more flexibly.

For example, we'd keep ~/.config/ruff/ruff.toml in revision control and not under ~/.config/ruff. So ruff by default won't find it there. On Linux we could potentially symlink it, but Windows users are pretty seriously averse to using symlinks. Even still, how would the pyproject.toml extend line refer to this file in a platform independent way as ~/.config/ruff path is not necessarily the same across Linux, Windows and macOS.

We could move the shared config somewhere else and refer to it indirectly using an environment variable. With this, the pyproject.toml extend line could use something like extend=$RUFF_CONFIG_FILE. The problem is then that subdirectories without pyproject.toml won't pick up the shared config file unless invoke ruff with ruff check --config=$RUFF_CONFIG_FILE. I would very much like ruff check to suffice in every part of our codebase without users needing to memorize additional options or having to configure other tools like VSCode to also specify this.

One satisfying solution would be if ruff allowed giving the --config argument via an environment variable. For example, if $RUFF_CONFIG_FILE is set, ruff would load its default config from that path. I tried to dig through docs and source, but it looks like there's no support for passing this through the environment?

Any alternative ways to express this "shared settings, but overridden in some subdirs" desire?

[MichaReiser]

Hi @nurpax

Yeah, I don't think your use case is supported today. There's a related issue #12352 but what you want goes beyond that because it doesn't cover the project_a case.

Without the csae of project_a, one thing we could do is to allow environment variables in the extend path. We do something similar in the VS code extension. But that would require that each project has a ruff.toml or pyproject.toml with at least an extend.

One satisfying solution would be if ruff allowed giving the --config argument via an environment variable. For example, if $RUFF_CONFIG_FILE is set, ruff would load its default config from that path. I tried to dig through docs and source, but it looks like there's no support for passing this through the environment?

I can see how this would solve the problem for project_a but it would break your setup for project_b because CLI provided arguments take precedence over the project's configuration. That means it becomes impossible to override any settings.

[nurpax]

Hmm, maybe I don't understand the defaults works.

The way I envisioned the RUFF_CONFIG_FILE env variable to work is that it'd be an optional indirection to locate user settings. Instead of implicitly like now (through various path searches to locate ~/.config/ruff/ruff.toml or similar), the env var could point directly to a shared settings file.

But based on what you're saying, it sounds like ~/.config/ruff/ruff.toml would override pyproject.toml settings?

To enumerate how I thought it might work:

1. if there's no pyproject.toml (and none found by following parent dirs), use user defaults from which ever directory it can be found, probably ~/.config/ruff/ruff.toml
2. if a directory contains pyproject.toml, use that. Use extend in this pyproject.toml if the project explicitly wants to merge user/team defaults

In both cases, the environment variable would only assist in locating the right user/team settings file. I didn't think it would count as a command line option.

[MichaReiser]

No, your understanding regarding the user configuration (in ~/.config/ruff) is correct. It has a lower precedence than the pyproject.toml. But configs specified with --config have a higher precedence than the pyproject.toml, they override the settings from pyproject.toml. That's why having a RUFF_CONFIG environment variable wouldn't work for the project_a case

[nurpax]

OK. Well, I didn't intend to use --config at all, only that the environment variable would be a feature of the user settings locator and the settings would have the same precedence as currently.

In all cases, we'd want to use ruff like ruff check, but ruff check --config <path/env var> because if we can configure it to work with just ruff check, all tools will use the right settings and users can remember how to run it correctly.

[nurpax]

I did take a look at the external file proposal for "setting presets" but yeah, that seems to be about something else. It also feels a bit complex given that it probably needs to cache git clone or http query results somehow. How would it know when to invalidate the cache?

In our case, the settings are in fact in revision control (not Git) and the file is always checked out on the file system, just that checkout path is not in any filesystem location where ruff would automatically find it.