Commands
| Command | What it does |
|---|---|
stoop run [options] -- <command> [args...] | Skip the command if a proof matches; otherwise run it traced and record a proof if it passes. The default, so stoop -- make test works too. |
stoop explain [options] -- <command> [args...] | Say what would happen and why, without running anything. Prints what differed in each proof it checked. |
stoop sh <script> [args...] | Shell mode for CI. Runs the script with bash --noprofile --norc -eo pipefail, keyed by the script's contents and arguments, GITHUB_WORKFLOW, GITHUB_JOB and the working directory. Made for shell: stoop sh {0}. |
stoop ls [--store DIR] | List keys, working directories, recorded platforms, proof count, inputs in the newest proof, and when it was created (Unix seconds). Older proofs without platform information are shown as unknown. |
stoop forget <key> [--store DIR] | Drop every proof for a key. |
stoop pull [--sync git[:remote]] | Fetch every published proof from the remote once. Use it at the start of a job. |
stoop prune [--sync git[:remote]] [--max-age DUR] | Delete published proofs older than --max-age (default 7d). Needs write access. |
stoop --help, stoop --version | Help text and version. |
Options
Options go before --. Everything after it is the command.
- --key NAME
- Name the proof yourself. The default is the program name plus a hash of the arguments and the working directory, like
cargo-46fcb2881638d3cc. A named proof must still match the working directory and repository identity. - --root DIR
- The repository root. Defaults to the nearest directory containing a
.gitdirectory or file; a nested repository uses the inner root. Without.git, the working directory is the root. Paths inside the root are stored relative to it, and only reads inside it can be recorded as absent. - --store DIR
- Where proofs live. Defaults to
<root>/.stoop, or$STOOP_STORE. An external store scopes automatic keys by Git origin, or by the physical root path if there is no origin. See keys. - --env NAME
- Count this variable too. The environment already counts, minus runner bookkeeping (
GITHUB_,RUNNER_,ACTIONS_,INPUT_,STOOP_); use this to put one of those back. Repeatable. - --ignore-env NAME
- Exempt a variable that changes without mattering, such as a per-run token. Repeatable.
- --probe CMD
- External state to verify. CMD runs with
sh -cbefore the command; its output is hashed into the proof and must match again for a skip. A probe that fails, or prints something different after the command finishes, means nothing is recorded. Declaring a probe accepts network use for that step. Repeatable. - --allow-network
- Record runs that used the network anyway. You are vouching that the network can't change the result.
- --max-age DUR
- A proof stops counting after DUR:
90s,30m,12h,7d, or a bare number of seconds. Default7d;0means never expire. - --ignore PATTERN
- Paths whose reads don't count. Same syntax as
.stoopignore. Repeatable. - --no-record
- Check and skip as usual, but never write a proof. For jobs you don't trust.
- --sync git[:REMOTE]
- On a miss, fetch this key's proofs from
refs/stoop/<key>on the git remote (defaultorigin) and check again. See git sync. - --sync-write
- Publish proofs to that remote after a recorded run. Off by default; use it on the default branch only.
- --quiet
- Print nothing about the decision. The command's own output is untouched.
Environment
| Variable | Effect |
|---|---|
STOOP_FULL=1 | Never skip; still record. For the nightly full run. |
STOOP_OFF=1 | Don't trace or skip; run commands directly. |
STOOP_STORE=DIR | Default for --store. |
STOOP_SYNC=git[:REMOTE] | Default for --sync. |
STOOP_SYNC_WRITE=1 | Same as --sync-write. |
STOOP_ENV_SALT | A secret that keys the environment hashes stored in proofs. Set it from a repository secret wherever proofs are published. See How git sync works. |
These are switches. A variable that is empty, or set to 0, false, no or off, is off; anything else is on. That makes the common CI idiom STOOP_SYNC_WRITE: ${{ github.ref == 'refs/heads/main' && '1' || '' }} safe: the empty string on a pull request does not turn publishing on. An empty STOOP_SYNC or STOOP_STORE counts as unset.
Exit codes
| Command | Exit code |
|---|---|
run, sh | 0 on a skip; otherwise the command's own code (128 + signal if it was killed). 127 if it couldn't be started. |
explain | 0 if the command would be skipped, 1 if it would run. |
forget | 0 if proofs were dropped, 1 if there were none for the key. |
prune | 0 on success, 1 if the remote refused. |
| Any | 2 for a usage error, such as an unknown option. |
What the messages mean
- stoop: skip KEY: N inputs unchanged since T ago (Xms)
- A proof matched. The command did not run.
- stoop: run KEY: REASON
- No proof matched. REASON is what differed from the newest one:
no proof yet,src/main.rs changed,env changed,proof expired,STOOP_FULL is set. - stoop: recorded N inputs for KEY
- The run passed and a proof was written.
- stoop: not recorded: REASON
- The run passed but couldn't be vouched for. See when it runs anyway.
