From 41aee4572dcdd0c9d70729a8829dcc9a48724baa Mon Sep 17 00:00:00 2001
From: Greg Shuflin <greg@everydayimshuflin.com>
Date: Mon, 12 Jun 2023 10:02:13 -0700
Subject: [PATCH] Add better documentation for --dump and --fmt (#1603)

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9064fcd..aaa94fb 100644
--- a/README.md
+++ b/README.md
@@ -2275,9 +2275,46 @@ default:
   echo foo
 ```
 
-### Dumping `justfile`s as JSON
+### Formatting and dumping `justfile`s
 
-The `--dump` command can be used with `--dump-format json` to print a JSON representation of a `justfile`. The JSON format is currently unstable, so the `--unstable` flag is required.
+Each `justfile` has a canonical formatting with respect to whitespace and
+newlines.
+
+You can overwrite the current justfile with a canonically-formatted version
+using the currently-unstable `--fmt` flag:
+
+```sh
+$ cat justfile
+# A lot of blank lines
+
+
+
+
+
+some-recipe:
+  echo "foo"
+$ just --fmt --unstable
+$ cat justfile
+# A lot of blank lines
+
+some-recipe:
+    echo "foo"
+```
+
+Invoking `just --fmt --check --unstable` runs `--fmt` in check mode. Instead of
+overwriting the `justfile`, `just` will exit with an exit code of 0 if it is
+formatted correctly, and will exit with 1 and print a diff if it is not.
+
+You can use the `--dump` command to output a formatted version of the
+`justfile` to stdout:
+
+```sh
+$ just --dump > formatted-justfile
+```
+
+The `--dump` command can be used with `--dump-format json` to print a JSON
+representation of a `justfile`. The JSON format is currently unstable, so the
+`--unstable` flag is required.
 
 ### Fallback to parent `justfile`s