From b68558ea09f0a5bb047cac7f60a156b8c4f7506e Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 14 May 2025 20:18:08 -0500 Subject: [PATCH 01/15] Add new option to spfs clean to allow for building documentation Signed-off-by: Bryce Gattis --- crates/spfs-cli/cmd-clean/Cargo.toml | 1 + crates/spfs-cli/cmd-clean/src/cmd_clean.rs | 7 +++++++ 2 files changed, 8 insertions(+) diff --git a/crates/spfs-cli/cmd-clean/Cargo.toml b/crates/spfs-cli/cmd-clean/Cargo.toml index 62a1c0c67d..e44605b145 100644 --- a/crates/spfs-cli/cmd-clean/Cargo.toml +++ b/crates/spfs-cli/cmd-clean/Cargo.toml @@ -22,6 +22,7 @@ sentry = ["spfs-cli-common/sentry"] [dependencies] chrono = { workspace = true } clap = { workspace = true } +clap-markdown = "0.1.5" colored = { workspace = true } miette = { workspace = true, features = ["fancy"] } question = "0.2.2" diff --git a/crates/spfs-cli/cmd-clean/src/cmd_clean.rs b/crates/spfs-cli/cmd-clean/src/cmd_clean.rs index 493a25bc8e..ba4f6f622e 100644 --- a/crates/spfs-cli/cmd-clean/src/cmd_clean.rs +++ b/crates/spfs-cli/cmd-clean/src/cmd_clean.rs @@ -113,6 +113,8 @@ pub struct CmdClean { default_value_t = spfs::Cleaner::DEFAULT_DISCOVER_CONCURRENCY )] max_discover_concurrency: usize, + #[clap(long, hide = true)] + markdown_help: bool } impl CommandName for CmdClean { @@ -123,6 +125,11 @@ impl CommandName for CmdClean { impl CmdClean { pub async fn run(&mut self, config: &spfs::Config) -> Result { + if self.markdown_help { + clap_markdown::print_help_markdown::(); + return Ok(0); + } + let mut repo = spfs::config::open_repository_from_string(config, self.remote.as_ref()).await?; tracing::debug!("spfs clean command called"); From 128df22154e7cf99c486c38af2299b460a18e098 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 14 May 2025 20:19:13 -0500 Subject: [PATCH 02/15] Add new generated documentation page and parent page for spfs CLI usage landing page Signed-off-by: Bryce Gattis --- docs/spfs/cli/_index.md | 13 +++++++++ docs/spfs/cli/clean.md | 61 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/spfs/cli/_index.md create mode 100644 docs/spfs/cli/clean.md diff --git a/docs/spfs/cli/_index.md b/docs/spfs/cli/_index.md new file mode 100644 index 0000000000..6b4495e93c --- /dev/null +++ b/docs/spfs/cli/_index.md @@ -0,0 +1,13 @@ +--- +title: CLI +chapter: true +--- + +# CLI + +CLI usage documentation for `spfs` + +Somehow list the subcommands here: + +- subcommand1 with hyperlink +- subcommand2 with hyperlink \ No newline at end of file diff --git a/docs/spfs/cli/clean.md b/docs/spfs/cli/clean.md new file mode 100644 index 0000000000..045f960ff2 --- /dev/null +++ b/docs/spfs/cli/clean.md @@ -0,0 +1,61 @@ +--- +title: Clean +chapter: true +--- + +# Command-Line Help for `spfs-clean` + +This document contains the help content for the `spfs-clean` command-line program. + +**Command Overview:** + +* [`spfs-clean`↴](#spfs-clean) + +## `spfs-clean` + +Clean the repository storage of any untracked data + +Untracked data is any data that is not tagged or is not attached to/used by a tagged object. This command also provides semantics for pruning a repository from older tag data to help detach additional data and reduce repository size. + +**Usage:** `spfs-clean [OPTIONS]` + +###### **Options:** + +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) +* `-r`, `--remote ` — Trigger the clean operation on a remote repository +* `--remove-durable ` — Remove the durable upper path component of the named runtime. If given, this will be the only thing removed +* `--runtime-storage ` — The address of the storage being used for runtimes + + Defaults to the current configured local repository. +* `-y`, `--yes` — Don't prompt/ask before cleaning the data +* `--dry-run` — Don't delete anything, just print what would be deleted (assumes --yes) +* `--prune-repeated` — Prune old tags that have the same target as a more recent version +* `--prune-repeated-keep ` — When pruning old tag that have the same target as a more recent version, keep this many of the repeated tags +* `--prune-if-older-than ` — Prune tags older that the given age (eg: 1y, 8w, 10d, 3h, 4m, 8s) +* `--keep-if-newer-than ` — Always keep data newer than the given age (eg: 1y, 8w, 10d, 3h, 4m, 8s) +* `--prune-if-more-than ` — Prune tags if there are more than this number in a stream +* `--keep-if-less-than ` — Always keep at least this number of tags in a stream +* `--keep-proxies-with-no-links` — Do not remove proxies for users that have no additional hard links. + + Proxies will still be removed if the object is unattached. This is enabled by default because it is generally considered safe and can be effective at reducing disk usage. +* `--max-tag-stream-concurrency ` + + Default value: `500` +* `--max-removal-concurrency ` + + Default value: `500` +* `--max-discover-concurrency ` + + Default value: `50` + + + +
+ + + This document was generated automatically by + clap-markdown. + + From 80b6c2623bfa83b82df6ea25dba8ae01d848b30d Mon Sep 17 00:00:00 2001 From: BryceGattis Date: Mon, 26 May 2025 20:57:20 -0500 Subject: [PATCH 03/15] Revert cmd-clean specific doc generation Signed-off-by: BryceGattis --- crates/spfs-cli/cmd-clean/Cargo.toml | 1 - crates/spfs-cli/cmd-clean/src/cmd_clean.rs | 7 --- docs/spfs/cli/_index.md | 13 ----- docs/spfs/cli/clean.md | 61 ---------------------- 4 files changed, 82 deletions(-) delete mode 100644 docs/spfs/cli/_index.md delete mode 100644 docs/spfs/cli/clean.md diff --git a/crates/spfs-cli/cmd-clean/Cargo.toml b/crates/spfs-cli/cmd-clean/Cargo.toml index e44605b145..62a1c0c67d 100644 --- a/crates/spfs-cli/cmd-clean/Cargo.toml +++ b/crates/spfs-cli/cmd-clean/Cargo.toml @@ -22,7 +22,6 @@ sentry = ["spfs-cli-common/sentry"] [dependencies] chrono = { workspace = true } clap = { workspace = true } -clap-markdown = "0.1.5" colored = { workspace = true } miette = { workspace = true, features = ["fancy"] } question = "0.2.2" diff --git a/crates/spfs-cli/cmd-clean/src/cmd_clean.rs b/crates/spfs-cli/cmd-clean/src/cmd_clean.rs index ba4f6f622e..493a25bc8e 100644 --- a/crates/spfs-cli/cmd-clean/src/cmd_clean.rs +++ b/crates/spfs-cli/cmd-clean/src/cmd_clean.rs @@ -113,8 +113,6 @@ pub struct CmdClean { default_value_t = spfs::Cleaner::DEFAULT_DISCOVER_CONCURRENCY )] max_discover_concurrency: usize, - #[clap(long, hide = true)] - markdown_help: bool } impl CommandName for CmdClean { @@ -125,11 +123,6 @@ impl CommandName for CmdClean { impl CmdClean { pub async fn run(&mut self, config: &spfs::Config) -> Result { - if self.markdown_help { - clap_markdown::print_help_markdown::(); - return Ok(0); - } - let mut repo = spfs::config::open_repository_from_string(config, self.remote.as_ref()).await?; tracing::debug!("spfs clean command called"); diff --git a/docs/spfs/cli/_index.md b/docs/spfs/cli/_index.md deleted file mode 100644 index 6b4495e93c..0000000000 --- a/docs/spfs/cli/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: CLI -chapter: true ---- - -# CLI - -CLI usage documentation for `spfs` - -Somehow list the subcommands here: - -- subcommand1 with hyperlink -- subcommand2 with hyperlink \ No newline at end of file diff --git a/docs/spfs/cli/clean.md b/docs/spfs/cli/clean.md deleted file mode 100644 index 045f960ff2..0000000000 --- a/docs/spfs/cli/clean.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Clean -chapter: true ---- - -# Command-Line Help for `spfs-clean` - -This document contains the help content for the `spfs-clean` command-line program. - -**Command Overview:** - -* [`spfs-clean`↴](#spfs-clean) - -## `spfs-clean` - -Clean the repository storage of any untracked data - -Untracked data is any data that is not tagged or is not attached to/used by a tagged object. This command also provides semantics for pruning a repository from older tag data to help detach additional data and reduce repository size. - -**Usage:** `spfs-clean [OPTIONS]` - -###### **Options:** - -* `-v`, `--verbose` — Make output more verbose, can be specified more than once -* `--log-file ` — Additionally log output to the provided file -* `--timestamp` — Enables timestamp in logging (always enabled in file log) -* `-r`, `--remote ` — Trigger the clean operation on a remote repository -* `--remove-durable ` — Remove the durable upper path component of the named runtime. If given, this will be the only thing removed -* `--runtime-storage ` — The address of the storage being used for runtimes - - Defaults to the current configured local repository. -* `-y`, `--yes` — Don't prompt/ask before cleaning the data -* `--dry-run` — Don't delete anything, just print what would be deleted (assumes --yes) -* `--prune-repeated` — Prune old tags that have the same target as a more recent version -* `--prune-repeated-keep ` — When pruning old tag that have the same target as a more recent version, keep this many of the repeated tags -* `--prune-if-older-than ` — Prune tags older that the given age (eg: 1y, 8w, 10d, 3h, 4m, 8s) -* `--keep-if-newer-than ` — Always keep data newer than the given age (eg: 1y, 8w, 10d, 3h, 4m, 8s) -* `--prune-if-more-than ` — Prune tags if there are more than this number in a stream -* `--keep-if-less-than ` — Always keep at least this number of tags in a stream -* `--keep-proxies-with-no-links` — Do not remove proxies for users that have no additional hard links. - - Proxies will still be removed if the object is unattached. This is enabled by default because it is generally considered safe and can be effective at reducing disk usage. -* `--max-tag-stream-concurrency ` - - Default value: `500` -* `--max-removal-concurrency ` - - Default value: `500` -* `--max-discover-concurrency ` - - Default value: `50` - - - -
- - - This document was generated automatically by - clap-markdown. - - From 1d6b02274527e4ff4423e66e9197102ce3cd678e Mon Sep 17 00:00:00 2001 From: BryceGattis Date: Mon, 26 May 2025 21:03:07 -0500 Subject: [PATCH 04/15] Second iteration where it generates docs for all spfs commands Signed-off-by: BryceGattis --- crates/spfs-cli/main/Cargo.toml | 1 + crates/spfs-cli/main/src/bin.rs | 3 + crates/spfs-cli/main/src/cmd_docs.rs | 17 + docs/spfs/cli/markdown.md | 806 +++++++++++++++++++++++++++ 4 files changed, 827 insertions(+) create mode 100644 crates/spfs-cli/main/src/cmd_docs.rs create mode 100644 docs/spfs/cli/markdown.md diff --git a/crates/spfs-cli/main/Cargo.toml b/crates/spfs-cli/main/Cargo.toml index 32dbe3409d..7bc4a51338 100644 --- a/crates/spfs-cli/main/Cargo.toml +++ b/crates/spfs-cli/main/Cargo.toml @@ -33,6 +33,7 @@ server = [ async-recursion = "1.0.2" chrono = { workspace = true } clap = { workspace = true } +clap-markdown = "0.1.5" colored = "2.0" dunce = { workspace = true } futures = { workspace = true } diff --git a/crates/spfs-cli/main/src/bin.rs b/crates/spfs-cli/main/src/bin.rs index a1c39291e4..b397517108 100644 --- a/crates/spfs-cli/main/src/bin.rs +++ b/crates/spfs-cli/main/src/bin.rs @@ -38,6 +38,7 @@ mod cmd_tags; mod cmd_untag; mod cmd_version; mod cmd_write; +mod cmd_docs; use spfs_cli_common as cli; use spfs_cli_common::CommandName; @@ -90,6 +91,7 @@ pub enum Command { Check(cmd_check::CmdCheck), Read(cmd_read::CmdRead), Write(cmd_write::CmdWrite), + Docs(cmd_docs::CmdDocs), #[cfg(feature = "server")] Server(cmd_server::CmdServer), @@ -133,6 +135,7 @@ impl Opt { Command::Shell(cmd) => cmd.run(config).await, Command::Pull(cmd) => cmd.run(config).await, Command::Push(cmd) => cmd.run(config).await, + Command::Docs(cmd) => cmd.run(config).await, #[cfg(feature = "server")] Command::Server(cmd) => cmd.run(config).await, Command::External(args) => run_external_subcommand(args.clone()).await, diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/main/src/cmd_docs.rs new file mode 100644 index 0000000000..6c130b231d --- /dev/null +++ b/crates/spfs-cli/main/src/cmd_docs.rs @@ -0,0 +1,17 @@ +// Copyright (c) Contributors to the SPK project. +// SPDX-License-Identifier: Apache-2.0 +// https://github.com/spkenv/spk + +use clap::Args; +use miette::{IntoDiagnostic, Result}; + +/// Output the current configuration of spfs +#[derive(Debug, Args)] +pub struct CmdDocs {} + +impl CmdDocs { + pub async fn run(&mut self, config: &spfs::Config) -> Result { + clap_markdown::print_help_markdown::(); + Ok(0) + } +} diff --git a/docs/spfs/cli/markdown.md b/docs/spfs/cli/markdown.md new file mode 100644 index 0000000000..caca8a5e43 --- /dev/null +++ b/docs/spfs/cli/markdown.md @@ -0,0 +1,806 @@ +--- +title: SPFS CLI +chapter: true +--- + +# Command-Line Help for `spfs-cli-main` + +This document contains the help content for the `spfs-cli-main` command-line program. + +**Command Overview:** + +* [`spfs-cli-main`↴](#spfs-cli-main) +* [`spfs-cli-main version`↴](#spfs-cli-main-version) +* [`spfs-cli-main init`↴](#spfs-cli-main-init) +* [`spfs-cli-main init repo`↴](#spfs-cli-main-init-repo) +* [`spfs-cli-main edit`↴](#spfs-cli-main-edit) +* [`spfs-cli-main commit`↴](#spfs-cli-main-commit) +* [`spfs-cli-main config`↴](#spfs-cli-main-config) +* [`spfs-cli-main reset`↴](#spfs-cli-main-reset) +* [`spfs-cli-main run`↴](#spfs-cli-main-run) +* [`spfs-cli-main tag`↴](#spfs-cli-main-tag) +* [`spfs-cli-main untag`↴](#spfs-cli-main-untag) +* [`spfs-cli-main shell`↴](#spfs-cli-main-shell) +* [`spfs-cli-main runtime`↴](#spfs-cli-main-runtime) +* [`spfs-cli-main runtime info`↴](#spfs-cli-main-runtime-info) +* [`spfs-cli-main runtime list`↴](#spfs-cli-main-runtime-list) +* [`spfs-cli-main runtime prune`↴](#spfs-cli-main-runtime-prune) +* [`spfs-cli-main runtime remove`↴](#spfs-cli-main-runtime-remove) +* [`spfs-cli-main layers`↴](#spfs-cli-main-layers) +* [`spfs-cli-main platforms`↴](#spfs-cli-main-platforms) +* [`spfs-cli-main tags`↴](#spfs-cli-main-tags) +* [`spfs-cli-main info`↴](#spfs-cli-main-info) +* [`spfs-cli-main pull`↴](#spfs-cli-main-pull) +* [`spfs-cli-main push`↴](#spfs-cli-main-push) +* [`spfs-cli-main log`↴](#spfs-cli-main-log) +* [`spfs-cli-main search`↴](#spfs-cli-main-search) +* [`spfs-cli-main diff`↴](#spfs-cli-main-diff) +* [`spfs-cli-main ls-tags`↴](#spfs-cli-main-ls-tags) +* [`spfs-cli-main ls`↴](#spfs-cli-main-ls) +* [`spfs-cli-main migrate`↴](#spfs-cli-main-migrate) +* [`spfs-cli-main check`↴](#spfs-cli-main-check) +* [`spfs-cli-main read`↴](#spfs-cli-main-read) +* [`spfs-cli-main write`↴](#spfs-cli-main-write) +* [`spfs-cli-main docs`↴](#spfs-cli-main-docs) + +## `spfs-cli-main` + +SPK is a Package Manager for high-velocity software environments, built on SPFS. SPFS is a system for filesystem isolation, capture, and distribution. + +**Usage:** `spfs-cli-main [OPTIONS] ` + +EXTERNAL SUBCOMMANDS: + render render the contents of an environment or layer + monitor watch a runtime and clean it up when complete + +###### **Subcommands:** + +* `version` — Print the version of spfs +* `init` — Create an empty filesystem repository +* `edit` — Make the current runtime editable +* `commit` — Commit the current runtime state or a directory to storage +* `config` — Output the current configuration of spfs +* `reset` — Reset changes, or rebuild the entire spfs directory +* `run` — Run a program in a configured spfs environment +* `tag` — Tag an object +* `untag` — Remove tag versions or entire tag streams +* `shell` — Enter a subshell in a configured spfs environment +* `runtime` — View and manage spfs runtime information +* `layers` — List all layers in an spfs repository +* `platforms` — List all platforms in an spfs repository +* `tags` — List all tags in an spfs repository +* `info` — Display information about the current environment, or specific items +* `pull` — Pull one or more objects to the local repository +* `push` — Push one or more objects to a remote repository +* `log` — Log the history of a given tag over time +* `search` — Search for available tags by substring +* `diff` — Compare two spfs file system states +* `ls-tags` — List tags by their path +* `ls` — List the contents of a committed directory +* `migrate` — Migrate the data from and older repository format to the latest one +* `check` — Check a repositories internal integrity +* `read` — Output the contents of a blob to stdout +* `write` — Store an arbitrary blob of data in spfs +* `docs` — Output the current configuration of spfs + +###### **Options:** + +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) + + + +## `spfs-cli-main version` + +Print the version of spfs + +**Usage:** `spfs-cli-main version` + + + +## `spfs-cli-main init` + +Create an empty filesystem repository + +**Usage:** `spfs-cli-main init ` + +###### **Subcommands:** + +* `repo` — Initialize an empty filesystem repository + + + +## `spfs-cli-main init repo` + +Initialize an empty filesystem repository + +Does nothing when run on an existing repository + +**Usage:** `spfs-cli-main init repo ` + +###### **Arguments:** + +* `` — The root of the new repository + + + +## `spfs-cli-main edit` + +Make the current runtime editable + +**Usage:** `spfs-cli-main edit [OPTIONS]` + +###### **Options:** + +* `--off` — Disable edit mode instead +* `--keep-runtime` — Change a runtime into a durable runtime, will also make the runtime editable + + + +## `spfs-cli-main commit` + +Commit the current runtime state or a directory to storage + +**Usage:** `spfs-cli-main commit [OPTIONS] [KIND]` + +###### **Arguments:** + +* `` — The desired object type to create, skip this when giving --path or --ref + + Possible values: `layer`, `platform` + + +###### **Options:** + +* `-r`, `--remote ` — Commit files directly into a remote repository + + The default is to commit to the local repository. This flag is only valid with the --path argument. +* `-t`, `--tag ` — A human-readable tag for the generated object + + Can be provided more than once. +* `--path ` — Commit this directory instead of the current spfs changes +* `--ref ` — Combine existing items into a platform, use a '+' to join multiple +* `--hash-while-committing` — Hash the files while committing, rather than before. + + This option can improve commit times when a large number of the files are both large, and don't already exist in the repository. It may degrade commit times when committing directly to a slow or remote repository. When given, all files are written to the repository even if the payload exists, rather than hashing the file first to determine if it needs to be transferred. +* `--max-concurrent-blobs ` — The total number of blobs that can be committed concurrently + + Default value: `1000` +* `--max-concurrent-branches ` — The total number of branches that can be processed concurrently at each level of the rendered file tree. + + The number of active trees being processed can grow exponentially by this exponent for each additional level of depth in the rendered file tree. In general, this number should be kept low. + + Default value: `5` + + + +## `spfs-cli-main config` + +Output the current configuration of spfs + +**Usage:** `spfs-cli-main config` + + + +## `spfs-cli-main reset` + +Reset changes, or rebuild the entire spfs directory + +**Usage:** `spfs-cli-main reset [OPTIONS] [PATHS]...` + +###### **Arguments:** + +* `` — Glob patterns in the spfs dir of files to reset, defaults to everything + +###### **Options:** + +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. +* `--resync` — Forcefully sync all associated graph data even if it already exists + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently + + Default value: `100` +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently + + Default value: `100` +* `--progress ` — Options for showing progress + + Possible values: + - `bars`: + Show progress bars (default) + - `none`: + Do not show any progress + +* `-e`, `--edit` — Mount the resulting runtime in edit mode + + Default to true if REF is empty or not given +* `-r`, `--ref ` — The tag or id to rebuild the runtime with. + + Uses current runtime stack if not given. Use '-' or an empty string to request an empty environment. Only valid if no paths are given + + + +## `spfs-cli-main run` + +Run a program in a configured spfs environment + +**Usage:** `spfs-cli-main run [OPTIONS] <--rerun |REFERENCE> [-- ...]` + +###### **Arguments:** + +* `` — The tag or id of the desired runtime + + Use '-' to request an empty environment +* `` — The command to run in the environment and its arguments + + In order to ensure that flags are passed as-is, '--' must be place before specifying the command and any flags that should be given to that command: e.g. `spfs run -- command --flag-for-command` + +###### **Options:** + +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. +* `--resync` — Forcefully sync all associated graph data even if it already exists + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently + + Default value: `100` +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently + + Default value: `100` +* `--progress ` — Options for showing progress + + Possible values: + - `bars`: + Show progress bars (default) + - `none`: + Do not show any progress + +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) +* `-e`, `--edit` — Mount the spfs filesystem in edit mode (default if REF is empty or not given) +* `--no-edit` — Mount the spfs filesystem in read-only mode (default if REF is non-empty) +* `--force` — Requires --rerun. Force reset the process fields of the runtime before it is run again +* `-k`, `--keep-runtime` — Use to keep the runtime around rather than deleting it when the process exits. This is best used with '--name NAME' to make rerunning the runtime easier at a later time +* `--runtime-name ` — Provide a name for this runtime to make it easier to identify +* `--rerun ` — Name of an existing durable runtime to reuse for this run +* `--annotation ` — Adds annotation key-value string data to the new runtime. + + This allows external processes to store arbitrary data in the runtimes they create. This is most useful with durable runtimes. The data can be retrieved by running `spfs runtime info` or `spfs info` and using the `--get ` or `--get-all` options + + Annotation data is specified as key-value string pairs separated by either an equals sign or colon (--annotation name=value --annotation other:value). Multiple pairs of annotation data can also be specified at once in yaml or json format (--annotation '{name: value, other: value}'). + + Annotation data can also be given in a json or yaml file, by using the `--annotation-file ` argument. If given, `--annotation` arguments will supersede anything given in annotation files. + + If the same key is used more than once, the last key-value pair will override the earlier values for the same key. +* `--annotation-file ` — Specify annotation key-value data from a json or yaml file (see --annotation) + + + +## `spfs-cli-main tag` + +Tag an object + +**Usage:** `spfs-cli-main tag [OPTIONS] ...` + +###### **Arguments:** + +* `` — The reference or id of the item to tag +* `` — The tag(s) to point to the the given target + +###### **Options:** + +* `-r`, `--remote ` — Create tags in a remote repository instead of the local one + + + +## `spfs-cli-main untag` + +Remove tag versions or entire tag streams + +**Usage:** `spfs-cli-main untag [OPTIONS] ` + +###### **Arguments:** + +* `` — The tag to remove + + Unless --all or --latest is provided, this must have an explicit version number (eg: path/name~0) + +###### **Options:** + +* `-r`, `--remote ` — Remove tags in a remote repository instead of the local one +* `--latest` — Only remove the latest version of this tag +* `-a`, `--all` — Remove all versions of this tag, deleting it completely + + + +## `spfs-cli-main shell` + +Enter a subshell in a configured spfs environment + +**Usage:** `spfs-cli-main shell [OPTIONS] <--rerun |REF>` + +###### **Arguments:** + +* `` — The tag or id of the desired runtime + + Use '-' or nothing to request an empty environment + +###### **Options:** + +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. +* `--resync` — Forcefully sync all associated graph data even if it already exists + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently + + Default value: `100` +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently + + Default value: `100` +* `--progress ` — Options for showing progress + + Possible values: + - `bars`: + Show progress bars (default) + - `none`: + Do not show any progress + +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) +* `-e`, `--edit` — Mount the spfs filesystem in edit mode (true if REF is empty or not given) +* `--no-edit` — Mount the spfs filesystem in read-only mode (default if REF is non-empty) +* `--rerun ` — Name of a previously run durable runtime to reuse for this run +* `--force` — Requires --rerun. Force reset the process fields of the runtime before it is run again +* `--runtime-name ` — Provide a name for this runtime to make it easier to identify +* `-k`, `--keep-runtime` — Use to keep the runtime around rather than deleting it when the process exits. This is best used with '--name NAME' to make rerunning the runtime easier at a later time +* `--annotation ` — Adds annotation key-value string data to the new runtime. + + This allows external processes to store arbitrary data in the runtimes they create. This is most useful with durable runtimes. The data can be retrieved by running `spfs runtime info` or `spfs info` and using the `--get ` or `--get-all` options + + Annotation data is specified as key-value string pairs separated by either an equals sign or colon (--annotation name=value --annotation other:value). Multiple pairs of annotation data can also be specified at once in yaml or json format (--annotation '{name: value, other: value}'). + + Annotation data can also be given in a json or yaml file, by using the `--annotation-file ` argument. If given, `--annotation` arguments will supersede anything given in annotation files. + + If the same key is used more than once, the last key-value pair will override the earlier values for the same key. +* `--annotation-file ` — Specify annotation key-value data from a json or yaml file (see --annotation) + + + +## `spfs-cli-main runtime` + +View and manage spfs runtime information + +**Usage:** `spfs-cli-main runtime ` + +**Command Alias:** `rt` + +###### **Subcommands:** + +* `info` — Show the complete state of a runtime +* `list` — List runtime information from the repository +* `prune` — Find and remove runtimes from the repository based on a pruning strategy +* `remove` — Remove runtimes from the repository + + + +## `spfs-cli-main runtime info` + +Show the complete state of a runtime + +**Usage:** `spfs-cli-main runtime info [OPTIONS] ` + +###### **Arguments:** + +* `` — The name/id of the runtime to remove + +###### **Options:** + +* `-r`, `--remote ` — Load a runtime in a remote or alternate repository +* `--get ` — Output the data value for the given annotation key(s) from the active runtime. Each value is printed on its own line without its key +* `--get-all` — Output all the annotation keys and values from the active runtime as a yaml dictionary + + + +## `spfs-cli-main runtime list` + +List runtime information from the repository + +**Usage:** `spfs-cli-main runtime list [OPTIONS]` + +**Command Alias:** `ls` + +###### **Options:** + +* `-r`, `--remote ` — List runtimes in a remote or alternate repository +* `-q`, `--quiet` — Only print the name of each runtime, no additional data + + + +## `spfs-cli-main runtime prune` + +Find and remove runtimes from the repository based on a pruning strategy + +**Usage:** `spfs-cli-main runtime prune [OPTIONS]` + +###### **Options:** + +* `-r`, `--remote ` — Prune a runtime in a remote or alternate repository +* `--ignore-user` — Remove the runtime even if it's owned by someone else +* `--ignore-host` — Remove the runtime even if it appears to be from a different host + + Implies --ignore-monitor +* `--ignore-monitor` — Do not try and terminate the monitor process, just remove runtime data +* `--from-before-boot` — Remove runtimes started before last reboot + + + +## `spfs-cli-main runtime remove` + +Remove runtimes from the repository + +**Usage:** `spfs-cli-main runtime remove [OPTIONS] [NAME]...` + +**Command Alias:** `rm` + +###### **Arguments:** + +* `` — The name/id of the runtime to remove + +###### **Options:** + +* `-r`, `--remote ` — Remove a runtime in a remote or alternate repository +* `-f`, `--force` — Remove the runtime from the repository forcefully + + Even if the monitor cannot be stopped or killed the data will be removed from the repository. +* `--ignore-user` — Remove the runtime even if it's owned by someone else +* `--ignore-host` — Remove the runtime even if it appears to be from a different host + + Implies --ignore-monitor +* `--ignore-monitor` — Do not try and terminate the monitor process, just remove runtime data +* `--remove-durable` — Allow durable runtimes to be removed, normally they will not be removed + + + +## `spfs-cli-main layers` + +List all layers in an spfs repository + +**Usage:** `spfs-cli-main layers [OPTIONS]` + +###### **Options:** + +* `-r`, `--remote ` — Show layers from remote repository instead of the local one +* `--short` — Show the shortened form of each reported layer digest +* `--tags` — Also find and report any tags that point to each layer, implies --short + + + +## `spfs-cli-main platforms` + +List all platforms in an spfs repository + +**Usage:** `spfs-cli-main platforms [OPTIONS]` + +###### **Options:** + +* `-r`, `--remote ` — Show layers from remote repository instead of the local one +* `--short` — Show the shortened form of each reported layer digest +* `--tags` — Also find and report any tags that point to each platform, implies --short + + + +## `spfs-cli-main tags` + +List all tags in an spfs repository + +**Usage:** `spfs-cli-main tags [OPTIONS]` + +###### **Options:** + +* `-r`, `--remote ` — Show layers from remote repository instead of the local one +* `--target` — Also show the target digest of each tag +* `--short` — Show the shortened form of each reported digest, implies --target + + + +## `spfs-cli-main info` + +Display information about the current environment, or specific items + +**Usage:** `spfs-cli-main info [OPTIONS] [REF]...` + +###### **Arguments:** + +* `` — Tag, id, or /spfs/file/path to show information about + +###### **Options:** + +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) +* `--get ` — Output the data value for the given annotation key(s) from the active runtime. Each value is printed on its own line without its key +* `--get-all` — Output all the annotation keys and values from the active runtime as a yaml dictionary +* `-H`, `--human-readable` — Lists file sizes in human readable format +* `-r`, `--remote ` — Operate on a remote repository instead of the local one + + This is really only helpful if you are providing a specific ref to look up. +* `--tags` — Also find and report any tags that point to any identified digest (implies '--short') +* `--short` — Use shortened digests in the output (nicer, but slower) +* `--follow` — Follow and show child objects, depth-first + + + +## `spfs-cli-main pull` + +Pull one or more objects to the local repository + +**Usage:** `spfs-cli-main pull [OPTIONS] ...` + +###### **Arguments:** + +* `` — The reference(s) to pull/localize + + These can be individual tags or digests, or they may also be a collection of items joined by a '+' + +###### **Options:** + +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. +* `--resync` — Forcefully sync all associated graph data even if it already exists + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently + + Default value: `100` +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently + + Default value: `100` +* `--progress ` — Options for showing progress + + Possible values: + - `bars`: + Show progress bars (default) + - `none`: + Do not show any progress + +* `-v`, `--verbose` +* `-r`, `--remote ` — The name or address of the remote server to pull from + + Defaults to searching all configured remotes + + + +## `spfs-cli-main push` + +Push one or more objects to a remote repository + +**Usage:** `spfs-cli-main push [OPTIONS] ...` + +###### **Arguments:** + +* `` — The reference(s) to push + + These can be individual tags or digests, or they may also be a collection of items joined by a '+' + +###### **Options:** + +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. +* `--resync` — Forcefully sync all associated graph data even if it already exists + + When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently + + Default value: `100` +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently + + Default value: `100` +* `--progress ` — Options for showing progress + + Possible values: + - `bars`: + Show progress bars (default) + - `none`: + Do not show any progress + +* `-v`, `--verbose` +* `-r`, `--remote ` — The name or address of the remote server to push to + + Default value: `origin` + + + +## `spfs-cli-main log` + +Log the history of a given tag over time + +**Usage:** `spfs-cli-main log [OPTIONS] ` + +###### **Arguments:** + +* `` — The tag to show history of + +###### **Options:** + +* `-r`, `--remote ` — Load the tag from remote repository instead of the local one + + + +## `spfs-cli-main search` + +Search for available tags by substring + +**Usage:** `spfs-cli-main search ` + +###### **Arguments:** + +* `` — The search term/substring to look for + + + +## `spfs-cli-main diff` + +Compare two spfs file system states + +**Usage:** `spfs-cli-main diff [FROM] [TO]` + +###### **Arguments:** + +* `` — The tag or id to use as the base of the computed diff, defaults to the current runtime +* `` — The tag or id to diff the base against, defaults to the contents of the spfs filesystem + + + +## `spfs-cli-main ls-tags` + +List tags by their path + +**Usage:** `spfs-cli-main ls-tags [OPTIONS] [PATH]` + +**Command Alias:** `list-tags` + +###### **Arguments:** + +* `` — The tag path to list under + + Default value: `/` + +###### **Options:** + +* `-r`, `--remote ` — List tags from a remote repository instead of the local one +* `--recursive` — Walk the tag tree recursively listing all tags under the specified dir + + + +## `spfs-cli-main ls` + +List the contents of a committed directory + +**Usage:** `spfs-cli-main ls [OPTIONS] [PATH]` + +**Command Aliases:** `list-dir`, `list` + +###### **Arguments:** + +* `` — The tag or digest of the file tree to read from +* `` — The subdirectory to list + + Default value: `/spfs` + +###### **Options:** + +* `-r`, `--remote ` — List files on a remote repository instead of the local one +* `-R`, `--recursive` — Recursively list all files and directories +* `-l` — Long listing format +* `-H`, `--human-readable` — Lists file sizes in human readable format + + + +## `spfs-cli-main migrate` + +Migrate the data from and older repository format to the latest one + +**Usage:** `spfs-cli-main migrate [OPTIONS] ` + +###### **Arguments:** + +* `` — The path to the filesystem repository to migrate + +###### **Options:** + +* `--upgrade` — Replace old data with migrated data one complete + + + +## `spfs-cli-main check` + +Check a repositories internal integrity + +**Usage:** `spfs-cli-main check [OPTIONS] [REF]...` + +###### **Arguments:** + +* `` — Objects to recursively check, defaults to everything + +###### **Options:** + +* `-r`, `--remote ` — Trigger the check operation on a remote repository instead of the local one +* `--max-tag-stream-concurrency ` — The maximum number of tag streams that can be read and processed at once + + Default value: `1000` +* `--max-object-concurrency ` — The maximum number of objects that can be validated at once + + Default value: `5000` +* `--pull ` — Attempt to fix problems by pulling from another repository. Defaults to "origin" + + + +## `spfs-cli-main read` + +Output the contents of a blob to stdout + +**Usage:** `spfs-cli-main read [OPTIONS] [PATH]` + +**Command Aliases:** `read-file`, `cat`, `cat-file` + +###### **Arguments:** + +* `` — The tag or digest of the blob/payload to output +* `` — If the given ref is not a blob, read the blob found at this path + +###### **Options:** + +* `-r`, `--remote ` — Read from a remote repository instead of the local one + + + +## `spfs-cli-main write` + +Store an arbitrary blob of data in spfs + +**Usage:** `spfs-cli-main write [OPTIONS]` + +**Command Alias:** `write-file` + +###### **Options:** + +* `-t`, `--tag ` — A human-readable tag for the generated object + + Can be provided more than once. +* `-r`, `--remote ` — Write to a remote repository instead of the local one +* `-f`, `--file ` — Store the contents of this file instead of reading from stdin + + + +## `spfs-cli-main docs` + +Output the current configuration of spfs + +**Usage:** `spfs-cli-main docs` + + + +
+ + + This document was generated automatically by + clap-markdown. + + From fa2985990c265278f7edb92e3c2e487933fb25b9 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 28 May 2025 07:31:57 -0500 Subject: [PATCH 05/15] Fix markdown file encoding issues where some characters weren't showing correctly Signed-off-by: Bryce Gattis --- docs/spfs/cli/markdown.md | 431 +++++++++++++++++++------------------- 1 file changed, 215 insertions(+), 216 deletions(-) diff --git a/docs/spfs/cli/markdown.md b/docs/spfs/cli/markdown.md index caca8a5e43..3f7b2d9b9b 100644 --- a/docs/spfs/cli/markdown.md +++ b/docs/spfs/cli/markdown.md @@ -9,39 +9,39 @@ This document contains the help content for the `spfs-cli-main` command-line pro **Command Overview:** -* [`spfs-cli-main`Γå┤](#spfs-cli-main) -* [`spfs-cli-main version`Γå┤](#spfs-cli-main-version) -* [`spfs-cli-main init`Γå┤](#spfs-cli-main-init) -* [`spfs-cli-main init repo`Γå┤](#spfs-cli-main-init-repo) -* [`spfs-cli-main edit`Γå┤](#spfs-cli-main-edit) -* [`spfs-cli-main commit`Γå┤](#spfs-cli-main-commit) -* [`spfs-cli-main config`Γå┤](#spfs-cli-main-config) -* [`spfs-cli-main reset`Γå┤](#spfs-cli-main-reset) -* [`spfs-cli-main run`Γå┤](#spfs-cli-main-run) -* [`spfs-cli-main tag`Γå┤](#spfs-cli-main-tag) -* [`spfs-cli-main untag`Γå┤](#spfs-cli-main-untag) -* [`spfs-cli-main shell`Γå┤](#spfs-cli-main-shell) -* [`spfs-cli-main runtime`Γå┤](#spfs-cli-main-runtime) -* [`spfs-cli-main runtime info`Γå┤](#spfs-cli-main-runtime-info) -* [`spfs-cli-main runtime list`Γå┤](#spfs-cli-main-runtime-list) -* [`spfs-cli-main runtime prune`Γå┤](#spfs-cli-main-runtime-prune) -* [`spfs-cli-main runtime remove`Γå┤](#spfs-cli-main-runtime-remove) -* [`spfs-cli-main layers`Γå┤](#spfs-cli-main-layers) -* [`spfs-cli-main platforms`Γå┤](#spfs-cli-main-platforms) -* [`spfs-cli-main tags`Γå┤](#spfs-cli-main-tags) -* [`spfs-cli-main info`Γå┤](#spfs-cli-main-info) -* [`spfs-cli-main pull`Γå┤](#spfs-cli-main-pull) -* [`spfs-cli-main push`Γå┤](#spfs-cli-main-push) -* [`spfs-cli-main log`Γå┤](#spfs-cli-main-log) -* [`spfs-cli-main search`Γå┤](#spfs-cli-main-search) -* [`spfs-cli-main diff`Γå┤](#spfs-cli-main-diff) -* [`spfs-cli-main ls-tags`Γå┤](#spfs-cli-main-ls-tags) -* [`spfs-cli-main ls`Γå┤](#spfs-cli-main-ls) -* [`spfs-cli-main migrate`Γå┤](#spfs-cli-main-migrate) -* [`spfs-cli-main check`Γå┤](#spfs-cli-main-check) -* [`spfs-cli-main read`Γå┤](#spfs-cli-main-read) -* [`spfs-cli-main write`Γå┤](#spfs-cli-main-write) -* [`spfs-cli-main docs`Γå┤](#spfs-cli-main-docs) +* [`spfs-cli-main`↴](#spfs-cli-main) +* [`spfs-cli-main version`↴](#spfs-cli-main-version) +* [`spfs-cli-main init`↴](#spfs-cli-main-init) +* [`spfs-cli-main init repo`↴](#spfs-cli-main-init-repo) +* [`spfs-cli-main edit`↴](#spfs-cli-main-edit) +* [`spfs-cli-main commit`↴](#spfs-cli-main-commit) +* [`spfs-cli-main config`↴](#spfs-cli-main-config) +* [`spfs-cli-main reset`↴](#spfs-cli-main-reset) +* [`spfs-cli-main run`↴](#spfs-cli-main-run) +* [`spfs-cli-main tag`↴](#spfs-cli-main-tag) +* [`spfs-cli-main untag`↴](#spfs-cli-main-untag) +* [`spfs-cli-main shell`↴](#spfs-cli-main-shell) +* [`spfs-cli-main runtime`↴](#spfs-cli-main-runtime) +* [`spfs-cli-main runtime info`↴](#spfs-cli-main-runtime-info) +* [`spfs-cli-main runtime list`↴](#spfs-cli-main-runtime-list) +* [`spfs-cli-main runtime prune`↴](#spfs-cli-main-runtime-prune) +* [`spfs-cli-main runtime remove`↴](#spfs-cli-main-runtime-remove) +* [`spfs-cli-main layers`↴](#spfs-cli-main-layers) +* [`spfs-cli-main platforms`↴](#spfs-cli-main-platforms) +* [`spfs-cli-main tags`↴](#spfs-cli-main-tags) +* [`spfs-cli-main info`↴](#spfs-cli-main-info) +* [`spfs-cli-main pull`↴](#spfs-cli-main-pull) +* [`spfs-cli-main push`↴](#spfs-cli-main-push) +* [`spfs-cli-main log`↴](#spfs-cli-main-log) +* [`spfs-cli-main search`↴](#spfs-cli-main-search) +* [`spfs-cli-main diff`↴](#spfs-cli-main-diff) +* [`spfs-cli-main ls-tags`↴](#spfs-cli-main-ls-tags) +* [`spfs-cli-main ls`↴](#spfs-cli-main-ls) +* [`spfs-cli-main migrate`↴](#spfs-cli-main-migrate) +* [`spfs-cli-main check`↴](#spfs-cli-main-check) +* [`spfs-cli-main read`↴](#spfs-cli-main-read) +* [`spfs-cli-main write`↴](#spfs-cli-main-write) +* [`spfs-cli-main docs`↴](#spfs-cli-main-docs) ## `spfs-cli-main` @@ -55,39 +55,39 @@ EXTERNAL SUBCOMMANDS: ###### **Subcommands:** -* `version` ΓÇö Print the version of spfs -* `init` ΓÇö Create an empty filesystem repository -* `edit` ΓÇö Make the current runtime editable -* `commit` ΓÇö Commit the current runtime state or a directory to storage -* `config` ΓÇö Output the current configuration of spfs -* `reset` ΓÇö Reset changes, or rebuild the entire spfs directory -* `run` ΓÇö Run a program in a configured spfs environment -* `tag` ΓÇö Tag an object -* `untag` ΓÇö Remove tag versions or entire tag streams -* `shell` ΓÇö Enter a subshell in a configured spfs environment -* `runtime` ΓÇö View and manage spfs runtime information -* `layers` ΓÇö List all layers in an spfs repository -* `platforms` ΓÇö List all platforms in an spfs repository -* `tags` ΓÇö List all tags in an spfs repository -* `info` ΓÇö Display information about the current environment, or specific items -* `pull` ΓÇö Pull one or more objects to the local repository -* `push` ΓÇö Push one or more objects to a remote repository -* `log` ΓÇö Log the history of a given tag over time -* `search` ΓÇö Search for available tags by substring -* `diff` ΓÇö Compare two spfs file system states -* `ls-tags` ΓÇö List tags by their path -* `ls` ΓÇö List the contents of a committed directory -* `migrate` ΓÇö Migrate the data from and older repository format to the latest one -* `check` ΓÇö Check a repositories internal integrity -* `read` ΓÇö Output the contents of a blob to stdout -* `write` ΓÇö Store an arbitrary blob of data in spfs -* `docs` ΓÇö Output the current configuration of spfs +* `version` — Print the version of spfs +* `init` — Create an empty filesystem repository +* `edit` — Make the current runtime editable +* `commit` — Commit the current runtime state or a directory to storage +* `config` — Output the current configuration of spfs +* `reset` — Reset changes, or rebuild the entire spfs directory +* `run` — Run a program in a configured spfs environment +* `tag` — Tag an object +* `untag` — Remove tag versions or entire tag streams +* `shell` — Enter a subshell in a configured spfs environment +* `runtime` — View and manage spfs runtime information +* `layers` — List all layers in an spfs repository +* `platforms` — List all platforms in an spfs repository +* `tags` — List all tags in an spfs repository +* `info` — Display information about the current environment, or specific items +* `pull` — Pull one or more objects to the local repository +* `push` — Push one or more objects to a remote repository +* `log` — Log the history of a given tag over time +* `search` — Search for available tags by substring +* `diff` — Compare two spfs file system states +* `ls-tags` — List tags by their path +* `ls` — List the contents of a committed directory +* `migrate` — Migrate the data from and older repository format to the latest one +* `check` — Check a repositories internal integrity +* `read` — Output the contents of a blob to stdout +* `write` — Store an arbitrary blob of data in spfs +* `docs` — Output the current configuration of spfs ###### **Options:** -* `-v`, `--verbose` ΓÇö Make output more verbose, can be specified more than once -* `--log-file ` ΓÇö Additionally log output to the provided file -* `--timestamp` ΓÇö Enables timestamp in logging (always enabled in file log) +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) @@ -107,7 +107,7 @@ Create an empty filesystem repository ###### **Subcommands:** -* `repo` ΓÇö Initialize an empty filesystem repository +* `repo` — Initialize an empty filesystem repository @@ -121,7 +121,7 @@ Does nothing when run on an existing repository ###### **Arguments:** -* `` ΓÇö The root of the new repository +* `` — The root of the new repository @@ -133,8 +133,8 @@ Make the current runtime editable ###### **Options:** -* `--off` ΓÇö Disable edit mode instead -* `--keep-runtime` ΓÇö Change a runtime into a durable runtime, will also make the runtime editable +* `--off` — Disable edit mode instead +* `--keep-runtime` — Change a runtime into a durable runtime, will also make the runtime editable @@ -146,28 +146,28 @@ Commit the current runtime state or a directory to storage ###### **Arguments:** -* `` ΓÇö The desired object type to create, skip this when giving --path or --ref +* `` — The desired object type to create, skip this when giving --path or --ref Possible values: `layer`, `platform` ###### **Options:** -* `-r`, `--remote ` ΓÇö Commit files directly into a remote repository +* `-r`, `--remote ` — Commit files directly into a remote repository The default is to commit to the local repository. This flag is only valid with the --path argument. -* `-t`, `--tag ` ΓÇö A human-readable tag for the generated object +* `-t`, `--tag ` — A human-readable tag for the generated object Can be provided more than once. -* `--path ` ΓÇö Commit this directory instead of the current spfs changes -* `--ref ` ΓÇö Combine existing items into a platform, use a '+' to join multiple -* `--hash-while-committing` ΓÇö Hash the files while committing, rather than before. +* `--path ` — Commit this directory instead of the current spfs changes +* `--ref ` — Combine existing items into a platform, use a '+' to join multiple +* `--hash-while-committing` — Hash the files while committing, rather than before. This option can improve commit times when a large number of the files are both large, and don't already exist in the repository. It may degrade commit times when committing directly to a slow or remote repository. When given, all files are written to the repository even if the payload exists, rather than hashing the file first to determine if it needs to be transferred. -* `--max-concurrent-blobs ` ΓÇö The total number of blobs that can be committed concurrently +* `--max-concurrent-blobs ` — The total number of blobs that can be committed concurrently Default value: `1000` -* `--max-concurrent-branches ` ΓÇö The total number of branches that can be processed concurrently at each level of the rendered file tree. +* `--max-concurrent-branches ` — The total number of branches that can be processed concurrently at each level of the rendered file tree. The number of active trees being processed can grow exponentially by this exponent for each additional level of depth in the rendered file tree. In general, this number should be kept low. @@ -191,24 +191,24 @@ Reset changes, or rebuild the entire spfs directory ###### **Arguments:** -* `` ΓÇö Glob patterns in the spfs dir of files to reset, defaults to everything +* `` — Glob patterns in the spfs dir of files to reset, defaults to everything ###### **Options:** -* `--sync` ΓÇö Sync the latest information for each tag even if it already exists -* `--check` ΓÇö Traverse and check the entire graph, filling in any missing data +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. -* `--resync` ΓÇö Forcefully sync all associated graph data even if it already exists +* `--resync` — Forcefully sync all associated graph data even if it already exists When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. -* `--max-concurrent-manifests ` ΓÇö The total number of manifests that can be synced concurrently +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently Default value: `100` -* `--max-concurrent-payloads ` ΓÇö The total number of file payloads that can be synced concurrently +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently Default value: `100` -* `--progress ` ΓÇö Options for showing progress +* `--progress ` — Options for showing progress Possible values: - `bars`: @@ -216,10 +216,10 @@ Reset changes, or rebuild the entire spfs directory - `none`: Do not show any progress -* `-e`, `--edit` ΓÇö Mount the resulting runtime in edit mode +* `-e`, `--edit` — Mount the resulting runtime in edit mode Default to true if REF is empty or not given -* `-r`, `--ref ` ΓÇö The tag or id to rebuild the runtime with. +* `-r`, `--ref ` — The tag or id to rebuild the runtime with. Uses current runtime stack if not given. Use '-' or an empty string to request an empty environment. Only valid if no paths are given @@ -233,29 +233,29 @@ Run a program in a configured spfs environment ###### **Arguments:** -* `` ΓÇö The tag or id of the desired runtime +* `` — The tag or id of the desired runtime - Use '-' to request an empty environment -* `` ΓÇö The command to run in the environment and its arguments + Use '-' to or an empty string to request an empty environment +* `` — The command to run in the environment and its arguments In order to ensure that flags are passed as-is, '--' must be place before specifying the command and any flags that should be given to that command: e.g. `spfs run -- command --flag-for-command` ###### **Options:** -* `--sync` ΓÇö Sync the latest information for each tag even if it already exists -* `--check` ΓÇö Traverse and check the entire graph, filling in any missing data +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. -* `--resync` ΓÇö Forcefully sync all associated graph data even if it already exists +* `--resync` — Forcefully sync all associated graph data even if it already exists When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. -* `--max-concurrent-manifests ` ΓÇö The total number of manifests that can be synced concurrently +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently Default value: `100` -* `--max-concurrent-payloads ` ΓÇö The total number of file payloads that can be synced concurrently +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently Default value: `100` -* `--progress ` ΓÇö Options for showing progress +* `--progress ` — Options for showing progress Possible values: - `bars`: @@ -263,16 +263,16 @@ Run a program in a configured spfs environment - `none`: Do not show any progress -* `-v`, `--verbose` ΓÇö Make output more verbose, can be specified more than once -* `--log-file ` ΓÇö Additionally log output to the provided file -* `--timestamp` ΓÇö Enables timestamp in logging (always enabled in file log) -* `-e`, `--edit` ΓÇö Mount the spfs filesystem in edit mode (default if REF is empty or not given) -* `--no-edit` ΓÇö Mount the spfs filesystem in read-only mode (default if REF is non-empty) -* `--force` ΓÇö Requires --rerun. Force reset the process fields of the runtime before it is run again -* `-k`, `--keep-runtime` ΓÇö Use to keep the runtime around rather than deleting it when the process exits. This is best used with '--name NAME' to make rerunning the runtime easier at a later time -* `--runtime-name ` ΓÇö Provide a name for this runtime to make it easier to identify -* `--rerun ` ΓÇö Name of an existing durable runtime to reuse for this run -* `--annotation ` ΓÇö Adds annotation key-value string data to the new runtime. +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) +* `-e`, `--edit` — Mount the spfs filesystem in edit mode (default if REF is empty or not given) +* `--no-edit` — Mount the spfs filesystem in read-only mode (default if REF is non-empty) +* `--force` — Requires --rerun. Force reset the process fields of the runtime before it is run again +* `-k`, `--keep-runtime` — Use to keep the runtime around rather than deleting it when the process exits. This is best used with '--name NAME' to make rerunning the runtime easier at a later time +* `--runtime-name ` — Provide a name for this runtime to make it easier to identify +* `--rerun ` — Name of an existing durable runtime to reuse for this run +* `--annotation ` — Adds annotation key-value string data to the new runtime. This allows external processes to store arbitrary data in the runtimes they create. This is most useful with durable runtimes. The data can be retrieved by running `spfs runtime info` or `spfs info` and using the `--get ` or `--get-all` options @@ -281,7 +281,7 @@ Run a program in a configured spfs environment Annotation data can also be given in a json or yaml file, by using the `--annotation-file ` argument. If given, `--annotation` arguments will supersede anything given in annotation files. If the same key is used more than once, the last key-value pair will override the earlier values for the same key. -* `--annotation-file ` ΓÇö Specify annotation key-value data from a json or yaml file (see --annotation) +* `--annotation-file ` — Specify annotation key-value data from a json or yaml file (see --annotation) @@ -293,12 +293,12 @@ Tag an object ###### **Arguments:** -* `` ΓÇö The reference or id of the item to tag -* `` ΓÇö The tag(s) to point to the the given target +* `` — The reference or id of the item to tag +* `` — The tag(s) to point to the the given target ###### **Options:** -* `-r`, `--remote ` ΓÇö Create tags in a remote repository instead of the local one +* `-r`, `--remote ` — Create tags in a remote repository instead of the local one @@ -310,15 +310,15 @@ Remove tag versions or entire tag streams ###### **Arguments:** -* `` ΓÇö The tag to remove +* `` — The tag to remove Unless --all or --latest is provided, this must have an explicit version number (eg: path/name~0) ###### **Options:** -* `-r`, `--remote ` ΓÇö Remove tags in a remote repository instead of the local one -* `--latest` ΓÇö Only remove the latest version of this tag -* `-a`, `--all` ΓÇö Remove all versions of this tag, deleting it completely +* `-r`, `--remote ` — Remove tags in a remote repository instead of the local one +* `--latest` — Only remove the latest version of this tag +* `-a`, `--all` — Remove all versions of this tag, deleting it completely @@ -330,26 +330,26 @@ Enter a subshell in a configured spfs environment ###### **Arguments:** -* `` ΓÇö The tag or id of the desired runtime +* `` — The tag or id of the desired runtime - Use '-' or nothing to request an empty environment + Use '-' or an empty string to request an empty environment ###### **Options:** -* `--sync` ΓÇö Sync the latest information for each tag even if it already exists -* `--check` ΓÇö Traverse and check the entire graph, filling in any missing data +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. -* `--resync` ΓÇö Forcefully sync all associated graph data even if it already exists +* `--resync` — Forcefully sync all associated graph data even if it already exists When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. -* `--max-concurrent-manifests ` ΓÇö The total number of manifests that can be synced concurrently +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently Default value: `100` -* `--max-concurrent-payloads ` ΓÇö The total number of file payloads that can be synced concurrently +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently Default value: `100` -* `--progress ` ΓÇö Options for showing progress +* `--progress ` — Options for showing progress Possible values: - `bars`: @@ -357,16 +357,16 @@ Enter a subshell in a configured spfs environment - `none`: Do not show any progress -* `-v`, `--verbose` ΓÇö Make output more verbose, can be specified more than once -* `--log-file ` ΓÇö Additionally log output to the provided file -* `--timestamp` ΓÇö Enables timestamp in logging (always enabled in file log) -* `-e`, `--edit` ΓÇö Mount the spfs filesystem in edit mode (true if REF is empty or not given) -* `--no-edit` ΓÇö Mount the spfs filesystem in read-only mode (default if REF is non-empty) -* `--rerun ` ΓÇö Name of a previously run durable runtime to reuse for this run -* `--force` ΓÇö Requires --rerun. Force reset the process fields of the runtime before it is run again -* `--runtime-name ` ΓÇö Provide a name for this runtime to make it easier to identify -* `-k`, `--keep-runtime` ΓÇö Use to keep the runtime around rather than deleting it when the process exits. This is best used with '--name NAME' to make rerunning the runtime easier at a later time -* `--annotation ` ΓÇö Adds annotation key-value string data to the new runtime. +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) +* `-e`, `--edit` — Mount the spfs filesystem in edit mode (true if REF is empty or not given) +* `--no-edit` — Mount the spfs filesystem in read-only mode (default if REF is non-empty) +* `--rerun ` — Name of a previously run durable runtime to reuse for this run +* `--force` — Requires --rerun. Force reset the process fields of the runtime before it is run again +* `--runtime-name ` — Provide a name for this runtime to make it easier to identify +* `-k`, `--keep-runtime` — Use to keep the runtime around rather than deleting it when the process exits. This is best used with '--name NAME' to make rerunning the runtime easier at a later time +* `--annotation ` — Adds annotation key-value string data to the new runtime. This allows external processes to store arbitrary data in the runtimes they create. This is most useful with durable runtimes. The data can be retrieved by running `spfs runtime info` or `spfs info` and using the `--get ` or `--get-all` options @@ -375,7 +375,7 @@ Enter a subshell in a configured spfs environment Annotation data can also be given in a json or yaml file, by using the `--annotation-file ` argument. If given, `--annotation` arguments will supersede anything given in annotation files. If the same key is used more than once, the last key-value pair will override the earlier values for the same key. -* `--annotation-file ` ΓÇö Specify annotation key-value data from a json or yaml file (see --annotation) +* `--annotation-file ` — Specify annotation key-value data from a json or yaml file (see --annotation) @@ -389,10 +389,10 @@ View and manage spfs runtime information ###### **Subcommands:** -* `info` ΓÇö Show the complete state of a runtime -* `list` ΓÇö List runtime information from the repository -* `prune` ΓÇö Find and remove runtimes from the repository based on a pruning strategy -* `remove` ΓÇö Remove runtimes from the repository +* `info` — Show the complete state of a runtime +* `list` — List runtime information from the repository +* `prune` — Find and remove runtimes from the repository based on a pruning strategy +* `remove` — Remove runtimes from the repository @@ -404,13 +404,13 @@ Show the complete state of a runtime ###### **Arguments:** -* `` ΓÇö The name/id of the runtime to remove +* `` — The name/id of the runtime to remove ###### **Options:** -* `-r`, `--remote ` ΓÇö Load a runtime in a remote or alternate repository -* `--get ` ΓÇö Output the data value for the given annotation key(s) from the active runtime. Each value is printed on its own line without its key -* `--get-all` ΓÇö Output all the annotation keys and values from the active runtime as a yaml dictionary +* `-r`, `--remote ` — Load a runtime in a remote or alternate repository +* `--get ` — Output the data value for the given annotation key(s) from the active runtime. Each value is printed on its own line without its key +* `--get-all` — Output all the annotation keys and values from the active runtime as a yaml dictionary @@ -424,8 +424,8 @@ List runtime information from the repository ###### **Options:** -* `-r`, `--remote ` ΓÇö List runtimes in a remote or alternate repository -* `-q`, `--quiet` ΓÇö Only print the name of each runtime, no additional data +* `-r`, `--remote ` — List runtimes in a remote or alternate repository +* `-q`, `--quiet` — Only print the name of each runtime, no additional data @@ -437,13 +437,13 @@ Find and remove runtimes from the repository based on a pruning strategy ###### **Options:** -* `-r`, `--remote ` ΓÇö Prune a runtime in a remote or alternate repository -* `--ignore-user` ΓÇö Remove the runtime even if it's owned by someone else -* `--ignore-host` ΓÇö Remove the runtime even if it appears to be from a different host +* `-r`, `--remote ` — Prune a runtime in a remote or alternate repository +* `--ignore-user` — Remove the runtime even if it's owned by someone else +* `--ignore-host` — Remove the runtime even if it appears to be from a different host Implies --ignore-monitor -* `--ignore-monitor` ΓÇö Do not try and terminate the monitor process, just remove runtime data -* `--from-before-boot` ΓÇö Remove runtimes started before last reboot +* `--ignore-monitor` — Do not try and terminate the monitor process, just remove runtime data +* `--from-before-boot` — Remove runtimes started before last reboot @@ -457,20 +457,20 @@ Remove runtimes from the repository ###### **Arguments:** -* `` ΓÇö The name/id of the runtime to remove +* `` — The name/id of the runtime to remove ###### **Options:** -* `-r`, `--remote ` ΓÇö Remove a runtime in a remote or alternate repository -* `-f`, `--force` ΓÇö Remove the runtime from the repository forcefully +* `-r`, `--remote ` — Remove a runtime in a remote or alternate repository +* `-f`, `--force` — Remove the runtime from the repository forcefully Even if the monitor cannot be stopped or killed the data will be removed from the repository. -* `--ignore-user` ΓÇö Remove the runtime even if it's owned by someone else -* `--ignore-host` ΓÇö Remove the runtime even if it appears to be from a different host +* `--ignore-user` — Remove the runtime even if it's owned by someone else +* `--ignore-host` — Remove the runtime even if it appears to be from a different host Implies --ignore-monitor -* `--ignore-monitor` ΓÇö Do not try and terminate the monitor process, just remove runtime data -* `--remove-durable` ΓÇö Allow durable runtimes to be removed, normally they will not be removed +* `--ignore-monitor` — Do not try and terminate the monitor process, just remove runtime data +* `--remove-durable` — Allow durable runtimes to be removed, normally they will not be removed @@ -482,9 +482,9 @@ List all layers in an spfs repository ###### **Options:** -* `-r`, `--remote ` ΓÇö Show layers from remote repository instead of the local one -* `--short` ΓÇö Show the shortened form of each reported layer digest -* `--tags` ΓÇö Also find and report any tags that point to each layer, implies --short +* `-r`, `--remote ` — Show layers from remote repository instead of the local one +* `--short` — Show the shortened form of each reported layer digest +* `--tags` — Also find and report any tags that point to each layer, implies --short @@ -496,9 +496,9 @@ List all platforms in an spfs repository ###### **Options:** -* `-r`, `--remote ` ΓÇö Show layers from remote repository instead of the local one -* `--short` ΓÇö Show the shortened form of each reported layer digest -* `--tags` ΓÇö Also find and report any tags that point to each platform, implies --short +* `-r`, `--remote ` — Show layers from remote repository instead of the local one +* `--short` — Show the shortened form of each reported layer digest +* `--tags` — Also find and report any tags that point to each platform, implies --short @@ -510,9 +510,9 @@ List all tags in an spfs repository ###### **Options:** -* `-r`, `--remote ` ΓÇö Show layers from remote repository instead of the local one -* `--target` ΓÇö Also show the target digest of each tag -* `--short` ΓÇö Show the shortened form of each reported digest, implies --target +* `-r`, `--remote ` — Show layers from remote repository instead of the local one +* `--target` — Also show the target digest of each tag +* `--short` — Show the shortened form of each reported digest, implies --target @@ -524,22 +524,22 @@ Display information about the current environment, or specific items ###### **Arguments:** -* `` ΓÇö Tag, id, or /spfs/file/path to show information about +* `` — Tag, id, or /spfs/file/path to show information about ###### **Options:** -* `-v`, `--verbose` ΓÇö Make output more verbose, can be specified more than once -* `--log-file ` ΓÇö Additionally log output to the provided file -* `--timestamp` ΓÇö Enables timestamp in logging (always enabled in file log) -* `--get ` ΓÇö Output the data value for the given annotation key(s) from the active runtime. Each value is printed on its own line without its key -* `--get-all` ΓÇö Output all the annotation keys and values from the active runtime as a yaml dictionary -* `-H`, `--human-readable` ΓÇö Lists file sizes in human readable format -* `-r`, `--remote ` ΓÇö Operate on a remote repository instead of the local one +* `-v`, `--verbose` — Make output more verbose, can be specified more than once +* `--log-file ` — Additionally log output to the provided file +* `--timestamp` — Enables timestamp in logging (always enabled in file log) +* `--get ` — Output the data value for the given annotation key(s) from the active runtime. Each value is printed on its own line without its key +* `--get-all` — Output all the annotation keys and values from the active runtime as a yaml dictionary +* `-H`, `--human-readable` — Lists file sizes in human readable format +* `-r`, `--remote ` — Operate on a remote repository instead of the local one This is really only helpful if you are providing a specific ref to look up. -* `--tags` ΓÇö Also find and report any tags that point to any identified digest (implies '--short') -* `--short` ΓÇö Use shortened digests in the output (nicer, but slower) -* `--follow` ΓÇö Follow and show child objects, depth-first +* `--tags` — Also find and report any tags that point to any identified digest (implies '--short') +* `--short` — Use shortened digests in the output (nicer, but slower) +* `--follow` — Follow and show child objects, depth-first @@ -551,26 +551,26 @@ Pull one or more objects to the local repository ###### **Arguments:** -* `` ΓÇö The reference(s) to pull/localize +* `` — The reference(s) to pull/localize These can be individual tags or digests, or they may also be a collection of items joined by a '+' ###### **Options:** -* `--sync` ΓÇö Sync the latest information for each tag even if it already exists -* `--check` ΓÇö Traverse and check the entire graph, filling in any missing data +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. -* `--resync` ΓÇö Forcefully sync all associated graph data even if it already exists +* `--resync` — Forcefully sync all associated graph data even if it already exists When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. -* `--max-concurrent-manifests ` ΓÇö The total number of manifests that can be synced concurrently +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently Default value: `100` -* `--max-concurrent-payloads ` ΓÇö The total number of file payloads that can be synced concurrently +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently Default value: `100` -* `--progress ` ΓÇö Options for showing progress +* `--progress ` — Options for showing progress Possible values: - `bars`: @@ -579,7 +579,7 @@ Pull one or more objects to the local repository Do not show any progress * `-v`, `--verbose` -* `-r`, `--remote ` ΓÇö The name or address of the remote server to pull from +* `-r`, `--remote ` — The name or address of the remote server to pull from Defaults to searching all configured remotes @@ -593,26 +593,26 @@ Push one or more objects to a remote repository ###### **Arguments:** -* `` ΓÇö The reference(s) to push +* `` — The reference(s) to push These can be individual tags or digests, or they may also be a collection of items joined by a '+' ###### **Options:** -* `--sync` ΓÇö Sync the latest information for each tag even if it already exists -* `--check` ΓÇö Traverse and check the entire graph, filling in any missing data +* `--sync` — Sync the latest information for each tag even if it already exists +* `--check` — Traverse and check the entire graph, filling in any missing data When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted or lost, this option may help recover it. -* `--resync` ΓÇö Forcefully sync all associated graph data even if it already exists +* `--resync` — Forcefully sync all associated graph data even if it already exists When a repository is in good health, this should not be necessary, but if some subset of the data has been deleted, lost, or corrupted this option may help recover it. -* `--max-concurrent-manifests ` ΓÇö The total number of manifests that can be synced concurrently +* `--max-concurrent-manifests ` — The total number of manifests that can be synced concurrently Default value: `100` -* `--max-concurrent-payloads ` ΓÇö The total number of file payloads that can be synced concurrently +* `--max-concurrent-payloads ` — The total number of file payloads that can be synced concurrently Default value: `100` -* `--progress ` ΓÇö Options for showing progress +* `--progress ` — Options for showing progress Possible values: - `bars`: @@ -621,7 +621,7 @@ Push one or more objects to a remote repository Do not show any progress * `-v`, `--verbose` -* `-r`, `--remote ` ΓÇö The name or address of the remote server to push to +* `-r`, `--remote ` — The name or address of the remote server to push to Default value: `origin` @@ -635,11 +635,11 @@ Log the history of a given tag over time ###### **Arguments:** -* `` ΓÇö The tag to show history of +* `` — The tag to show history of ###### **Options:** -* `-r`, `--remote ` ΓÇö Load the tag from remote repository instead of the local one +* `-r`, `--remote ` — Load the tag from remote repository instead of the local one @@ -651,7 +651,7 @@ Search for available tags by substring ###### **Arguments:** -* `` ΓÇö The search term/substring to look for +* `` — The search term/substring to look for @@ -663,8 +663,8 @@ Compare two spfs file system states ###### **Arguments:** -* `` ΓÇö The tag or id to use as the base of the computed diff, defaults to the current runtime -* `` ΓÇö The tag or id to diff the base against, defaults to the contents of the spfs filesystem +* `` — The tag or id to use as the base of the computed diff, defaults to the current runtime +* `` — The tag or id to diff the base against, defaults to the contents of the spfs filesystem @@ -678,14 +678,14 @@ List tags by their path ###### **Arguments:** -* `` ΓÇö The tag path to list under +* `` — The tag path to list under Default value: `/` ###### **Options:** -* `-r`, `--remote ` ΓÇö List tags from a remote repository instead of the local one -* `--recursive` ΓÇö Walk the tag tree recursively listing all tags under the specified dir +* `-r`, `--remote ` — List tags from a remote repository instead of the local one +* `--recursive` — Walk the tag tree recursively listing all tags under the specified dir @@ -699,17 +699,17 @@ List the contents of a committed directory ###### **Arguments:** -* `` ΓÇö The tag or digest of the file tree to read from -* `` ΓÇö The subdirectory to list +* `` — The tag or digest of the file tree to read from +* `` — The subdirectory to list Default value: `/spfs` ###### **Options:** -* `-r`, `--remote ` ΓÇö List files on a remote repository instead of the local one -* `-R`, `--recursive` ΓÇö Recursively list all files and directories -* `-l` ΓÇö Long listing format -* `-H`, `--human-readable` ΓÇö Lists file sizes in human readable format +* `-r`, `--remote ` — List files on a remote repository instead of the local one +* `-R`, `--recursive` — Recursively list all files and directories +* `-l` — Long listing format +* `-H`, `--human-readable` — Lists file sizes in human readable format @@ -721,11 +721,11 @@ Migrate the data from and older repository format to the latest one ###### **Arguments:** -* `` ΓÇö The path to the filesystem repository to migrate +* `` — The path to the filesystem repository to migrate ###### **Options:** -* `--upgrade` ΓÇö Replace old data with migrated data one complete +* `--upgrade` — Replace old data with migrated data one complete @@ -737,18 +737,18 @@ Check a repositories internal integrity ###### **Arguments:** -* `` ΓÇö Objects to recursively check, defaults to everything +* `` — Objects to recursively check, defaults to everything ###### **Options:** -* `-r`, `--remote ` ΓÇö Trigger the check operation on a remote repository instead of the local one -* `--max-tag-stream-concurrency ` ΓÇö The maximum number of tag streams that can be read and processed at once +* `-r`, `--remote ` — Trigger the check operation on a remote repository instead of the local one +* `--max-tag-stream-concurrency ` — The maximum number of tag streams that can be read and processed at once Default value: `1000` -* `--max-object-concurrency ` ΓÇö The maximum number of objects that can be validated at once +* `--max-object-concurrency ` — The maximum number of objects that can be validated at once Default value: `5000` -* `--pull ` ΓÇö Attempt to fix problems by pulling from another repository. Defaults to "origin" +* `--pull ` — Attempt to fix problems by pulling from another repository. Defaults to "origin" @@ -762,12 +762,12 @@ Output the contents of a blob to stdout ###### **Arguments:** -* `` ΓÇö The tag or digest of the blob/payload to output -* `` ΓÇö If the given ref is not a blob, read the blob found at this path +* `` — The tag or digest of the blob/payload to output +* `` — If the given ref is not a blob, read the blob found at this path ###### **Options:** -* `-r`, `--remote ` ΓÇö Read from a remote repository instead of the local one +* `-r`, `--remote ` — Read from a remote repository instead of the local one @@ -781,11 +781,11 @@ Store an arbitrary blob of data in spfs ###### **Options:** -* `-t`, `--tag ` ΓÇö A human-readable tag for the generated object +* `-t`, `--tag ` — A human-readable tag for the generated object Can be provided more than once. -* `-r`, `--remote ` ΓÇö Write to a remote repository instead of the local one -* `-f`, `--file ` ΓÇö Store the contents of this file instead of reading from stdin +* `-r`, `--remote ` — Write to a remote repository instead of the local one +* `-f`, `--file ` — Store the contents of this file instead of reading from stdin @@ -803,4 +803,3 @@ Output the current configuration of spfs This document was generated automatically by clap-markdown. - From d22ee9816ccaec3b8ad4b7e275b382f4a5d1662d Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 28 May 2025 07:32:37 -0500 Subject: [PATCH 06/15] Update cmd docs so we don't have to pipe output manually in the shell command we call Signed-off-by: Bryce Gattis --- crates/spfs-cli/main/src/cmd_docs.rs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/main/src/cmd_docs.rs index 6c130b231d..b6cfcbce15 100644 --- a/crates/spfs-cli/main/src/cmd_docs.rs +++ b/crates/spfs-cli/main/src/cmd_docs.rs @@ -1,6 +1,7 @@ // Copyright (c) Contributors to the SPK project. // SPDX-License-Identifier: Apache-2.0 // https://github.com/spkenv/spk +use std::fs; use clap::Args; use miette::{IntoDiagnostic, Result}; @@ -11,7 +12,14 @@ pub struct CmdDocs {} impl CmdDocs { pub async fn run(&mut self, config: &spfs::Config) -> Result { - clap_markdown::print_help_markdown::(); + let mut markdown = clap_markdown::help_markdown::(); + markdown.insert_str(0, "\n"); + markdown.insert_str(0, "---\n"); + markdown.insert_str(0, "chapter: true\n"); + markdown.insert_str(0, "title: SPFS CLI\n"); + markdown.insert_str(0, "---\n"); + // This path is relative to the current shell directory. + fs::write("docs/spfs/cli/markdown.md", markdown).expect("Unable to write file"); Ok(0) } } From fdff99560863dc48b264a0b44e230c566aaae205 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 28 May 2025 08:00:49 -0500 Subject: [PATCH 07/15] Fix lint issue Signed-off-by: Bryce Gattis --- crates/spfs-cli/main/src/bin.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/spfs-cli/main/src/bin.rs b/crates/spfs-cli/main/src/bin.rs index b397517108..8d17f81c62 100644 --- a/crates/spfs-cli/main/src/bin.rs +++ b/crates/spfs-cli/main/src/bin.rs @@ -10,6 +10,7 @@ mod cmd_check; mod cmd_commit; mod cmd_config; mod cmd_diff; +mod cmd_docs; mod cmd_edit; mod cmd_info; mod cmd_init; @@ -38,7 +39,6 @@ mod cmd_tags; mod cmd_untag; mod cmd_version; mod cmd_write; -mod cmd_docs; use spfs_cli_common as cli; use spfs_cli_common::CommandName; From 040406f1804f73cd8e359cc92842425014809303 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 28 May 2025 08:09:18 -0500 Subject: [PATCH 08/15] More lint cleanup Signed-off-by: Bryce Gattis --- crates/spfs-cli/main/src/cmd_docs.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/main/src/cmd_docs.rs index b6cfcbce15..65bcf29fe6 100644 --- a/crates/spfs-cli/main/src/cmd_docs.rs +++ b/crates/spfs-cli/main/src/cmd_docs.rs @@ -4,16 +4,16 @@ use std::fs; use clap::Args; -use miette::{IntoDiagnostic, Result}; +use miette::{Result}; /// Output the current configuration of spfs #[derive(Debug, Args)] pub struct CmdDocs {} impl CmdDocs { - pub async fn run(&mut self, config: &spfs::Config) -> Result { + pub async fn run(&mut self, _config: &spfs::Config) -> Result { let mut markdown = clap_markdown::help_markdown::(); - markdown.insert_str(0, "\n"); + markdown.insert(0, '\n'); markdown.insert_str(0, "---\n"); markdown.insert_str(0, "chapter: true\n"); markdown.insert_str(0, "title: SPFS CLI\n"); From fd05a3b6403aabdd8268aa0abd873604bf2615da Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 28 May 2025 08:24:44 -0500 Subject: [PATCH 09/15] Lint Signed-off-by: Bryce Gattis --- crates/spfs-cli/main/src/cmd_docs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/main/src/cmd_docs.rs index 65bcf29fe6..6212ae1532 100644 --- a/crates/spfs-cli/main/src/cmd_docs.rs +++ b/crates/spfs-cli/main/src/cmd_docs.rs @@ -4,7 +4,7 @@ use std::fs; use clap::Args; -use miette::{Result}; +use miette::Result; /// Output the current configuration of spfs #[derive(Debug, Args)] From 5ed5ffc68d2a2c8d3e8446d07a321cb5a137b260 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Wed, 28 May 2025 08:36:01 -0500 Subject: [PATCH 10/15] Update docstring for CmdDocs Signed-off-by: Bryce Gattis --- crates/spfs-cli/main/src/cmd_docs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/main/src/cmd_docs.rs index 6212ae1532..126fbf41fe 100644 --- a/crates/spfs-cli/main/src/cmd_docs.rs +++ b/crates/spfs-cli/main/src/cmd_docs.rs @@ -6,7 +6,7 @@ use std::fs; use clap::Args; use miette::Result; -/// Output the current configuration of spfs +/// Write Markdown documentation for all SPFS subcommands to docs folder. #[derive(Debug, Args)] pub struct CmdDocs {} From 8cdf465b28739b32b8ee11839be02b7e474960a6 Mon Sep 17 00:00:00 2001 From: BryceGattis Date: Tue, 3 Jun 2025 11:48:43 -0500 Subject: [PATCH 11/15] Got spfs-cli-main package working with a library target so it can be used outside of its own package Signed-off-by: BryceGattis --- crates/spfs-cli/main/Cargo.toml | 4 + crates/spfs-cli/main/src/bin.rs | 178 +------------------------- crates/spfs-cli/main/src/bin_utils.rs | 171 +++++++++++++++++++++++++ crates/spfs-cli/main/src/cmd_docs.rs | 4 +- crates/spfs-cli/main/src/lib.rs | 38 ++++++ 5 files changed, 219 insertions(+), 176 deletions(-) create mode 100644 crates/spfs-cli/main/src/bin_utils.rs create mode 100644 crates/spfs-cli/main/src/lib.rs diff --git a/crates/spfs-cli/main/Cargo.toml b/crates/spfs-cli/main/Cargo.toml index 7bc4a51338..a5387d1d78 100644 --- a/crates/spfs-cli/main/Cargo.toml +++ b/crates/spfs-cli/main/Cargo.toml @@ -17,6 +17,10 @@ workspace = true name = "spfs" path = "src/bin.rs" +[lib] +name = "spfs_cli_main" +path = "src/lib.rs" + [features] fuse = ["spfs/fuse-backend"] sentry = ["spfs-cli-common/sentry"] diff --git a/crates/spfs-cli/main/src/bin.rs b/crates/spfs-cli/main/src/bin.rs index 8d17f81c62..009c59db0c 100644 --- a/crates/spfs-cli/main/src/bin.rs +++ b/crates/spfs-cli/main/src/bin.rs @@ -2,182 +2,10 @@ // SPDX-License-Identifier: Apache-2.0 // https://github.com/spkenv/spk -use clap::{Parser, Subcommand}; -use miette::Result; -use spfs::{Error, OsErrorExt}; - -mod cmd_check; -mod cmd_commit; -mod cmd_config; -mod cmd_diff; -mod cmd_docs; -mod cmd_edit; -mod cmd_info; -mod cmd_init; -mod cmd_layers; -mod cmd_log; -mod cmd_ls; -mod cmd_ls_tags; -mod cmd_migrate; -mod cmd_platforms; -mod cmd_pull; -mod cmd_push; -mod cmd_read; -mod cmd_reset; -mod cmd_run; -mod cmd_runtime; -mod cmd_runtime_info; -mod cmd_runtime_list; -mod cmd_runtime_prune; -mod cmd_runtime_remove; -mod cmd_search; -#[cfg(feature = "server")] -mod cmd_server; -mod cmd_shell; -mod cmd_tag; -mod cmd_tags; -mod cmd_untag; -mod cmd_version; -mod cmd_write; +use clap::{Parser}; use spfs_cli_common as cli; -use spfs_cli_common::CommandName; - -cli::main!(Opt); - -/// Filesystem isolation, capture and distribution. -#[derive(Debug, Parser)] -#[clap( - about, - after_help = "EXTERNAL SUBCOMMANDS:\ - \n render render the contents of an environment or layer\ - \n monitor watch a runtime and clean it up when complete\ - " -)] -pub struct Opt { - #[clap(flatten)] - pub logging: cli::Logging, - #[clap(subcommand)] - pub cmd: Command, -} - -#[derive(strum::AsRefStr, Debug, Subcommand)] -#[strum(serialize_all = "lowercase")] -#[clap(trailing_var_arg = true, dont_delimit_trailing_values = true)] -pub enum Command { - Version(cmd_version::CmdVersion), - Init(cmd_init::CmdInit), - Edit(cmd_edit::CmdEdit), - Commit(cmd_commit::CmdCommit), - Config(cmd_config::CmdConfig), - Reset(cmd_reset::CmdReset), - Run(cmd_run::CmdRun), - Tag(cmd_tag::CmdTag), - Untag(cmd_untag::CmdUntag), - Shell(cmd_shell::CmdShell), - Runtime(cmd_runtime::CmdRuntime), - Layers(cmd_layers::CmdLayers), - Platforms(cmd_platforms::CmdPlatforms), - Tags(cmd_tags::CmdTags), - Info(cmd_info::CmdInfo), - Pull(cmd_pull::CmdPull), - Push(cmd_push::CmdPush), - Log(cmd_log::CmdLog), - Search(cmd_search::CmdSearch), - Diff(cmd_diff::CmdDiff), - LsTags(cmd_ls_tags::CmdLsTags), - Ls(cmd_ls::CmdLs), - Migrate(cmd_migrate::CmdMigrate), - Check(cmd_check::CmdCheck), - Read(cmd_read::CmdRead), - Write(cmd_write::CmdWrite), - Docs(cmd_docs::CmdDocs), - - #[cfg(feature = "server")] - Server(cmd_server::CmdServer), - #[clap(external_subcommand)] - External(Vec), -} +use spfs_cli_main::bin_utils::Opt; -impl CommandName for Opt { - fn command_name(&self) -> &str { - self.cmd.as_ref() - } -} - -impl Opt { - async fn run(&mut self, config: &spfs::Config) -> Result { - match &mut self.cmd { - Command::Version(cmd) => cmd.run().await, - Command::Edit(cmd) => cmd.run(config).await, - Command::Init(cmd) => cmd.run(config).await, - Command::Commit(cmd) => cmd.run(config).await, - Command::Config(cmd) => cmd.run(config).await, - Command::Reset(cmd) => cmd.run(config).await, - Command::Tag(cmd) => cmd.run(config).await, - Command::Untag(cmd) => cmd.run(config).await, - Command::Runtime(cmd) => cmd.run(config).await, - Command::Layers(cmd) => cmd.run(config).await, - Command::Platforms(cmd) => cmd.run(config).await, - Command::Tags(cmd) => cmd.run(config).await, - Command::Info(cmd) => cmd.run(config).await, - Command::Log(cmd) => cmd.run(config).await, - Command::Search(cmd) => cmd.run(config).await, - Command::Diff(cmd) => cmd.run(config).await, - Command::LsTags(cmd) => cmd.run(config).await, - Command::Ls(cmd) => cmd.run(config).await, - Command::Migrate(cmd) => cmd.run(config).await, - Command::Check(cmd) => cmd.run(config).await, - Command::Read(cmd) => cmd.run(config).await, - Command::Write(cmd) => cmd.run(config).await, - Command::Run(cmd) => cmd.run(config).await, - Command::Shell(cmd) => cmd.run(config).await, - Command::Pull(cmd) => cmd.run(config).await, - Command::Push(cmd) => cmd.run(config).await, - Command::Docs(cmd) => cmd.run(config).await, - #[cfg(feature = "server")] - Command::Server(cmd) => cmd.run(config).await, - Command::External(args) => run_external_subcommand(args.clone()).await, - } - } -} - -async fn run_external_subcommand(args: Vec) -> Result { - { - let mut args = args.into_iter(); - let command = match args.next() { - None => { - tracing::error!("Invalid subcommand, cannot be empty"); - return Ok(1); - } - Some(c) => c, - }; - - // either in the PATH or next to the current binary - let cmd_path = match spfs::which_spfs(&command) { - Some(cmd) => cmd, - None => { - let mut p = std::env::current_exe() - .map_err(|err| Error::process_spawn_error("current_exe()", err, None))?; - p.set_file_name(&command); - p - } - }; - - let cmd = spfs::bootstrap::Command { - executable: cmd_path.into(), - args: args.map(Into::into).collect(), - vars: Vec::new(), - }; - - match cmd.exec() { - Ok(o) => match o {}, - Err(err) if err.is_os_not_found() => { - tracing::error!("{command} not found in PATH, was it properly installed?") - } - Err(err) => tracing::error!("subcommand failed: {err:?}"), - } - Ok(1) - } -} +cli::main!(Opt); diff --git a/crates/spfs-cli/main/src/bin_utils.rs b/crates/spfs-cli/main/src/bin_utils.rs new file mode 100644 index 0000000000..57cf39cb24 --- /dev/null +++ b/crates/spfs-cli/main/src/bin_utils.rs @@ -0,0 +1,171 @@ +use clap::{Parser, Subcommand}; + +use spfs::{Error, OsErrorExt}; +use spfs_cli_common as cli; +use spfs_cli_common::CommandName; +use crate::{ + cmd_check, + cmd_config, + cmd_commit, + cmd_docs, + cmd_diff, + cmd_edit, + cmd_info, + cmd_init, + cmd_layers, + cmd_log, + cmd_ls, + cmd_ls_tags, + cmd_migrate, + cmd_platforms, + cmd_pull, + cmd_push, + cmd_read, + cmd_reset, + cmd_run, + cmd_runtime, + cmd_search, + cmd_shell, + cmd_tag, + cmd_tags, + cmd_version, + cmd_untag, + cmd_write +}; + +/// Filesystem isolation, capture and distribution. +#[derive(Debug, Parser)] +#[clap( + about, + after_help = "EXTERNAL SUBCOMMANDS:\ + \n render render the contents of an environment or layer\ + \n monitor watch a runtime and clean it up when complete\ + " +)] +pub struct Opt { + #[clap(flatten)] + pub logging: cli::Logging, + #[clap(subcommand)] + pub cmd: Command, +} + +#[derive(strum::AsRefStr, Debug, Subcommand)] +#[strum(serialize_all = "lowercase")] +#[clap(trailing_var_arg = true, dont_delimit_trailing_values = true)] +pub enum Command { + Version(cmd_version::CmdVersion), + Init(cmd_init::CmdInit), + Edit(cmd_edit::CmdEdit), + Commit(cmd_commit::CmdCommit), + Config(cmd_config::CmdConfig), + Reset(cmd_reset::CmdReset), + Run(cmd_run::CmdRun), + Tag(cmd_tag::CmdTag), + Untag(cmd_untag::CmdUntag), + Shell(cmd_shell::CmdShell), + Runtime(cmd_runtime::CmdRuntime), + Layers(cmd_layers::CmdLayers), + Platforms(cmd_platforms::CmdPlatforms), + Tags(cmd_tags::CmdTags), + Info(cmd_info::CmdInfo), + Pull(cmd_pull::CmdPull), + Push(cmd_push::CmdPush), + Log(cmd_log::CmdLog), + Search(cmd_search::CmdSearch), + Diff(cmd_diff::CmdDiff), + LsTags(cmd_ls_tags::CmdLsTags), + Ls(cmd_ls::CmdLs), + Migrate(cmd_migrate::CmdMigrate), + Check(cmd_check::CmdCheck), + Read(cmd_read::CmdRead), + Write(cmd_write::CmdWrite), + Docs(cmd_docs::CmdDocs), + + #[cfg(feature = "server")] + Server(crate::cmd_server::CmdServer), + + #[clap(external_subcommand)] + External(Vec), +} + +impl CommandName for Opt { + fn command_name(&self) -> &str { + self.cmd.as_ref() + } +} + +impl Opt { + pub async fn run(&mut self, config: &spfs::Config) -> miette::Result { + match &mut self.cmd { + Command::Version(cmd) => cmd.run().await, + Command::Edit(cmd) => cmd.run(config).await, + Command::Init(cmd) => cmd.run(config).await, + Command::Commit(cmd) => cmd.run(config).await, + Command::Config(cmd) => cmd.run(config).await, + Command::Reset(cmd) => cmd.run(config).await, + Command::Tag(cmd) => cmd.run(config).await, + Command::Untag(cmd) => cmd.run(config).await, + Command::Runtime(cmd) => cmd.run(config).await, + Command::Layers(cmd) => cmd.run(config).await, + Command::Platforms(cmd) => cmd.run(config).await, + Command::Tags(cmd) => cmd.run(config).await, + Command::Info(cmd) => cmd.run(config).await, + Command::Log(cmd) => cmd.run(config).await, + Command::Search(cmd) => cmd.run(config).await, + Command::Diff(cmd) => cmd.run(config).await, + Command::LsTags(cmd) => cmd.run(config).await, + Command::Ls(cmd) => cmd.run(config).await, + Command::Migrate(cmd) => cmd.run(config).await, + Command::Check(cmd) => cmd.run(config).await, + Command::Read(cmd) => cmd.run(config).await, + Command::Write(cmd) => cmd.run(config).await, + Command::Run(cmd) => cmd.run(config).await, + Command::Shell(cmd) => cmd.run(config).await, + Command::Pull(cmd) => cmd.run(config).await, + Command::Push(cmd) => cmd.run(config).await, + Command::Docs(cmd) => cmd.run(config).await, + #[cfg(feature = "server")] + Command::Server(cmd) => cmd.run(config).await, + Command::External(args) => run_external_subcommand(args.clone()).await, + } + } +} + +async fn run_external_subcommand(args: Vec) -> miette::Result { + { + let mut args = args.into_iter(); + let command = match args.next() { + None => { + tracing::error!("Invalid subcommand, cannot be empty"); + return Ok(1); + } + Some(c) => c, + }; + + // either in the PATH or next to the current binary + let cmd_path = match spfs::which_spfs(&command) { + Some(cmd) => cmd, + None => { + let mut p = std::env::current_exe() + .map_err(|err| Error::process_spawn_error("current_exe()", err, None))?; + p.set_file_name(&command); + p + } + }; + + let cmd = spfs::bootstrap::Command { + executable: cmd_path.into(), + args: args.map(Into::into).collect(), + vars: Vec::new(), + }; + + match cmd.exec() { + Ok(o) => match o {}, + Err(err) if err.is_os_not_found() => { + tracing::error!("{command} not found in PATH, was it properly installed?") + } + Err(err) => tracing::error!("subcommand failed: {err:?}"), + } + Ok(1) + } +} \ No newline at end of file diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/main/src/cmd_docs.rs index 126fbf41fe..7ab1dea12b 100644 --- a/crates/spfs-cli/main/src/cmd_docs.rs +++ b/crates/spfs-cli/main/src/cmd_docs.rs @@ -6,13 +6,15 @@ use std::fs; use clap::Args; use miette::Result; +use crate::bin_utils::Opt; + /// Write Markdown documentation for all SPFS subcommands to docs folder. #[derive(Debug, Args)] pub struct CmdDocs {} impl CmdDocs { pub async fn run(&mut self, _config: &spfs::Config) -> Result { - let mut markdown = clap_markdown::help_markdown::(); + let mut markdown = clap_markdown::help_markdown::(); markdown.insert(0, '\n'); markdown.insert_str(0, "---\n"); markdown.insert_str(0, "chapter: true\n"); diff --git a/crates/spfs-cli/main/src/lib.rs b/crates/spfs-cli/main/src/lib.rs new file mode 100644 index 0000000000..e4b944be8d --- /dev/null +++ b/crates/spfs-cli/main/src/lib.rs @@ -0,0 +1,38 @@ +// Copyright (c) Contributors to the SPK project. +// SPDX-License-Identifier: Apache-2.0 +// https://github.com/spkenv/spk + +pub mod bin_utils; +mod cmd_check; +mod cmd_commit; +mod cmd_config; +mod cmd_diff; +mod cmd_docs; +mod cmd_edit; +mod cmd_info; +mod cmd_init; +mod cmd_layers; +mod cmd_log; +mod cmd_ls; +mod cmd_ls_tags; +mod cmd_migrate; +mod cmd_platforms; +mod cmd_pull; +mod cmd_push; +mod cmd_read; +mod cmd_reset; +mod cmd_run; +mod cmd_runtime; +mod cmd_runtime_info; +mod cmd_runtime_list; +mod cmd_runtime_prune; +mod cmd_runtime_remove; +mod cmd_search; +#[cfg(feature = "server")] +mod cmd_server; +mod cmd_shell; +mod cmd_tag; +mod cmd_tags; +mod cmd_untag; +mod cmd_version; +mod cmd_write; \ No newline at end of file From 8db83eb81c92b5927aa24891066c30ce57f3a554 Mon Sep 17 00:00:00 2001 From: BryceGattis Date: Tue, 3 Jun 2025 12:03:16 -0500 Subject: [PATCH 12/15] Lint cleanup Signed-off-by: BryceGattis --- crates/spfs-cli/main/src/bin.rs | 4 +--- crates/spfs-cli/main/src/bin_utils.rs | 12 ++++++------ crates/spfs-cli/main/src/lib.rs | 2 +- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/crates/spfs-cli/main/src/bin.rs b/crates/spfs-cli/main/src/bin.rs index 009c59db0c..c7c10e9569 100644 --- a/crates/spfs-cli/main/src/bin.rs +++ b/crates/spfs-cli/main/src/bin.rs @@ -2,10 +2,8 @@ // SPDX-License-Identifier: Apache-2.0 // https://github.com/spkenv/spk -use clap::{Parser}; - +use clap::Parser; use spfs_cli_common as cli; - use spfs_cli_main::bin_utils::Opt; cli::main!(Opt); diff --git a/crates/spfs-cli/main/src/bin_utils.rs b/crates/spfs-cli/main/src/bin_utils.rs index 57cf39cb24..b6990655f8 100644 --- a/crates/spfs-cli/main/src/bin_utils.rs +++ b/crates/spfs-cli/main/src/bin_utils.rs @@ -1,14 +1,14 @@ use clap::{Parser, Subcommand}; - use spfs::{Error, OsErrorExt}; use spfs_cli_common as cli; use spfs_cli_common::CommandName; + use crate::{ cmd_check, - cmd_config, cmd_commit, - cmd_docs, + cmd_config, cmd_diff, + cmd_docs, cmd_edit, cmd_info, cmd_init, @@ -28,9 +28,9 @@ use crate::{ cmd_shell, cmd_tag, cmd_tags, - cmd_version, cmd_untag, - cmd_write + cmd_version, + cmd_write, }; /// Filesystem isolation, capture and distribution. @@ -168,4 +168,4 @@ async fn run_external_subcommand(args: Vec) -> miette::Result { } Ok(1) } -} \ No newline at end of file +} diff --git a/crates/spfs-cli/main/src/lib.rs b/crates/spfs-cli/main/src/lib.rs index e4b944be8d..365631efdc 100644 --- a/crates/spfs-cli/main/src/lib.rs +++ b/crates/spfs-cli/main/src/lib.rs @@ -35,4 +35,4 @@ mod cmd_tag; mod cmd_tags; mod cmd_untag; mod cmd_version; -mod cmd_write; \ No newline at end of file +mod cmd_write; From 7b476c15e2eed711ce4251744c5acd7f7bac2aa1 Mon Sep 17 00:00:00 2001 From: BryceGattis Date: Sat, 7 Jun 2025 11:33:08 -0500 Subject: [PATCH 13/15] Rename bin_utils to cmd_spfs Signed-off-by: BryceGattis --- crates/spfs-cli/main/src/bin.rs | 2 +- crates/spfs-cli/main/src/cmd_docs.rs | 2 +- crates/spfs-cli/main/src/{bin_utils.rs => cmd_spfs.rs} | 0 crates/spfs-cli/main/src/lib.rs | 2 +- 4 files changed, 3 insertions(+), 3 deletions(-) rename crates/spfs-cli/main/src/{bin_utils.rs => cmd_spfs.rs} (100%) diff --git a/crates/spfs-cli/main/src/bin.rs b/crates/spfs-cli/main/src/bin.rs index c7c10e9569..30ecad3286 100644 --- a/crates/spfs-cli/main/src/bin.rs +++ b/crates/spfs-cli/main/src/bin.rs @@ -4,6 +4,6 @@ use clap::Parser; use spfs_cli_common as cli; -use spfs_cli_main::bin_utils::Opt; +use spfs_cli_main::cmd_spfs::Opt; cli::main!(Opt); diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/main/src/cmd_docs.rs index 7ab1dea12b..5f1ceeb9b3 100644 --- a/crates/spfs-cli/main/src/cmd_docs.rs +++ b/crates/spfs-cli/main/src/cmd_docs.rs @@ -6,7 +6,7 @@ use std::fs; use clap::Args; use miette::Result; -use crate::bin_utils::Opt; +use crate::cmd_spfs::Opt; /// Write Markdown documentation for all SPFS subcommands to docs folder. #[derive(Debug, Args)] diff --git a/crates/spfs-cli/main/src/bin_utils.rs b/crates/spfs-cli/main/src/cmd_spfs.rs similarity index 100% rename from crates/spfs-cli/main/src/bin_utils.rs rename to crates/spfs-cli/main/src/cmd_spfs.rs diff --git a/crates/spfs-cli/main/src/lib.rs b/crates/spfs-cli/main/src/lib.rs index 365631efdc..9ed98e6717 100644 --- a/crates/spfs-cli/main/src/lib.rs +++ b/crates/spfs-cli/main/src/lib.rs @@ -2,7 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 // https://github.com/spkenv/spk -pub mod bin_utils; +pub mod cmd_spfs; mod cmd_check; mod cmd_commit; mod cmd_config; From 1ba57f18650df1c336ac523f92ee3b33740cca7b Mon Sep 17 00:00:00 2001 From: BryceGattis Date: Sat, 7 Jun 2025 11:52:44 -0500 Subject: [PATCH 14/15] Make spfs docs a separate command entry point Signed-off-by: BryceGattis --- Cargo.toml | 1 + crates/spfs-cli/cmd-docs/Cargo.toml | 34 +++++++++++++++++++ .../{main => cmd-docs}/src/cmd_docs.rs | 16 ++++++--- crates/spfs-cli/main/Cargo.toml | 1 - crates/spfs-cli/main/src/cmd_spfs.rs | 3 -- crates/spfs-cli/main/src/lib.rs | 1 - docs/spfs/cli/markdown.md | 10 ------ 7 files changed, 47 insertions(+), 19 deletions(-) create mode 100644 crates/spfs-cli/cmd-docs/Cargo.toml rename crates/spfs-cli/{main => cmd-docs}/src/cmd_docs.rs (77%) diff --git a/Cargo.toml b/Cargo.toml index 857c964314..835aab42fa 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -108,6 +108,7 @@ shellexpand = "3.1.0" spdx = "0.10" spfs = { path = "crates/spfs" } spfs-cli-common = { path = "crates/spfs-cli/common" } +spfs-cli-main = { path = "crates/spfs-cli/main" } spfs-encoding = { path = "crates/spfs-encoding" } spfs-vfs = { path = "crates/spfs-vfs" } spk-build = { path = "crates/spk-build" } diff --git a/crates/spfs-cli/cmd-docs/Cargo.toml b/crates/spfs-cli/cmd-docs/Cargo.toml new file mode 100644 index 0000000000..761b6bb867 --- /dev/null +++ b/crates/spfs-cli/cmd-docs/Cargo.toml @@ -0,0 +1,34 @@ +[package] +authors = { workspace = true } +edition = { workspace = true } +name = "spfs-cli-docs" +version = { workspace = true } +license-file = { workspace = true } +homepage = { workspace = true } +repository = { workspace = true } +readme = { workspace = true } +description = { workspace = true } + +[lints] +workspace = true + +[[bin]] +name = "spfs-docs" +path = "src/cmd_docs.rs" + +[features] +sentry = ["spfs-cli-common/sentry"] + +[dependencies] +chrono = { workspace = true } +clap = { workspace = true } +clap-markdown = "0.1.5" +colored = { workspace = true } +miette = { workspace = true, features = ["fancy"] } +question = "0.2.2" +spfs = { workspace = true } +spfs-cli-common = { workspace = true } +spfs-cli-main = { workspace = true } +tokio = { workspace = true, features = ["rt", "rt-multi-thread"] } +tracing = { workspace = true } +url = { version = "2.2", features = ["serde"] } diff --git a/crates/spfs-cli/main/src/cmd_docs.rs b/crates/spfs-cli/cmd-docs/src/cmd_docs.rs similarity index 77% rename from crates/spfs-cli/main/src/cmd_docs.rs rename to crates/spfs-cli/cmd-docs/src/cmd_docs.rs index 5f1ceeb9b3..46d22ccc67 100644 --- a/crates/spfs-cli/main/src/cmd_docs.rs +++ b/crates/spfs-cli/cmd-docs/src/cmd_docs.rs @@ -1,16 +1,24 @@ // Copyright (c) Contributors to the SPK project. // SPDX-License-Identifier: Apache-2.0 // https://github.com/spkenv/spk + use std::fs; -use clap::Args; +use clap::Parser; use miette::Result; +use spfs_cli_common as cli; + +cli::main!(CmdDocs); -use crate::cmd_spfs::Opt; +use spfs_cli_main::cmd_spfs::Opt; /// Write Markdown documentation for all SPFS subcommands to docs folder. -#[derive(Debug, Args)] -pub struct CmdDocs {} +#[derive(Debug, Parser)] +#[clap(name = "spfs-docs")] +pub struct CmdDocs { + #[clap(flatten)] + pub logging: cli::Logging +} impl CmdDocs { pub async fn run(&mut self, _config: &spfs::Config) -> Result { diff --git a/crates/spfs-cli/main/Cargo.toml b/crates/spfs-cli/main/Cargo.toml index a5387d1d78..b9f666b1e7 100644 --- a/crates/spfs-cli/main/Cargo.toml +++ b/crates/spfs-cli/main/Cargo.toml @@ -37,7 +37,6 @@ server = [ async-recursion = "1.0.2" chrono = { workspace = true } clap = { workspace = true } -clap-markdown = "0.1.5" colored = "2.0" dunce = { workspace = true } futures = { workspace = true } diff --git a/crates/spfs-cli/main/src/cmd_spfs.rs b/crates/spfs-cli/main/src/cmd_spfs.rs index b6990655f8..772452da99 100644 --- a/crates/spfs-cli/main/src/cmd_spfs.rs +++ b/crates/spfs-cli/main/src/cmd_spfs.rs @@ -8,7 +8,6 @@ use crate::{ cmd_commit, cmd_config, cmd_diff, - cmd_docs, cmd_edit, cmd_info, cmd_init, @@ -79,7 +78,6 @@ pub enum Command { Check(cmd_check::CmdCheck), Read(cmd_read::CmdRead), Write(cmd_write::CmdWrite), - Docs(cmd_docs::CmdDocs), #[cfg(feature = "server")] Server(crate::cmd_server::CmdServer), @@ -123,7 +121,6 @@ impl Opt { Command::Shell(cmd) => cmd.run(config).await, Command::Pull(cmd) => cmd.run(config).await, Command::Push(cmd) => cmd.run(config).await, - Command::Docs(cmd) => cmd.run(config).await, #[cfg(feature = "server")] Command::Server(cmd) => cmd.run(config).await, Command::External(args) => run_external_subcommand(args.clone()).await, diff --git a/crates/spfs-cli/main/src/lib.rs b/crates/spfs-cli/main/src/lib.rs index 9ed98e6717..e50e092ff6 100644 --- a/crates/spfs-cli/main/src/lib.rs +++ b/crates/spfs-cli/main/src/lib.rs @@ -7,7 +7,6 @@ mod cmd_check; mod cmd_commit; mod cmd_config; mod cmd_diff; -mod cmd_docs; mod cmd_edit; mod cmd_info; mod cmd_init; diff --git a/docs/spfs/cli/markdown.md b/docs/spfs/cli/markdown.md index 3f7b2d9b9b..6e6114b2e9 100644 --- a/docs/spfs/cli/markdown.md +++ b/docs/spfs/cli/markdown.md @@ -41,7 +41,6 @@ This document contains the help content for the `spfs-cli-main` command-line pro * [`spfs-cli-main check`↴](#spfs-cli-main-check) * [`spfs-cli-main read`↴](#spfs-cli-main-read) * [`spfs-cli-main write`↴](#spfs-cli-main-write) -* [`spfs-cli-main docs`↴](#spfs-cli-main-docs) ## `spfs-cli-main` @@ -81,7 +80,6 @@ EXTERNAL SUBCOMMANDS: * `check` — Check a repositories internal integrity * `read` — Output the contents of a blob to stdout * `write` — Store an arbitrary blob of data in spfs -* `docs` — Output the current configuration of spfs ###### **Options:** @@ -789,14 +787,6 @@ Store an arbitrary blob of data in spfs -## `spfs-cli-main docs` - -Output the current configuration of spfs - -**Usage:** `spfs-cli-main docs` - - -
From 3f2f31808cee206780ab0022426586f9ec5fafd4 Mon Sep 17 00:00:00 2001 From: BryceGattis Date: Sat, 7 Jun 2025 11:57:17 -0500 Subject: [PATCH 15/15] Cleanup unused imports and fixup lint Signed-off-by: BryceGattis --- crates/spfs-cli/cmd-docs/Cargo.toml | 4 ---- crates/spfs-cli/cmd-docs/src/cmd_docs.rs | 2 +- crates/spfs-cli/main/src/lib.rs | 2 +- 3 files changed, 2 insertions(+), 6 deletions(-) diff --git a/crates/spfs-cli/cmd-docs/Cargo.toml b/crates/spfs-cli/cmd-docs/Cargo.toml index 761b6bb867..3e564fb091 100644 --- a/crates/spfs-cli/cmd-docs/Cargo.toml +++ b/crates/spfs-cli/cmd-docs/Cargo.toml @@ -20,15 +20,11 @@ path = "src/cmd_docs.rs" sentry = ["spfs-cli-common/sentry"] [dependencies] -chrono = { workspace = true } clap = { workspace = true } clap-markdown = "0.1.5" -colored = { workspace = true } miette = { workspace = true, features = ["fancy"] } -question = "0.2.2" spfs = { workspace = true } spfs-cli-common = { workspace = true } spfs-cli-main = { workspace = true } tokio = { workspace = true, features = ["rt", "rt-multi-thread"] } tracing = { workspace = true } -url = { version = "2.2", features = ["serde"] } diff --git a/crates/spfs-cli/cmd-docs/src/cmd_docs.rs b/crates/spfs-cli/cmd-docs/src/cmd_docs.rs index 46d22ccc67..d4a7248065 100644 --- a/crates/spfs-cli/cmd-docs/src/cmd_docs.rs +++ b/crates/spfs-cli/cmd-docs/src/cmd_docs.rs @@ -17,7 +17,7 @@ use spfs_cli_main::cmd_spfs::Opt; #[clap(name = "spfs-docs")] pub struct CmdDocs { #[clap(flatten)] - pub logging: cli::Logging + pub logging: cli::Logging, } impl CmdDocs { diff --git a/crates/spfs-cli/main/src/lib.rs b/crates/spfs-cli/main/src/lib.rs index e50e092ff6..79b0c2be36 100644 --- a/crates/spfs-cli/main/src/lib.rs +++ b/crates/spfs-cli/main/src/lib.rs @@ -2,7 +2,6 @@ // SPDX-License-Identifier: Apache-2.0 // https://github.com/spkenv/spk -pub mod cmd_spfs; mod cmd_check; mod cmd_commit; mod cmd_config; @@ -30,6 +29,7 @@ mod cmd_search; #[cfg(feature = "server")] mod cmd_server; mod cmd_shell; +pub mod cmd_spfs; mod cmd_tag; mod cmd_tags; mod cmd_untag;