From 8c4842de8cc1a8329f9b42ada13ab1a074cfa9dd Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 29 Sep 2024 18:42:38 +0200
Subject: [PATCH] doc/nix fmt: Do not document behavior we do not control

This leads to confusion about what the command does.
E.g. https://github.com/NixOS/nix/issues/9359

- Move the description up

- Remove details about the individual formatters
---
 src/nix/fmt.md          | 24 +++++++++---------------
 tests/functional/fmt.sh |  2 +-
 2 files changed, 10 insertions(+), 16 deletions(-)

diff --git a/src/nix/fmt.md b/src/nix/fmt.md
index 1c78bb36f..a2afde61c 100644
--- a/src/nix/fmt.md
+++ b/src/nix/fmt.md
@@ -1,5 +1,14 @@
 R""(
 
+# Description
+
+`nix fmt` calls the formatter specified in the flake.
+
+Flags can be forwarded to the formatter by using `--` followed by the flags.
+
+Any arguments will be forwarded to the formatter. Typically these are the files to format.
+
+
 # Examples
 
 With [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt):
@@ -13,10 +22,6 @@ With [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt):
 }
 ```
 
-- Format the current flake: `$ nix fmt`
-
-- Format a specific folder or file: `$ nix fmt ./folder ./file.nix`
-
 With [nixfmt](https://github.com/serokell/nixfmt):
 
 ```nix
@@ -28,8 +33,6 @@ With [nixfmt](https://github.com/serokell/nixfmt):
 }
 ```
 
-- Format specific files: `$ nix fmt ./file1.nix ./file2.nix`
-
 With [Alejandra](https://github.com/kamadorueda/alejandra):
 
 ```nix
@@ -41,13 +44,4 @@ With [Alejandra](https://github.com/kamadorueda/alejandra):
 }
 ```
 
-- Format the current flake: `$ nix fmt`
-
-- Format a specific folder or file: `$ nix fmt ./folder ./file.nix`
-
-# Description
-
-`nix fmt` will rewrite all Nix files (\*.nix) to a canonical format
-using the formatter specified in your flake.
-
 )""
diff --git a/tests/functional/fmt.sh b/tests/functional/fmt.sh
index 9a79260e6..4e0fd57a5 100755
--- a/tests/functional/fmt.sh
+++ b/tests/functional/fmt.sh
@@ -11,7 +11,7 @@ cp ./simple.nix ./simple.builder.sh ./fmt.simple.sh ./config.nix "$TEST_HOME"
 
 cd "$TEST_HOME"
 
-nix fmt --help | grep "Format"
+nix fmt --help | grep "forward"
 
 cat << EOF > flake.nix
 {