Help Reference

Usage: spaces [OPTIONS] <COMMAND>

Commands:
  checkout       
                 Executes the checkout rules in the specified scripts or workflow files.
  checkout-repo  
                 Uses git to clone a repository in a new workspace and evaluates the top level [*]spaces.star files.
                 This can be used if the repository defines all of its own dependencies.
  co             
                 The shortform version of `checkout` and `checkout-repo`. The details of the command are
                 loaded from `co.spaces.toml` in the current directory.
                 
                 ```toml
                 [spaces-dev.Repo]
                 url = "https://github.com/work-spaces/spaces"
                 rule-name = "spaces" # optionally checkout in a different directory - default is from URL
                 rev = "main" # branch/tag/commit to checkout
                 new-branch = ["spaces"] # optionally create a new branch for a git repository
                 clone = "Default" # optionally clone type Default/Blobless
                 env = ["SET_VALUE=VALUE", "ANOTHER_VALUE=ANOTHER_VALUE"] # optionally add environment variables
                 create-lock-file = false # optionally create a lock file
                 
                 
                 [ninja-build.Workflow]
                 # Loads the ninja-build-dev flow from workflows/workflows.spaces.toml
                 workflow = "workflows:ninja-build-dev" # Workflow to checkout or use script
                 script = ["workflows/preload", "workflows/ninja-build"] # Use in place of or addition to workflow
                 env = ["SET_VALUE=VALUE", "ANOTHER_VALUE=ANOTHER_VALUE"] # optionally add environment variables
                 new-branch = ["spaces"] # optionally create a new branch for a git repository
                 create-lock-file = false # optionally create a lock file
                 ```
                 
  sync           Runs checkout rules within an existing workspace (experimental)
  run            Runs a spaces run rule.
                   - `spaces run`: Run all non-optional rules with dependencies
                   - `spaces run my-target`: Run a single target plus dependencies
                   - `spaces run my-target -- --some-arg --some-other-arg`: pass additional arguments to a rule
  inspect        Inspect all the scripts in the workspace without running any rules.
                   - `spaces inspect`: show the rules that have `help` entries:
                   - `spaces inspect <target-name>`: show target plus dependencies
                   - `spaces --verbosity=message inspect`: show all rules
                   - `spaces --verbosity=debug inspect`: show all rules in detail
  completions    Generates shell completions for the spaces command (experimental)
  docs           Shows the documentation for spaces starlark modules
  foreach        Runs a command in each repo or branch in the workspace
  shell          Runs an interactive shell using the workspace environment (experimental)
  help           Print this message or the help of the given subcommand(s)

Options:
  -v, --verbosity <VERBOSITY>  [default: app] [possible values: trace, debug, message, info, app, passthrough, warning, error]
      --hide-progress-bars     Dont show progress bars
      --show-elapsed-time      Show elapsed time - use with --verbosity=debug to instrument spaces performance
      --ci                     If this is passed, info.is_ci() returns true in scripts
      --rescan                 Rescan the workspace for *spaces.star files
  -h, --help                   Print help
  -V, --version                Print version

Executes the checkout rules in the specified scripts or workflow files.

Usage: spaces checkout [OPTIONS] --name <NAME>

Options:
      --name <NAME>                The name of the workspace to create
      --env <ENV>                  Environment variables to add to the checked out workspace.
                                     Use `--env=VAR=VALUE`. Makes workspace not reproducible.
      --new-branch <NEW_BRANCH>    Use --new-branch=<rule> to have spaces create a new branch for the rule.
                                     Branch name will match the workspace name.
      --script <SCRIPT>            The path(s) to the `spaces.star` file containing checkout rules. Paths are processed in order
      --workflow <WORKFLOW>        Scripts to process in the format of `--workflow=<directory>:<script>,<script>,...`.
                                     `--script` is processed before `--workflow`.
                                   
                                     If <directory> has `workflows.spaces.toml`, it will be parsed for shortcuts if only one <script> is passed.
                                     - `spaces checkout --workflow=workflows:my-shortcut --name=workspace-name`
                                       - run scripts listed in `my-shortcut` in `workflows/workflows.spaces.toml`
                                     - `spaces checkout --workflow=workflows:preload,my-shortcut --name=workspace-name`
                                       - run `workflows/preload.spaces.star` then `workflows/my-shortcut.spaces.star`
                                   
                                     ```toml
                                     my-shortcut = ["preload", "my-shortcut"]
                                     ```
      --wf <WF>                    Shortcut for --workflow
      --create-lock-file           Create a lock file for the workspace.
                                     This file can be passed on the next checkout as a script to re-create the exact workspace.
      --force-install-tools        Force install the tools spaces needs to run
      --keep-workspace-on-failure  Do not delete the workspace directory if checkout fails
  -h, --help                       Print help

Runs a spaces run rule.
  - `spaces run`: Run all non-optional rules with dependencies
  - `spaces run my-target`: Run a single target plus dependencies
  - `spaces run my-target -- --some-arg --some-other-arg`: pass additional arguments to a rule

Usage: spaces run [OPTIONS] [TARGET] [EXTRA_RULE_ARGS]...

Arguments:
  [TARGET]              The name of the target to run (default is all targets)
  [EXTRA_RULE_ARGS]...  Extra arguments to pass to the rule (passed after `--`)

Options:
      --forget-inputs  Forces rules to run even if input globs are the same as last time
      --skip-deps      Runs only the target specified, without executing dependencies
      --env <ENV>      Environment variables to override during the run. Use `--env=VAR=VALUE`
  -h, --help           Print help

Inspect all the scripts in the workspace without running any rules.
  - `spaces inspect`: show the rules that have `help` entries:
  - `spaces inspect <target-name>`: show target plus dependencies
  - `spaces --verbosity=message inspect`: show all rules
  - `spaces --verbosity=debug inspect`: show all rules in detail

Usage: spaces inspect [OPTIONS] [TARGET]

Arguments:
  [TARGET]  The name of the target to evaluate (default is all targets)

Options:
      --filter <FILTER>      Filter targets with a glob (e.g. `--filter=**/my-target`)
      --has-help             Only show rules with the help entry populated
      --markdown <MARKDOWN>  Write the output of the inspect command to a markdown file
      --stardoc <STARDOC>    Write the starlark documentation to the specified path
  -h, --help                 Print help