From b0cb5fc7efa76eeb233d8feb03f6b08015e2bf0d Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Mon, 12 Dec 2022 11:49:21 -0500 Subject: [PATCH] Document current behavior around `pyproject.toml` discovery (#1213) --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index b75bb4d577..b1e96b8832 100644 --- a/README.md +++ b/README.md @@ -331,6 +331,31 @@ Options: Print version information ``` +### `pyproject.toml` discovery + +Similar to [ESLint](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#cascading-and-hierarchy), +Ruff supports hierarchical configuration, such that the "closest" `pyproject.toml` file in the +directory hierarchy is used for every individual file, with all paths in the `pyproject.toml` file +(e.g., `exclude` globs, `src` paths) being resolved relative to the directory containing the +`pyproject.toml` file. + +There are a few exceptions to these rules: + +1. If a configuration file is passed directly via `--config`, those settings are used for across + files. Any relative paths in that configuration file (like `exclude` globs or `src` paths) are + resolved relative to the _current working directory_. +2. If no `pyproject.toml` file is found in the filesystem hierarchy, Ruff will fall back to using + a default configuration. If a user-specific configuration file exists at `${config_dir}/ruff/pyproject.toml`, + that file will be used instead of the default configuration, with `${config_dir}` being determined + via the [`dirs](https://docs.rs/dirs/4.0.0/dirs/fn.config_dir.html) crate, and all relative paths + being again resolved relative to the _current working directory_. +3. Any `pyproject.toml`-supported settings that are provided on the command-line (e.g., via + `--select`) will override the settings in _every_ resolved configuration file. + +Unlike [ESLint](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#cascading-and-hierarchy), +Ruff does not merge settings across configuration files; instead, the "closest" configuration file +is used, and any parent configuration files are ignored. + ### Ignoring errors To omit a lint check entirely, add it to the "ignore" list via [`ignore`](#ignore) or