Rust Cache Action

https://github.com/swatinem/rust-cache
Admin
A GitHub Action that implements smart caching for Rust/Cargo projects with sensible defaults to...
Tokens:25,579
Snippets:188
Trust Score:9.6
License:LGPL-3.0
Update:5 days ago
Show doc for...
Tokens:
Raw
### Workspace instantiation example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

Example showing how to initialize a Workspace instance with root and target paths.

```typescript
import { Workspace } from "./workspace.js";

// Equivalent to the input line "tests -> target"
const ws = new Workspace("/repo/tests", "/repo/tests/target");
console.log(ws.root, ws.target);
```

--------------------------------

### printInfo usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Example showing how to retrieve the cache provider and print the configuration.

```ts
const provider = await getCacheProvider();
config.printInfo(provider);
```

--------------------------------

### saveState usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Example showing how to save the state after restoring the cache.

```ts
const config = await CacheConfig.new();
// ... restoreCache ...
config.saveState();
```

--------------------------------

### cleanBin usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Example showing how to invoke cleanBin conditionally based on the cache-bin configuration.

```typescript
import { cleanBin } from "./cleanup.js";
import { CacheConfig } from "./config.js";

// Only runs when the "cache-bin" input is true:
if (config.cacheBin) {
  await cleanBin(config.cargoBins); // bins recorded at main-step start
}
```

--------------------------------

### getPackages usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

Example of using getPackages to filter for dependencies outside the workspace root.

```typescript
// Keep only packages outside the workspace root (i.e. dependencies)
const deps = await workspace.getPackages(cmdFormat, (pkg) => !pkg.manifest_path.startsWith(workspace.root));
```

--------------------------------

### cleanRegistry usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Example showing how to invoke cleanRegistry based on the cache-all-crates input.

```typescript
import { cleanRegistry } from "./cleanup.js";

const crates = core.getInput("cache-all-crates").toLowerCase() || "false";
// cache-all-crates=true  -> only prune the index, keep every .crate/src
// cache-all-crates=false -> prune index + src + cache to the dependency set
await cleanRegistry(allPackages, crates !== "true");
```

--------------------------------

### cleanTargetDir full cleanup example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Example of using cleanTargetDir with a keep-list based approach before saving the cache.

```typescript
const packages = await workspace.getPackagesOutsideWorkspaceRoot(config.cmdFormat);
await cleanTargetDir(workspace.target, packages); // keep-list based
```

--------------------------------

### getCmdOutput usage examples

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Demonstrates basic command execution and usage with formatting and custom execution options.

```typescript
import { getCmdOutput } from "./utils.js";

const stdout = await getCmdOutput("{0}", "rustc -vV");
// stdout => "rustc 1.83.0 (90b35a623 2024-11-26)\n..."

// With formatting and extra options:
const meta = await getCmdOutput(
  "nix develop -c {0}",
  "cargo metadata --all-features --format-version 1 --no-deps",
  { cwd: workspace.root, env: { ...process.env, CARGO_ENCODED_RUSTFLAGS: "" } },
);
```

--------------------------------

### cleanGit usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Example showing how to invoke cleanGit after cleaning the target and registry to prune unused git dependencies.

```typescript
import { cleanGit } from "./cleanup.js";

// After the target and registry are cleaned, prune unused git deps:
await cleanGit(allPackages);
```

--------------------------------

### Usage in post step

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Example of using fromState() in a post step to continue configuration without re-reading inputs.

```ts
import { cacheProvider } from "./utils.js";
import { CacheConfig } from "./config.js";

const provider = await getCacheProvider();
const config = CacheConfig.fromState(); // throws if no state was saved
config.printInfo(provider);
```

--------------------------------

### Minimal rust-cache configuration

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/configuration.md

A basic setup for the rust-cache action using the stable toolchain.

```yaml
steps:
  - uses: actions/checkout@v6
  - run: rustup toolchain install stable --profile minimal
  - uses: Swatinem/rust-cache@v2
```

--------------------------------

### Restore entry point configuration usage

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

This example demonstrates how the restore entry point constructs the CacheConfig and uses it to restore cache paths via the cache provider.

```ts
import * as core from "@actions/core";
import { CacheConfig } from "./config.js";
import { getCacheProvider } from "./utils.js";

const cacheProvider = await getCacheProvider();
const config = await CacheConfig.new();
config.printInfo(cacheProvider);

const key = config.cacheKey;
// Pass a copy to avoid mutating the original array (upstream @actions/cache bug)
const restoreKey = await cacheProvider.cache.restoreCache(
  config.cachePaths.slice(),
  key,
  [config.restoreKey],
  { lookupOnly: core.getInput("lookup-only").toLowerCase() === "true" },
);
```

--------------------------------

### isCacheUpToDate usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Example showing how to use isCacheUpToDate to check if the cache is current.

```ts
import { isCacheUpToDate } from "./config.js";

if (isCacheUpToDate()) {
  core.info(`Cache up-to-date.`);
  return;
}
```

--------------------------------

### cleanTargetDir partial restore example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Example of using cleanTargetDir with timestamp-based pruning when a cache key mismatch occurs.

```typescript
import { cleanTargetDir } from "./cleanup.js";

// Cache restored but not a full match — pre-clean the target dir:
for (const workspace of config.workspaces) {
  try {
    await cleanTargetDir(workspace.target, [], true); // timestamp-based
  } catch {}
}
```

--------------------------------

### getPackagesOutsideWorkspaceRoot usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

Demonstrates how to retrieve external dependency crates for the save step.

```ts
const packages = await workspace.getPackagesOutsideWorkspaceRoot(config.cmdFormat);
// packages now contains only dependency crates, never the workspace crates themselves
```

--------------------------------

### exists function usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Example showing how to import and use the exists function to check for the presence of a Cargo.lock file.

```ts
import { exists } from "./utils.js";

const cargoLock = path.join(workspace.root, "Cargo.lock");
if (await exists(cargoLock)) {
  // hash the lockfile as part of the key
}
```

--------------------------------

### YAML configuration for cache-on-failure

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/save.md

Example of enabling cache saving even when the build fails, provided the main step exported the appropriate variable.

```yaml
- uses: Swatinem/rust-cache@v2
  with:
    cache-on-failure: true
```

--------------------------------

### getWorkspaceMembers usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

Demonstrates retrieving workspace members to include them in the package list during the save step.

```ts
const wsMembers = await workspace.getWorkspaceMembers(config.cmdFormat);
packages.push(...wsMembers);
```

--------------------------------

### Handling missing state

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Example of wrapping fromState() in a try-catch block to handle cases where no state was previously saved.

```ts
import { CacheConfig, isCacheUpToDate } from "./config.js";

try {
  const config = CacheConfig.fromState();
  // ... save cache ...
} catch (e) {
  // "Cache configuration not found in state"
  core.debug(`Skipping save: ${(e as Error).message}`);
}
```

--------------------------------

### reportError usage example

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Example of using reportError within a try-catch block to handle errors during cache operations.

```ts
import { reportError } from "./utils.js";

try {
  await cacheProvider.cache.saveCache(paths, key);
} catch (e) {
  reportError(e);
}
```

--------------------------------

### Handling command errors

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Example of catching errors from getCmdOutput to access the enriched commandFailed property for logging or fallback logic.

```typescript
try {
  return await getCmdOutput(cmdFormat, "rustup toolchain list --quiet");
} catch (e) {
  // e.commandFailed = { command: "rustup toolchain list --quiet", stderr: "..." }
  core.warning(`Error running rustup toolchain list, falling back to default toolchain only: ${e}`);
  return undefined;
}
```

--------------------------------

### async getPackages(cmdFormat, filter, extraArgs?)

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

Runs cargo metadata in the workspace root and returns an array of PackageDefinition objects for packages that pass the filter. Only build targets with kinds in the save set are kept. If cargo metadata fails, an empty array is returned.

```APIDOC
## async getPackages(cmdFormat, filter, extraArgs?)

### Description
Runs `cargo metadata --all-features --format-version 1 [extraArgs]` in the workspace root and filters packages using the provided predicate. Returns an array of PackageDefinition objects with saveable build targets.

### Method
async method

### Parameters
- **cmdFormat** (string) - Required - Command format string with a `{0}` placeholder, applied to the `cargo metadata` invocation
- **filter** (function) - Required - Predicate over raw metadata packages. The package type is `{ name: string; version: string; manifest_path: string; targets: Array<{ kind: Array<string>; name: string }> }`
- **extraArgs** (string) - Optional - Extra CLI arguments appended to `cargo metadata` (e.g. `"--no-deps"`)

### Behavior
Runs `cargo metadata --all-features --format-version 1 [extraArgs]` in the workspace root, with an environment of `{ ...process.env, CARGO_ENCODED_RUSTFLAGS: "" }`. For every metadata package passing `filter`, build targets are kept only if at least one of their `kind` values is in the set: `["lib", "cdylib", "dylib", "rlib", "staticlib", "proc-macro"]`. Each resulting `PackageDefinition` uses `path: path.dirname(pkg.manifest_path)`. If `cargo metadata` fails (or JSON parsing fails), the error is printed to `console.error` and an empty `Packages` array is returned.

### Returns
`Packages` — `Array<PackageDefinition>` with the shape: `{ name: string; version: string; path: string; targets: Array<string> }`

### Example
```ts
// Keep only packages outside the workspace root (i.e. dependencies)
const deps = await workspace.getPackages(cmdFormat, (pkg) => !pkg.manifest_path.startsWith(workspace.root));
```
```

--------------------------------

### new Workspace(root, target)

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

Creates a Workspace instance with the given root and target directory paths. The root is the absolute path to the cargo workspace root, and the target is the absolute path of the workspace target directory.

```APIDOC
## new Workspace(root, target)

### Description
Creates a Workspace instance representing a Cargo workspace root and its target directory.

### Constructor

#### Parameters
- **root** (string) - Required - Absolute path to the cargo workspace root
- **target** (string) - Required - Absolute path of the workspace target directory (usually <root>/target)

### Example
```ts
import { Workspace } from "./workspace.js";

// Equivalent to the input line "tests -> target"
const ws = new Workspace("/repo/tests", "/repo/tests/target");
console.log(ws.root, ws.target);
```
```

--------------------------------

### Multi-workspace and custom directory configuration

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/configuration.md

Advanced configuration for multiple workspaces, custom target directories, additional cache directories, and environment variable prefixes.

```yaml
- uses: Swatinem/rust-cache@v2
  with:
    workspaces: |
      . -> target
      tests -> target
    cache-directories: |
      ~/.cache/sccache
    env-vars: OPENSSL
    key: ${{ matrix.os }}
```

--------------------------------

### getCacheProvider Usage with Error Handling

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Demonstrates how to invoke getCacheProvider and handle potential errors or unavailable cache features.

```ts
import { getCacheProvider } from "./utils.js";

try {
  const provider = await getCacheProvider();
  core.info(`Provider: ${provider.name}`);
  if (!provider.cache.isFeatureAvailable()) {
    core.info("Cache feature not available on this runner");
    return;
  }
  await provider.cache.restoreCache(paths, key, [restoreKey], { lookupOnly });
} catch (e) {
  // e.message === 'The `cache-provider` `<bad>` is not valid.'
  process.exit(1);
}
```

--------------------------------

### CacheConfig.fromState() implementation

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

The static implementation of fromState() which reads from the STATE_CONFIG state key and reconstructs Workspace objects.

```ts
static fromState(): CacheConfig {
  const source = core.getState(STATE_CONFIG);
  if (!source) {
    throw new Error("Cache configuration not found in state");
  }
  const self = new CacheConfig();
  Object.assign(self, JSON.parse(source));
  self.workspaces = self.workspaces.map((w: any) => new Workspace(w.root, w.target));
  return self;
}
```

--------------------------------

### Usage of getCargoBins

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Demonstrates how to invoke getCargoBins to retrieve the set of binary names for use in the cleanBin process.

```ts
import { getCargoBins } from "./config.js";

const bins = await getCargoBins();
// bins => Set { "cargo-nextest", "rustc", ... }
```

--------------------------------

### async function getCargoBins(): Promise<Set<string>>

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Asynchronously retrieves the names of regular files in the Cargo bin directory and returns them as a Set. If the directory cannot be opened, it returns an empty Set.

```APIDOC
## async function getCargoBins(): Promise<Set<string>>

### Description
Asynchronously reads the Cargo bin directory and returns a Set of file names found there. If the directory does not exist or cannot be opened, the failure is swallowed and an empty Set is returned.

### Method
async function

### Endpoint
N/A (SDK function)

### Parameters
None.

### Returns
A `Set<string>` of regular-file names found in `$CARGO_HOME/bin`. If the directory does not exist or cannot be opened, an empty Set is returned.

### Example
```ts
import { getCargoBins } from "./config.js";

const bins = await getCargoBins();
// bins => Set { "cargo-nextest", "rustc", ... }
```
```

--------------------------------

### Nix dev shell integration

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/configuration.md

Uses the cmd-format option to execute the rust-cache action within a Nix development shell.

```yaml
- uses: Swatinem/rust-cache@v2
  with:
    cmd-format: nix develop -c {0}
```

--------------------------------

### getCmdOutput(cmdFormat, cmd, options)

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Formats a command string by replacing the {0} placeholder with the actual command, executes it silently using @actions/exec, and returns the captured stdout. On failure, it rethrows the error enriched with a commandFailed property containing the command and stderr.

```APIDOC
## getCmdOutput(cmdFormat, cmd, options)

### Description
Formats a command string by replacing the {0} placeholder with the actual command, executes it silently using @actions/exec, and returns the captured stdout. On failure, it rethrows the error enriched with a commandFailed property containing the command and stderr.

### Signature
```ts
export async function getCmdOutput(cmdFormat: string, cmd: string, options: exec.ExecOptions = {}): Promise<string>
```

### Parameters
- **cmdFormat** (string) - Required - Format string; the sole {0} occurrence is replaced with cmd (e.g. "nix develop -c {0}")
- **cmd** (string) - Required - The actual command, e.g. "rustc -vV" or "cargo metadata ..."
- **options** (exec.ExecOptions) - Optional - @actions/exec options. The defaults { silent: true, listeners: {stdout, stderr} } are merged first, so callers can override (e.g. { cwd, env })

### Behavior
Formats the command, runs it silently, and accumulates stdout/stderr through listeners. On failure the original error is re-thrown after attaching:
```ts
(e as any).commandFailed = { command: cmd, stderr };
```
which reportError recognizes.

### Returns
Promise<string> - the captured stdout.

### Throws
- Rethrows the original @actions/exec error, enriched with commandFailed = { command, stderr } - The process exited non-zero (or the format string replaced nothing - invoking {0}-less text, though CacheConfig validates cmdFormat contains exactly one {0})

### Example
```ts
import { getCmdOutput } from "./utils.js";

const stdout = await getCmdOutput("{0}", "rustc -vV");
// stdout => "rustc 1.83.0 (90b35a623 2024-11-26)\n..."

// With formatting and extra options:
const meta = await getCmdOutput(
  "nix develop -c {0}",
  "cargo metadata --all-features --format-version 1 --no-deps",
  { cwd: workspace.root, env: { ...process.env, CARGO_ENCODED_RUSTFLAGS: "" } },
);
```

Error handling:
```ts
try {
  return await getCmdOutput(cmdFormat, "rustup toolchain list --quiet");
} catch (e) {
  // e.commandFailed = { command: "rustup toolchain list --quiet", stderr: "..." }
  core.warning(`Error running rustup toolchain list, falling back to default toolchain only: ${e}`);
  return undefined;
}
```
```

--------------------------------

### Catching errors in the save step

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/errors.md

Demonstrates the standard try-catch pattern used in the save step, utilizing reportError to log the stack without crashing the runner.

```ts
try {
  const config = CacheConfig.fromState();
  // ... clean + save ...
} catch (e) {
  reportError(e); // logs stack; never crashes the runner
}
// note: reportError checks e.commandFailed first (see below)
```

--------------------------------

### Basic usage in GitHub Actions workflow

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/restore.md

Standard configuration for the rust-cache action in a workflow file.

```yaml
- uses: Swatinem/rust-cache@v2
  with:
    workspaces: tests
    key: ${{ matrix.target }}
```

--------------------------------

### Implementation of getCargoBins

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Retrieves a set of file names from the CARGO_HOME/bin directory. If the directory is inaccessible, it returns an empty set.

```ts
export async function getCargoBins(): Promise<Set<string>> {
  const bins = new Set<string>();
  try {
    const dir = await fs.opendir(path.join(CARGO_HOME, "bin"));
    for await (const dirent of dir) {
      if (dirent.isFile()) {
        bins.add(dirent.name);
      }
    }
  } catch {}
  return bins;
}
```

--------------------------------

### Configure rust-cache in GitHub Actions workflow

Source: https://github.com/swatinem/rust-cache/blob/master/README.md

This YAML snippet demonstrates how to integrate the rust-cache action into a workflow, including various configuration parameters for cache keys, environment variables, and workspace management.

```yaml
- uses: actions/checkout@v6

# selecting a toolchain either by action or manual `rustup` calls should happen
# before the plugin, as the cache uses the current rustc version as its cache key
- run: rustup toolchain install stable --profile minimal

- uses: Swatinem/rust-cache@v2
  with:
    # The prefix cache key, this can be changed to start a new cache manually.
    # default: "v0-rust"
    prefix-key: ""

    # A cache key that is used instead of the automatic `job`-based key,
    # and is stable over multiple jobs.
    # default: empty
    shared-key: ""

    # An additional cache key that is added alongside the automatic `job`-based
    # cache key and can be used to further differentiate jobs.
    # default: empty
    key: ""

    # If the automatic `job`-based cache key should include the job id.
    # default: "true"
    add-job-id-key: ""

    # Whether the a hash of the rust environment should be included in the cache key.
    # This includes a hash of all Cargo.toml/Cargo.lock files, rust-toolchain files,
    # and .cargo/config.toml files (if present), as well as the specified 'env-vars'.
    # default: "true"
    add-rust-environment-hash-key: ""

    # A whitespace separated list of env-var *prefixes* who's value contributes
    # to the environment cache key.
    # The env-vars are matched by *prefix*, so the default `RUST` var will
    # match all of `RUSTC`, `RUSTUP_*`, `RUSTFLAGS`, `RUSTDOC_*`, etc.
    # default: "CARGO CC CFLAGS CXX CMAKE RUST"
    env-vars: ""

    # The cargo workspaces and target directory configuration.
    # These entries are separated by newlines and have the form
    # `$workspace -> $target`. The `$target` part is treated as a directory
    # relative to the `$workspace` and defaults to "target" if not explicitly given.
    # default: ". -> target"
    workspaces: ""

    # Additional non workspace directories to be cached, separated by newlines.
    cache-directories: ""

    # Determines whether workspace `target` directories are cached.
    # If `false`, only the cargo registry will be cached.
    # default: "true"
    cache-targets: ""

    # Determines if the cache should be saved even when the workflow has failed.
    # default: "false"
    cache-on-failure: ""

    # Determines which crates are cached.
    # If `true` all crates will be cached, otherwise only dependent crates will be cached.
    # Useful if additional crates are used for CI tooling.
    # default: "false"
    cache-all-crates: ""

    # Similar to cache-all-crates.
    # If `true` the workspace crates will be cached.
    # Useful if the workspace contains libraries that are only updated sporadically.
    # default: "false"
    cache-workspace-crates: ""

    # Determines whether the cache should be saved.
    # If `false`, the cache is only restored.
    # Useful for jobs where the matrix is additive e.g. additional Cargo features,
    # or when only runs from `master` should be saved to the cache.
    # default: "true"
    save-if: ""
    # To only cache runs from `master`:
    save-if: ${{ github.ref == 'refs/heads/master' }}

    # Determines whether the cache should be restored.
    # If `true` the cache key will be checked and the `cache-hit` output will be set
    # but the cache itself won't be restored
    # default: "false"
    lookup-only: ""

    # Specifies what to use as the backend providing cache
    # Can be set to "github", or "warpbuild"
    # default: "github"
    cache-provider: ""

    # Determines whether to cache the ~/.cargo/bin directory.
    # default: "true"
    cache-bin: ""

    # A format string used to format commands to be run, i.e. `rustc` and `cargo`.
    # Must contain exactly one occurance of `{0}`, which is the formatting fragment
    # that will be replaced with the `rustc` or `cargo` command. This is necessary
    # when using Nix or other setup that requires running these commands within a
    # specific shell, otherwise the system `rustc` and `cargo` will be run.
    # default: "{0}"
    cmd-format: ""
    # To run within a Nix shell (using the default dev shell of a flake in the repo root):
    cmd-format: nix develop -c {0}
```

--------------------------------

### Async run function in src/restore.ts

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/restore.md

The main execution function that resolves the cache provider and performs a feature availability check.

```ts
async function run() {
  const cacheProvider = await getCacheProvider();

  if (!cacheProvider.cache.isFeatureAvailable()) {
    setCacheHitOutput(false);
    return;
  }
  // ...
}
```

--------------------------------

### async function exists(path)

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Checks if a file or directory exists at the given path. Returns true if the path is accessible, false otherwise.

```APIDOC
## async function exists(path)

### Description
Checks if a file or directory exists at the given path. Returns true if the path is accessible, false otherwise (including permission errors).

### Parameters
- **path** (string) - Required - Path to test

### Returns
Promise<boolean> - true if the path is accessible (file or directory), false otherwise (including permission errors).

### Example
```ts
import { exists } from "./utils.js";

const cargoLock = path.join(workspace.root, "Cargo.lock");
if (await exists(cargoLock)) {
  // hash the lockfile as part of the key
}
```
```

--------------------------------

### CacheConfig.new() method signature

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

The static new method constructs a CacheConfig instance by reading all action inputs and environment variables.

```ts
static async new(): Promise<CacheConfig> {
```

--------------------------------

### async function getCmdOutput

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Runs a (formatted) command and captures stdout. This is an async function that executes a command and returns its standard output.

```APIDOC
## async function getCmdOutput

### Description
Runs a (formatted) command and captures stdout. This is an async function that executes a command and returns its standard output.

### Parameters
No parameters are documented in the source.

### Returns
Captured stdout from the executed command.
```

--------------------------------

### getPackages method signature

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

The getPackages method signature for querying workspace packages.

```typescript
async getPackages(
  cmdFormat: string,
  filter: (p: Meta["packages"][0]) => boolean,
  extraArgs?: string,
): Promise<Packages> {
```

--------------------------------

### static fromState(): CacheConfig

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Deserializes a CacheConfig from the action state store. It reads the state saved by saveState(), parses the JSON, and reconstructs the Workspace objects. Throws an error if no state was saved or if the state is corrupted.

```APIDOC
## static fromState(): CacheConfig

### Description
Deserializes a CacheConfig from the action state store. It reads the state saved by saveState(), parses the JSON, and reconstructs the Workspace objects. Throws an error if no state was saved or if the state is corrupted.

### Method
static

### Parameters
*(none — static)*

Reads `core.getState("RUST_CACHE_CONFIG")`

### Returns
A `CacheConfig` deserialized from the action state store, saved previously by `saveState()`.

### Throws
- `Error("Cache configuration not found in state")` - No state was saved (e.g. the action's main step never ran or failed before saving).
- `SyntaxError` - Forwarded from `JSON.parse` if the saved state is corrupted.

### Example
Used in the post step to continue the same configuration without re-reading inputs (`src/save.ts:31`):

```ts
import { cacheProvider } from "./utils.js";
import { CacheConfig } from "./config.js";

const provider = await getCacheProvider();
const config = CacheConfig.fromState(); // throws if no state was saved
config.printInfo(provider);
```

Handling the missing-state case:

```ts
import { CacheConfig, isCacheUpToDate } from "./config.js";

try {
  const config = CacheConfig.fromState();
  // ... save cache ...
} catch (e) {
  // "Cache configuration not found in state"
  core.debug(`Skipping save: ${(e as Error).message}`);
}
```
```

--------------------------------

### cleanBin()

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Removes binaries that pre-dated the action run. This function is async and logs errors via core.debug.

```APIDOC
## cleanBin()

### Description
Removes binaries that pre-dated the action run. This function is async and logs errors via core.debug.

### Method
async function

### Returns
Promise<void>
```

--------------------------------

### cleanRegistry()

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Prunes registry index cache, src, and .crate archives. This function is async and logs errors via core.debug.

```APIDOC
## cleanRegistry()

### Description
Prunes registry index cache, src, and .crate archives. This function is async and logs errors via core.debug.

### Method
async function

### Returns
Promise<void>
```

--------------------------------

### getCmdOutput implementation

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

The core implementation of getCmdOutput which formats a command string, executes it silently, and captures output streams.

```typescript
export async function getCmdOutput(cmdFormat: string, cmd: string, options: exec.ExecOptions = {}): Promise<string> {
  cmd = cmdFormat.replace("{0}", cmd);
  let stdout = "";
  let stderr = "";
  try {
    await exec.exec(cmd, [], {
      silent: true,
      listeners: {
        stdout(data) {
          stdout += data.toString();
        },
        stderr(data) {
          stderr += data.toString();
        },
      },
      ...options,
    });
  } catch (e) {
    (e as any).commandFailed = {
      command: cmd,
      stderr,
    };
    throw e;
  }
  return stdout;
}
```

--------------------------------

### async function getCacheProvider

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Resolves the backend from the cache-provider input. This async function determines which cache provider to use based on the cache-provider input.

```APIDOC
## async function getCacheProvider

### Description
Resolves the backend from the cache-provider input. This async function determines which cache provider to use based on the cache-provider input.

### Parameters
No parameters are documented in the source.

### Returns
The resolved cache provider.
```

--------------------------------

### Cache save execution

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/save.md

Uploads the cache paths using the cache provider, with a workaround for an upstream mutation bug by slicing the paths array.

```ts
await cacheProvider.cache.saveCache(config.cachePaths.slice(), config.cacheKey);
```

--------------------------------

### cleanGit()

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Prunes unused git checkouts and bare databases. This function is async and logs errors via core.debug.

```APIDOC
## cleanGit()

### Description
Prunes unused git checkouts and bare databases. This function is async and logs errors via core.debug.

### Method
async function

### Returns
Promise<void>
```

--------------------------------

### getCacheProvider Function Implementation

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Dynamically imports and returns a cache provider based on the 'cache-provider' action input. Throws an error if the input is not 'github' or 'warpbuild'.

```ts
export async function getCacheProvider(): Promise<CacheProvider> {
  const cacheProvider = core.getInput("cache-provider");
  let cache: GhCache;
  switch (cacheProvider) {
    case "github":
      cache = await import("@actions/cache");
      break;
    case "warpbuild":
      cache = await import("@actions/warpbuild-cache");
      break;
    default:
      throw new Error(`The \`cache-provider\` \`${cacheProvider}\` is not valid.`);
  }

  return {
    name: cacheProvider,
    cache: cache,
  };
}
```

--------------------------------

### Lookup-only usage in GitHub Actions workflow

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/restore.md

Configures the action to check for a cache hit without downloading the cache, and demonstrates how to access the output.

```yaml
- uses: Swatinem/rust-cache@v2
  id: rust-cache
  with:
    lookup-only: true

- name: Use cache hit result
  run: echo "cache-hit=${{ steps.rust-cache.outputs.cache-hit }}"
```

--------------------------------

### Async run function in src/save.ts

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/save.md

The main execution function that resolves the cache provider and checks the save-if condition before proceeding.

```ts
async function run() {
  const cacheProvider = await getCacheProvider();

  const save = core.getInput("save-if").toLowerCase() || "true";

  if (!(cacheProvider.cache.isFeatureAvailable() && save === "true")) {
    return;
  }
  // ...
}
```

--------------------------------

### Handling invalid cache-provider errors

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/errors.md

Shows how to catch and report errors when an invalid cache-provider input is provided, using core.setFailed to signal the failure.

```ts
import { getCacheProvider } from "./utils.js";

try {
  const provider = await getCacheProvider();
} catch (e) {
  // e.message === 'The `cache-provider` `my-backend` is not valid.'
  core.setFailed(`Invalid cache-provider: ${(e as Error).message}`);
}
```

--------------------------------

### async function exists

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Path existence check. This async function checks whether a given path exists.

```APIDOC
## async function exists

### Description
Path existence check. This async function checks whether a given path exists.

### Parameters
No parameters are documented in the source.

### Returns
A boolean indicating whether the path exists.
```

--------------------------------

### CacheConfig class definition

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Defines the structure for cache configuration, including cache paths, keys, and workspace settings. The constructor is private; instances must be created via CacheConfig.new() or CacheConfig.fromState().

```ts
export class CacheConfig {
  public cmdFormat: string = "";
  public cachePaths: Array<string> = [];
  public cacheKey = "";
  public restoreKey = "";
  public cacheBin: boolean = true;
  public workspaces: Array<Workspace> = [];
  public cargoBins: Array<string> = [];
  private keyPrefix = "";
  private keyRust: Array<string> = [];
  private keyEnvs: Array<string> = [];
  private keyFiles: Array<string> = [];
  private constructor() {}
}
```

--------------------------------

### async function cleanGit(packages)

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Cleans up unused git dependencies by removing repositories and checkouts not present in the provided keep-list. Returns a Promise that resolves when cleanup is complete.

```APIDOC
## async function cleanGit(packages)

### Description
Cleans up unused git dependencies by removing repositories and checkouts not present in the provided keep-list. Returns a Promise that resolves when cleanup is complete.

### Signature
```ts
export async function cleanGit(packages: Packages)
```

### Parameters
- **packages** (Packages) - Required - Keep-list; entries with `path` starting with `$CARGO_HOME/git/checkouts` map repo → checked-out refs

### Behavior
Builds a `Map<string, Set<string>>` of `repo → refs` from packages fetched via git dependencies. Then:
1. In `$CARGO_HOME/git/db` (bare clones), any repo directory not in the map is removed.
2. In `$CARGO_HOME/git/checkouts`, any repo not in the map is removed; for kept repos, any checkout ref directory not in the kept ref set is removed.

Both the `db` clone and the `checkouts` checkout must be kept together — removing either triggers a rebuild.

### Returns
`Promise<void>`. Missing directories are caught and ignored.

### Example
```ts
import { cleanGit } from "./cleanup.js";

// After the target and registry are cleaned, prune unused git deps:
await cleanGit(allPackages);
```
```

--------------------------------

### Cache restoration logic in src/restore.ts

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/restore.md

Performs the cache lookup or restoration using the configured cache key and paths.

```ts
const key = config.cacheKey;
const restoreKey = await cacheProvider.cache.restoreCache(
  config.cachePaths.slice(),
  key,
  [config.restoreKey],
  { lookupOnly },
);
```

--------------------------------

### printInfo method signature

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

The signature for the printInfo method which accepts a CacheProvider.

```ts
printInfo(cacheProvider: CacheProvider) {
```

--------------------------------

### CARGO_HOME constant definition

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Defines the resolved cargo home directory, defaulting to ~/.cargo if the CARGO_HOME environment variable is not set.

```ts
export const CARGO_HOME = process.env.CARGO_HOME || path.join(HOME, ".cargo");
```

--------------------------------

### cleanTargetDir(targetDir, packages, checkTimestamp = false)

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Recursively prunes a cargo target directory, removing artifacts not in the keep-list or older than one week when checkTimestamp is true. Returns a Promise that resolves when cleanup is complete.

```APIDOC
## cleanTargetDir(targetDir, packages, checkTimestamp = false)

### Description
Recursively prunes a cargo target directory, removing artifacts not in the keep-list or older than one week when checkTimestamp is true. Returns a Promise that resolves when cleanup is complete.

### Method
async function

### Signature
```ts
export async function cleanTargetDir(targetDir: string, packages: Packages, checkTimestamp = false)
```

### Parameters
- **targetDir** (string) - Required - Absolute path of a cargo target directory
- **packages** (Packages) - Required - Keep-list (Array<PackageDefinition>) of artifacts to preserve; [] preserves nothing
- **checkTimestamp** (boolean) - Optional, default false - When true, remove artifacts older than one week instead of matching the keep-list

### Returns
Promise<void>. Failure in any subdirectory is caught and ignored.

### Example
Partial restore (key mismatch) ages out one-week-old artifacts without a keep-list:
```ts
import { cleanTargetDir } from "./cleanup.js";

// Cache restored but not a full match — pre-clean the target dir:
for (const workspace of config.workspaces) {
  try {
    await cleanTargetDir(workspace.target, [], true); // timestamp-based
  } catch {}
}
```

Full cleanup before saving:
```ts
const packages = await workspace.getPackagesOutsideWorkspaceRoot(config.cmdFormat);
await cleanTargetDir(workspace.target, packages); // keep-list based
```
```

--------------------------------

### saveState method implementation

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Implementation of the saveState method which persists the CacheConfig instance.

```ts
saveState() {
  core.saveState(STATE_CONFIG, this);
}
```

--------------------------------

### interface GhCache

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

The @actions/cache-compatible backend surface. This interface defines the cache operations that a backend must implement to be compatible with the @actions/cache library.

```APIDOC
## interface GhCache

### Description
The @actions/cache-compatible backend surface. This interface defines the cache operations that a backend must implement to be compatible with the @actions/cache library.

### Methods
No methods are documented in the source.
```

--------------------------------

### PackageDefinition return type

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

The structure of the PackageDefinition objects returned by getPackages.

```typescript
{ name: string; version: string; path: string; targets: Array<string> }
```

--------------------------------

### macOS workaround function

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/save.md

Executes a system purge on macOS to prevent cache corruption, swallowing any execution errors.

```ts
async function macOsWorkaround() {
  try {
    await exec.exec("sudo", ["/usr/sbin/purge"], { silent: true });
  } catch {}
}
```

--------------------------------

### interface CacheProvider

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

A named cache backend. This interface represents a cache backend with a name identifier.

```APIDOC
## interface CacheProvider

### Description
A named cache backend. This interface represents a cache backend with a name identifier.

### Properties
No properties are documented in the source.
```

--------------------------------

### Workspace class definition

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

The Workspace class constructor requires the absolute path to the cargo workspace root and the target directory.

```typescript
export class Workspace {
  constructor(
    public root: string,
    public target: string,
  ) {}
}
```

--------------------------------

### setCacheHitOutput function in src/restore.ts

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/restore.md

Writes the cache-hit output as a string to the GitHub Actions environment.

```ts
function setCacheHitOutput(cacheHit: boolean): void {
  core.setOutput("cache-hit", cacheHit.toString());
}
```

--------------------------------

### getCacheProvider

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Asynchronously resolves the cache provider based on the 'cache-provider' action input. Returns a CacheProvider object containing the provider name and the cache implementation.

```APIDOC
## getCacheProvider

### Description
Asynchronously resolves the cache provider based on the 'cache-provider' action input. Returns a CacheProvider object containing the provider name and the cache implementation.

### Method
async function

### Endpoint
N/A (SDK function)

### Parameters
None - reads the 'cache-provider' action input.

### Returns
Promise<CacheProvider> - { name, cache } where cache is the dynamically imported module (@actions/cache or @actions/warpbuild-cache, both satisfying GhCache structurally).

### Throws
- Error("The `cache-provider` `<value>` is not valid.") - when the input is not "github" or "warpbuild" (including empty string when the input is unset).

### Example
```ts
import { getCacheProvider } from "./utils.js";

try {
  const provider = await getCacheProvider();
  core.info(`Provider: ${provider.name}`);
  if (!provider.cache.isFeatureAvailable()) {
    core.info("Cache feature not available on this runner");
    return;
  }
  await provider.cache.restoreCache(paths, key, [restoreKey], { lookupOnly });
} catch (e) {
  // e.message === 'The `cache-provider` `<bad>` is not valid.'
  process.exit(1);
}
```
```

--------------------------------

### GhCache Interface Definition

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Defines the minimal backend surface required by cache providers, mapping to @actions/cache functionality.

```ts
export interface GhCache {
  isFeatureAvailable: typeof import("@actions/cache").isFeatureAvailable;
  restoreCache: typeof import("@actions/cache").restoreCache;
  saveCache: (paths: string[], key: string) => Promise<string | number>;
}
```

--------------------------------

### Enriching exec.exec errors with command details

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/errors.md

Attaches the executed command and stderr output to the error object when a non-zero exit or spawn failure occurs in getCmdOutput.

```ts
(e as any).commandFailed = {
  command: cmd,   // the formatted command actually run
  stderr,         // captured stderr
};
```

--------------------------------

### Global error hook in src/save.ts

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/save.md

Logs uncaught exceptions and their stack traces using the core logger.

```ts
process.on("uncaughtException", (e) => {
  core.error(e.message);
  if (e.stack) {
    core.error(e.stack);
  }
});
```

--------------------------------

### function reportError(e)

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Logs enriched errors (commandFailed metadata or stack) using core.error. If the error has a truthy commandFailed property, it logs the command and its captured stderr; otherwise it logs the error stack.

```APIDOC
## function reportError(e)

### Description
Logs enriched errors (commandFailed metadata or stack) using core.error. If the error has a truthy commandFailed property, it logs the command and its captured stderr; otherwise it logs the error stack.

### Parameters
- **e** (any) - Required - The caught error; may carry the commandFailed property attached by getCmdOutput.

### Behavior
If the error has a truthy commandFailed property ({ command: string; stderr: string }), logs the command and its captured stderr via core.error; otherwise logs e.stack. Used by both entry points' catch blocks.

### Example
```ts
import { reportError } from "./utils.js";

try {
  await cacheProvider.cache.saveCache(paths, key);
} catch (e) {
  reportError(e);
}
```
```

--------------------------------

### Internal helper signatures

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

Signatures for internal helper functions used for cache management, including profile target cleaning, registry index cache pruning, and file system removal utilities.

```typescript
async function cleanProfileTarget(profileDir: string, packages: Packages, checkTimestamp = false)
async function cleanRegistryIndexCache(dirName: string, keepPkg: Set<string>): Promise<boolean>
async function rmExcept(dirName: string, keepPrefix: Set<string>, checkTimestamp = false)
async function rm(parent: string, dirent: fs.Dirent)
async function rmRF(dirName: string)

const ONE_WEEK = 7 * 24 * 3600 * 1000;
```

--------------------------------

### cleanBin function definition

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

The signature for the cleanBin function which accepts an array of binary names.

```typescript
export async function cleanBin(oldBins: Array<string>) {
```

--------------------------------

### CacheProvider Interface Definition

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

Defines the structure for a cache provider, including its name and the associated GhCache implementation.

```ts
export interface CacheProvider {
  name: string;
  cache: GhCache;
}
```

--------------------------------

### PackageDefinition Interface

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/types.md

Defines the structure of a package within the workspace, including its name, version, path, and build targets. This interface is defined in src/workspace.ts.

```ts
export interface PackageDefinition {
  name: string;
  version: string;
  path: string;
  targets: Array<string>;
}
```

--------------------------------

### isCacheUpToDate function implementation

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/config.md

Implementation of the isCacheUpToDate function.

```ts
export function isCacheUpToDate(): boolean {
  return core.getState(STATE_CONFIG) === "";
}
```

--------------------------------

### cleanTargetDir function signature

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

The primary function signature for recursively pruning a cargo target directory.

```typescript
export async function cleanTargetDir(targetDir: string, packages: Packages, checkTimestamp = false) {
```

--------------------------------

### getPackagesOutsideWorkspaceRoot method definition

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/workspace.md

Defines the method to filter packages whose manifest_path is outside the workspace root.

```ts
public async getPackagesOutsideWorkspaceRoot(cmdFormat: string): Promise<Packages> {
  return await this.getPackages(cmdFormat, (pkg) => !pkg.manifest_path.startsWith(this.root));
}
```

--------------------------------

### exists function implementation

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/utils.md

The exists function checks if a path is accessible by attempting to access it using fs.promises.access. It returns true if accessible and false otherwise.

```ts
export async function exists(path: string) {
  try {
    await fs.promises.access(path);
    return true;
  } catch {
    return false;
  }
}
```

--------------------------------

### Conditional caching with save-if

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/configuration.md

Configures the action to only save the cache when running on the master branch, while still allowing restoration on other branches.

```yaml
- uses: Swatinem/rust-cache@v2
  with:
    save-if: ${{ github.ref == 'refs/heads/master' }}
```

--------------------------------

### cleanGit function signature

Source: https://github.com/swatinem/rust-cache/blob/master/_autodocs/api-reference/cleanup.md

The exported signature for the cleanGit function.

```typescript
export async function cleanGit(packages: Packages) {
```
Tokens:
Raw