diff --git a/docs/faq.md b/docs/faq.md index 0eb4a5aa1d20b7..3128cbdc55c93c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -3,16 +3,18 @@ ## Is the Ruff linter compatible with Black? Yes. The Ruff linter is compatible with [Black](https://github.com/psf/black) out-of-the-box, as -long as the `line-length` setting is consistent between the two. +long as the [`line-length`](settings.md#line-length) setting is consistent between the two. Ruff is designed to be used alongside a formatter (like Ruff's own formatter, or Black) and, as such, will defer implementing stylistic rules that are obviated by automated formatting. -Note that Ruff and Black treat line-length enforcement a little differently. Black makes a -best-effort attempt to adhere to the `line-length`, but avoids automatic line-wrapping in some cases -(e.g., within comments). Ruff, on the other hand, will flag rule `E501` for any line that exceeds -the `line-length` setting. As such, if `E501` is enabled, Ruff can still trigger line-length -violations even when Black is enabled. +Note that Ruff's linter and Black treat line-length enforcement a little differently. Black, like +Ruff's formatter, makes a best-effort attempt to adhere to the +[`line-length`](settings.md#line-length), but avoids automatic line-wrapping in some cases (e.g., +within comments). Ruff, on the other hand, will flag [`line-too-long`](rules/line-too-long.md) +(`E501`) for any line that exceeds the [`line-length`](settings.md#line-length) setting. As such, if +[`line-too-long`](rules/line-too-long.md) (`E501`) is enabled, Ruff can still trigger line-length +violations even when Black or `ruff format` is enabled. ## How does Ruff's formatter compare to Black? diff --git a/docs/formatter.md b/docs/formatter.md index c6b84524eef2a2..ca8e44e0e5a47a 100644 --- a/docs/formatter.md +++ b/docs/formatter.md @@ -183,7 +183,7 @@ some rules that, when enabled, can cause conflicts with the formatter, leading t behavior. When configured appropriately, the goal of Ruff's formatter-linter compatibility is such that running the formatter should never introduce new lint errors. -As such, when using Ruff as a formatter, we recommend avoiding the following lint rules: +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`) @@ -200,6 +200,11 @@ As such, when using Ruff as a formatter, we recommend avoiding the following lin - [`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`) +While the [`line-too-long`](rules/line-too-long.md) (`E501`) rule _can_ be used alongside the +formatter, the formatter only makes a best-effort attempt to wrap lines at the configured +[`line-length`](settings.md#line-length). As such, formatted code _may_ exceed the line length, +leading to [`line-too-long`](rules/line-too-long.md) (`E501`) errors. + 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. @@ -216,6 +221,7 @@ formatter's treatment of import statements when set to non-default values: 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!