From 3994e5627fed704fc0a0cd9717f5d6b6f0f455e5 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 2 Jun 2025 12:06:21 +0200
Subject: [PATCH] nix store copy-sigs: Add docs

---
 src/nix/sigs.cc            |  7 +++++++
 src/nix/store-copy-sigs.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 src/nix/store-copy-sigs.md

diff --git a/src/nix/sigs.cc b/src/nix/sigs.cc
index 142421e9c..bb2cd4e6f 100644
--- a/src/nix/sigs.cc
+++ b/src/nix/sigs.cc
@@ -28,6 +28,13 @@ struct CmdCopySigs : StorePathsCommand
         return "copy store path signatures from substituters";
     }
 
+    std::string doc() override
+    {
+        return
+#include "store-copy-sigs.md"
+            ;
+    }
+
     void run(ref<Store> store, StorePaths && storePaths) override
     {
         if (substituterUris.empty())
diff --git a/src/nix/store-copy-sigs.md b/src/nix/store-copy-sigs.md
new file mode 100644
index 000000000..678756221
--- /dev/null
+++ b/src/nix/store-copy-sigs.md
@@ -0,0 +1,30 @@
+R""(
+
+# Examples
+
+* To copy signatures from a binary cache to the local store:
+
+  ```console
+  # nix store copy-sigs --substituter https://cache.nixos.org \
+      --recursive /nix/store/y1x7ng5bmc9s8lqrf98brcpk1a7lbcl5-hello-2.12.1
+  ```
+
+* To copy signatures from one binary cache to another:
+
+  ```console
+  # nix store copy-sigs --substituter https://cache.nixos.org \
+      --store file:///tmp/binary-cache \
+      --recursive -v \
+      /nix/store/y1x7ng5bmc9s8lqrf98brcpk1a7lbcl5-hello-2.12.1
+  imported 2 signatures
+  ```
+
+# Description
+
+`nix store copy-sigs` copies store path signatures from one store to another.
+
+It is not advised to copy signatures to binary cache stores. Binary cache signatures are stored in `.narinfo` files. Since these are cached aggressively, clients may not see the new signatures quickly. It is therefore better to set any required signatures when the paths are first uploaded to the binary cache.
+
+Store paths are processed in parallel. The amount of parallelism is controlled by the [`http-connections`](@docroot@/command-ref/conf-file.md#conf-http-connections) settings.
+
+)""