From 58b54b664b7c67929cd0b5e6221cecbed3eab233 Mon Sep 17 00:00:00 2001
From: NAHO <90870942+trueNAHO@users.noreply.github.com>
Date: Sat, 25 Jan 2025 20:21:13 +0100
Subject: [PATCH] doc: elaborate pre-commit hook usage in development
 environment (#793)

---
 docs/src/development_environment.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/src/development_environment.md b/docs/src/development_environment.md
index edea1c79..4f5ad123 100644
--- a/docs/src/development_environment.md
+++ b/docs/src/development_environment.md
@@ -1,5 +1,7 @@
 # Development environment
 
+## Developer shell
+
 To enter the developer shell, run:
 
 ```console
@@ -12,3 +14,24 @@ with [`direnv`](https://direnv.net), run:
 ```console
 direnv allow
 ```
+
+## pre-commit
+
+The default developer shell leverages [`pre-commit`](https://pre-commit.com)
+hooks to simplify the process of reaching minimum quality standards for casual
+contributors.
+
+By default, `pre-commit` only runs on staged files. To manually run
+[`pre-commit`](https://pre-commit.com) against all files, run:
+
+```console
+pre-commit run --all-files
+```
+
+This is useful when submitting a patchset and `pre-commit` was not used on all
+commits. For example, suppose the first commit was created without `pre-commit`
+and touches `/flake.nix`. Installing `pre-commit` and then creating a second
+commit that touches `/README.md` will not run any hooks on `/flake.nix`.
+
+Note that the `outputs.checks.${system}.git-hooks` output always runs against
+all files.