From 161f4b0dea82bdaed7cf8928e523702f61cf899b Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Thu, 23 Mar 2023 10:38:48 +0100
Subject: [PATCH] Document store URLs

---
 src/libcmd/common-eval-args.cc |  6 +++++-
 src/libstore/globals.hh        | 12 +++++++----
 src/nix/help-stores.md         | 37 +++++++++++++++++++++++++++++++++-
 3 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index 908127b4d..166b8aaa9 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -136,7 +136,11 @@ MixEvalArgs::MixEvalArgs()
 
     addFlag({
         .longName = "eval-store",
-        .description = "The Nix store to use for evaluations.",
+        .description =
+          R"(
+            The [URL of the Nix store](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+            to use for evaluation, i.e. to store derivations (`.drv` files) and inputs referenced by them.
+          )",
         .category = category,
         .labels = {"store-url"},
         .handler = {&evalStoreUrl},
diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
index 4382d1b85..a74d5a46d 100644
--- a/src/libstore/globals.hh
+++ b/src/libstore/globals.hh
@@ -98,7 +98,9 @@ public:
 
     Setting<std::string> storeUri{this, getEnv("NIX_REMOTE").value_or("auto"), "store",
         R"(
-          The URL of the Nix store to use. See [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md)
+          The [URL of the Nix store](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+          to use for most operations.
+          See [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md)
           for supported store types and settings.
         )"};
 
@@ -681,8 +683,9 @@ public:
         Strings{"https://cache.nixos.org/"},
         "substituters",
         R"(
-          A list of URLs of substituters, separated by whitespace. Substituters
-          are tried based on their Priority value, which each substituter can set
+          A list of [URLs of Nix stores](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+          to be used as substituters, separated by whitespace.
+          Substituters are tried based on their Priority value, which each substituter can set
           independently. Lower value means higher priority.
           The default is `https://cache.nixos.org`, with a Priority of 40.
 
@@ -700,7 +703,8 @@ public:
     Setting<StringSet> trustedSubstituters{
         this, {}, "trusted-substituters",
         R"(
-          A list of URLs of substituters, separated by whitespace. These are
+          A list of [URLs of Nix stores](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format),
+          separated by whitespace. These are
           not used by default, but can be enabled by users of the Nix daemon
           by specifying `--option substituters urls` on the command
           line. Unprivileged users are only allowed to pass a subset of the
diff --git a/src/nix/help-stores.md b/src/nix/help-stores.md
index 8f872cb79..aa381393b 100644
--- a/src/nix/help-stores.md
+++ b/src/nix/help-stores.md
@@ -4,7 +4,42 @@ Nix supports different types of stores. These are described below.
 
 ## Store URL format
 
-TODO
+Stores are specified using a URL-like syntax. For example, the command
+
+```console
+# nix path-info --store https://cache.nixos.org/ --json \
+  /nix/store/a7gvj343m05j2s32xcnwr35v31ynlypr-coreutils-9.1
+```
+
+fetches information about a store path in the HTTP binary cache
+located at https://cache.nixos.org/, which is a type of store.
+
+Store URLs can specify **store settings** using URL query strings,
+i.e. by appending `?name1=value1&name2=value2&...` to the URL. For
+instance,
+
+```
+--store ssh://machine.example.org?ssh-key=/path/to/my/key
+```
+
+tells Nix to access the store on a remote machine via the SSH
+protocol, using `/path/to/my/key` as the SSH private key. The
+supported settings for each store type are documented below.
+
+The special store URL `auto` causes Nix to automatically select a
+store as follows:
+
+* Use the local store `/nix/store` if `/nix/var/nix` is writable by
+  the current user.
+
+* Otherwise, if `/nix/var/nix/daemon-socket/socket` exists, [connect
+  to the Nix daemon listening on that socket](#local-daemon-store).
+
+* Otherwise, on Linux only, use the local chroot store
+  `~/.local/share/nix/root`, which will be created automatically if it
+  does not exist.
+
+* Otherwise, use the local store `/nix/store`.
 
 @stores@