From ce549e75bc93e200f82b3bde48167efb60f8f750 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Tue, 7 Nov 2023 10:40:13 -0800
Subject: [PATCH] Update pre-commit documentation (#8545)

I got some feedback on Mastodon that it wasn't clear how to use the
linter and formatter together in pre-commit (mostly in the pre-commit
repo's documentation, which is even less clear, but the two should be
consistent).
---
 README.md            |  5 +++--
 docs/integrations.md | 41 ++++++++++++++++++++++-------------------
 docs/tutorial.md     |  8 ++------
 3 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 44129d9f523d7..5c1dd57c4a688 100644
--- a/README.md
+++ b/README.md
@@ -152,9 +152,10 @@ Ruff can also be used as a [pre-commit](https://pre-commit.com/) hook via [`ruff
   # Ruff version.
   rev: v0.1.4
   hooks:
-    # Run the Ruff linter.
+    # Run the linter.
     - id: ruff
-    # Run the Ruff formatter.
+      args: [ --fix ]
+    # Run the formatter.
     - id: ruff-format
 ```
 
diff --git a/docs/integrations.md b/docs/integrations.md
index 9f14681acc3cd..df8aa06505bd2 100644
--- a/docs/integrations.md
+++ b/docs/integrations.md
@@ -12,52 +12,55 @@ which supports fix actions, import sorting, and more.
 Ruff can be used as a [pre-commit](https://pre-commit.com) hook via [`ruff-pre-commit`](https://github.com/astral-sh/ruff-pre-commit):
 
 ```yaml
-# Run the Ruff linter.
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.0.291
+  rev: v0.1.4
   hooks:
+    # Run the linter.
     - id: ruff
-# Run the Ruff formatter.
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  # Ruff version.
-  rev: v0.0.291
-  hooks:
+    # Run the formatter.
     - id: ruff-format
 ```
 
-To enable fixes, add the `--fix` argument to the linter:
+To enable lint fixes, add the `--fix` argument to the lint hook:
 
 ```yaml
-# Run the Ruff linter.
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.0.291
+  rev: v0.1.4
   hooks:
+    # Run the linter.
     - id: ruff
-      args: [ --fix, --exit-non-zero-on-fix ]
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
 ```
 
 To run the hooks over Jupyter Notebooks too, add `jupyter` to the list of allowed filetypes:
 
 ```yaml
-# Run the Ruff linter.
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.0.291
+  rev: v0.1.4
   hooks:
+    # Run the linter.
     - id: ruff
       types_or: [ python, pyi, jupyter ]
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+      types_or: [ python, pyi, jupyter ]
 ```
 
-Ruff's lint hook should be placed after other formatting tools, such as Ruff's format hook, Black,
-or isort, _unless_ you enable autofix, in which case, Ruff's pre-commit hook should run _before_
-Black, isort, and other formatting tools, as Ruff's autofix behavior can output code changes that
-require reformatting.
+When running with `--fix`, Ruff's lint hook should be placed _before_ Ruff's formatter hook, and
+_before_ Black, isort, and other formatting tools, as Ruff's fix behavior can output code changes
+that require reformatting.
+
+When running without `--fix`, Ruff's formatter hook can be placed before or after Ruff's lint hook.
 
-As long as your Ruff configuration avoids any [linter-formatter incompatibilities](formatter.md#conflicting-lint-rules),
+(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`.
+`ruff check --fix`.)
 
 ## Language Server Protocol (Official)
 
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 90913bd727711..7eae80f290266 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -341,17 +341,13 @@ This tutorial has focused on Ruff's command-line interface, but Ruff can also be
 [pre-commit](https://pre-commit.com) hook via [`ruff-pre-commit`](https://github.com/astral-sh/ruff-pre-commit):
 
 ```yaml
-# Run the Ruff linter.
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
   rev: v0.1.4
   hooks:
+    # Run the linter.
     - id: ruff
-# Run the Ruff formatter.
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  # Ruff version.
-  rev: v0.1.4
-  hooks:
+    # Run the formatter.
     - id: ruff-format
 ```