diff --git a/docs/formatter.md b/docs/formatter.md index 887c5d7699d32..c6b84524eef2a 100644 --- a/docs/formatter.md +++ b/docs/formatter.md @@ -180,9 +180,10 @@ comments, which are treated equivalently to `# fmt: off` and `# fmt: on`, respec Ruff's formatter is designed to be used alongside the linter. However, the linter includes some rules that, when enabled, can cause conflicts with the formatter, leading to unexpected -behavior. +behavior. When configured appropriately, the goal of Ruff's formatter-linter compatibility is +such that running the formatter should never introduce new lint errors. -When using Ruff as a formatter, we recommend disabling the following rules: +As such, when using Ruff as a formatter, we recommend avoiding the following lint rules: - [`tab-indentation`](rules/tab-indentation.md) (`W191`) - [`indentation-with-invalid-multiple`](rules/indentation-with-invalid-multiple.md) (`E111`) @@ -199,7 +200,11 @@ When using Ruff as a formatter, we recommend disabling the following rules: - [`single-line-implicit-string-concatenation`](rules/single-line-implicit-string-concatenation.md) (`ISC001`) - [`multi-line-implicit-string-concatenation`](rules/multi-line-implicit-string-concatenation.md) (`ISC002`) -Similarly, we recommend disabling the following isort settings, which are incompatible with the +None of the above are included in Ruff's default configuration. However, if you've enabled +any of these rules or their parent categories (like `Q`), we recommend disabling them via the +linter's [`ignore`](settings.md#ignore) setting. + +Similarly, we recommend avoiding the following isort settings, which are incompatible with the formatter's treatment of import statements when set to non-default values: - [`force-single-line`](settings.md#isort-force-single-line) @@ -208,6 +213,12 @@ formatter's treatment of import statements when set to non-default values: - [`lines-between-types`](settings.md#isort-lines-between-types) - [`split-on-trailing-comma`](settings.md#isort-split-on-trailing-comma) +If you've configured any of these settings to take on non-default values, we recommend removing +them from your Ruff configuration. + +When an incompatible lint rule or setting is enabled, `ruff format` will emit a warning. If your +`ruff format` is free of warnings, you're good to go! + ## Exit codes `ruff format` exits with the following status codes: diff --git a/docs/integrations.md b/docs/integrations.md index e60b177321ab6..94f095dbd5956 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -55,6 +55,10 @@ or isort, _unless_ you enable autofix, in which case, Ruff's pre-commit hook sho Black, isort, and other formatting tools, as Ruff's autofix behavior can output code changes that require reformatting. +As long as your Ruff configuration avoids any [linter-formatter incompatibilities](formatter.md#conflicting-lint-rules), +`ruff format` should never introduce new lint errors, so it's safe to run Ruff's format hook _after_ +`ruff check --fix`. + ## Language Server Protocol (Official) Ruff supports the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)