From 1f7061badc617efaaaa7f327606eccdf88127b8a Mon Sep 17 00:00:00 2001
From: David Gilligan-Cook <dcook@imageworks.com>
Date: Wed, 9 Oct 2024 11:59:18 -0700
Subject: [PATCH] Adding docs and fixing a comment

Signed-off-by: David Gilligan-Cook <dcook@imageworks.com>
---
 crates/spfs/src/tracking/env.rs |  2 +-
 cspell.json                     |  8 ++++++++
 docs/spfs/usage.md              | 34 +++++++++++++++++++++++++++++++--
 3 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/crates/spfs/src/tracking/env.rs b/crates/spfs/src/tracking/env.rs
index fd675c46db..e2d22f0f0d 100644
--- a/crates/spfs/src/tracking/env.rs
+++ b/crates/spfs/src/tracking/env.rs
@@ -121,7 +121,7 @@ impl SpfsSpecFile {
         let value: serde_yaml::Value = serde_yaml::from_str(s).map_err(Error::YAML)?;
 
         // First work out what kind of data this is, based on the
-        // SpfsFileApiVersionMapping value.
+        // SpfsSpecApiVersionMapping value.
         let with_version = match serde_yaml::from_value::<SpfsSpecApiVersionMapping>(value.clone())
         {
             Err(err) => {
diff --git a/cspell.json b/cspell.json
index 975da1b413..14a30edd52 100644
--- a/cspell.json
+++ b/cspell.json
@@ -19,6 +19,7 @@
     "aclocal",
     "acyclical",
     "addrs",
+    "A7USTIBXPXHMD5CYEIIOBMFLM3X77ESVR3WAUXQ7XQQGTHKH7DMQ",
     "AEMKIJQ",
     "AGVXA",
     "alib",
@@ -320,6 +321,7 @@
     "LASTEXITCODE",
     "lastword",
     "latform",
+    "layerlist",
     "lcms",
     "LDFLAGS",
     "libc",
@@ -352,6 +354,7 @@
     "LIDL",
     "linkat",
     "listdir",
+    "livelayer",
     "livelayerfile",
     "livetime",
     "LKLS",
@@ -367,6 +370,7 @@
     "lowerdirs",
     "lseek",
     "lstrip",
+    "M4JTN4ENZVHV4LEOZ5ONOFYOXQGN2OZBWOGDQXAQ54K5C6QAR2AQ",
     "MAGICAVOXEL",
     "makedirs",
     "makeinfo",
@@ -485,6 +489,7 @@
     "OWYWHJKCVRKGSBL",
     "OXFB",
     "OYMIQUY",
+    "PJDUUENJYFFDKZWRKHDUXK4FGGZ7FHDYMZ7P4CXORUG6TUMDJ7A",
     "parsedbuf",
     "parsewords",
     "partio",
@@ -635,6 +640,9 @@
     "somethingelse",
     "somevalue",
     "somevar",
+    "SOMEDIGEST",
+    "SOMEOTHERDIGEST",
+    "SOMETAG",
     "SOVERSION",
     "spdev",
     "SPFS",
diff --git a/docs/spfs/usage.md b/docs/spfs/usage.md
index 8738797923..e1db4a7b61 100644
--- a/docs/spfs/usage.md
+++ b/docs/spfs/usage.md
@@ -106,6 +106,36 @@ The pruning process will always prefer keeping a tag version over removing it wh
 
 The spfs runtime uses a temporary, in-memory filesystem, which means that large sets of changes can run out of space because of RAM limitations. The size of this filesystem can be overridden using the `SPFS_FILESYSTEM_TMPFS_SIZE` variable (eg `SPFS_FILESYSTEM_TMPFS_SIZE=10G`). Note that specifying values close to or larger than the available memory on the system may cause deadlocks or system instability.
 
+## Shorter spfs run command lines: list of layers in a file
+
+Spfs supports using a yaml file for the list of layer references, the digests or tags, for the runtime environment instead of putting them all on the command line. You can pass an absolute filepath to `spfs run`. Spfs will read the file and use the layer references in the order they are in the file. More than one filepath can be given, and these file paths can be mix with digest or tag references on the command line.
+
+For example:
+```sh
+# using a list of layers file
+> spfs run /path/to/list/of/layers.spfs.yaml
+
+# or, with digests
+> spfs run SOMEDIGEST+/path/to/list/of/layers.spfs.yaml+SOMEOTHERDIGEST
+
+# or, with digests and tags
+> spfs run SOMEDIGEST+/path/to/list/of/layers.spfs.yaml+SOMETAG
+```
+
+Example `layers.spfs.yaml` file containing a list of layers, a mixture of digests and tags, with specific fields in yaml format:
+
+```yaml
+# layers.spfs.yaml
+api: v0/layerlist
+layers:
+  - A7USTIBXPXHMD5CYEIIOBMFLM3X77ESVR3WAUXQ7XQQGTHKH7DMQ====
+  - spfs/some/tag/to/something/tagged/in/spfs/repo
+  - M4JTN4ENZVHV4LEOZ5ONOFYOXQGN2OZBWOGDQXAQ54K5C6QAR2AQ====
+  - 6PJDUUENJYFFDKZWRKHDUXK4FGGZ7FHDYMZ7P4CXORUG6TUMDJ7A====
+```
+
+List of layers files are distinguished from live layer files by their `api: v0/layerlist` field.
+
 
 ## Live Layers: external directories and files in a spfs runtime
 
@@ -115,7 +145,7 @@ A live layer is configured by a yaml file, called `layer.spfs.yaml` by default.
 
 You can give `spfs run` the path to a live layer file, or the path to a directory that contains a 'layer.spfs.yaml' file, as one of the REFS on the command line that will make up the spfs runtime, e.g. `spfs run digest+digest+livelayerfile+tag+digest`. Multiple files can be specified on the command line. `spfs run` will put a live layer into /spfs each for config file specified.
 
-Example `layer.spfs.yaml` file in `/some/directory/somewhere/`:
+Example `layer.spfs.yaml` file containing live layer data in `/some/directory/somewhere/`, in yaml format:
 
 ```yaml
 # layer.spfs.yaml
@@ -127,7 +157,7 @@ contents:
     dest: test_data/some.data
 ```
 
-The `api:` field is required to indicate which version of live layer is in the file.
+The `api:` field is required to indicate which version of live layer is in the file.  Live layers files are distinguished from list of layer files by their `api: v0/layer` field.
 
 The `contents:` field is required and tells spfs what this live layer will add into /spfs. It is a list of items. Currently spfs supports bind mount items in live layers. Each bind mount consists of a source (`bind:` or `src:`) path and a destination (`dest:`) path.