From 5915951cbf3c4ab61339c0c8a908c55392cbbc1a Mon Sep 17 00:00:00 2001
From: Pamplemousse <git@xaviermaso.com>
Date: Tue, 1 Nov 2022 09:16:45 +0100
Subject: [PATCH] Document `--json` in `diff-closures`

Signed-off-by: Pamplemousse <git@xaviermaso.com>
---
 src/nix/diff-closures.md | 48 +++++++++++++++++++++++++++++-----------
 1 file changed, 35 insertions(+), 13 deletions(-)

diff --git a/src/nix/diff-closures.md b/src/nix/diff-closures.md
index 0294c0d8d..967ca42bb 100644
--- a/src/nix/diff-closures.md
+++ b/src/nix/diff-closures.md
@@ -24,28 +24,50 @@ of packages, as well as changes in store path sizes.
 
 For each package name in the two closures (where a package name is
 defined as the name component of a store path excluding the version),
-if there is a change in the set of versions of the package, or a
-change in the size of the store paths of more than 8 KiB, it prints a
-line like this:
+it returns information about the change in the set of versions of the
+package, and the change in the size of the store paths.
 
-```console
-dolphin: 20.08.1 → 20.08.2, +13.9 KiB
-```
-
-No size change is shown if it's below the threshold. If the package
-does not exist in either the *before* or *after* closures, it is
-represented using `∅` (empty set) on the appropriate side of the
-arrow. If a package has an empty version string, the version is
-rendered as `ε` (epsilon).
+If the package does not exist in either the *before* or *after*
+closures, it is represented using `∅` (empty set) on the appropriate
+side of the arrow. If a package has an empty version string, the
+version is rendered as `ε` (epsilon).
 
 There may be multiple versions of a package in each closure. In that
 case, only the changed versions are shown. Thus,
 
 ```console
-libfoo: 1.2, 1.3 → 1.4
+1.2, 1.3 → 1.4
 ```
 
 leaves open the possibility that there are other versions (e.g. `1.1`)
 that exist in both closures.
 
+## Regular output
+
+The regular output prints lines like this:
+
+```console
+dolphin: 20.08.1 → 20.08.2, +13.9 KiB
+```
+
+No size change is shown if it's below the 8 KiB threshold.
+
+## JSON output
+
+With `--json`, the output is in a JSON representation suitable for automatic
+processing by other tools.
+
+The printed result looks like this:
+
+```json
+{
+  "dolphin": {
+    "after": "20.08.1",
+    "before": "20.08.2",
+    "sizeDelta": 13900
+  },
+  ...
+}
+```
+
 )""