From d50ce2df14138fc22e8528a37e5460e2f397420b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 15 May 2024 01:14:06 +0200
Subject: [PATCH] make a more relevant example for `nix-store --export`

given `nix-copy-closure` exists, it doesn't make much sense to do

    nix-store --export $paths | nix-store --import --store ssh://foo@bar

since that dumps everything rather than granularly transferring store
objects as needed.

therefore, pick an example where dumping the entire closure into a file
actually makes a difference, such as when deploying to airgapped systems.
---
 .../src/command-ref/nix-store/export.md       | 30 +++++++++++--------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/doc/manual/src/command-ref/nix-store/export.md b/doc/manual/src/command-ref/nix-store/export.md
index 1bc46f53b..4f6dd5ffa 100644
--- a/doc/manual/src/command-ref/nix-store/export.md
+++ b/doc/manual/src/command-ref/nix-store/export.md
@@ -27,15 +27,21 @@ Nix store, the import will fail.
 
 # Examples
 
-To copy a whole closure, do something
-like:
-
-```console
-$ nix-store --export $(nix-store --query --requisites paths) > out
-```
-
-To import the whole closure again, run:
-
-```console
-$ nix-store --import < out
-```
+> **Example**
+>
+> Deploy GNU Hello to an airgapped machine via USB stick.
+>
+> Write the closure to the block device on a machine with internet connection:
+>
+> ```shell-session
+> [alice@itchy]$ storePath=$(nix-build '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello --no-out-link)
+> [alice@itchy]$ nix-store --export $(nix-store --query --requisites $storePath) | sudo dd of=/dev/usb
+> ```
+>
+> Read the closure from the block device on the machine without internet connection:
+>
+> ```shell-session
+> [bob@scratchy]$ hello=$(sudo dd if=/dev/usb | nix-store --import | tail -1)
+> [bob@scratchy]$ $hello/bin/hello
+> Hello, world!
+> ```