Cargo adapter

How the adapter works

Set up Cargo

Choose the cache layers for the job. Keep the compiler-cache tag and these profiles in .boringcache.toml, then use boringcache cargo --profile cargo-deps --skip-save check --locked for repeated checks. It restores Cargo home and uses sccache while keeping each worktree's target local. Use the cargo-target profile only for a deliberate checkpoint. Fresh runners can use boringcache cargo build --release --locked when moving target state is faster than rebuilding it.

[adapters.sccache]
tag = "rust-main"

[profiles.cargo-deps]
entries = [
  "cargo-registry-cache",
  "cargo-registry-index",
  "cargo-git-db"
]

[profiles.cargo-target]
entries = ["cargo-target"]

Before the first run

• Install Rust and Cargo before running the adapter.
• Install sccache 0.16.0 or newer when compiler-cache is enabled.
• Run boringcache onboard once, then commit the cargo-deps and cargo-target profiles. New CLI releases add both during onboarding.
• For repeated local or worktree checks, run boringcache cargo --profile cargo-deps --skip-save check --locked; target stays local while sccache remains writable when the credential permits it.
• When a trusted clean checkout should publish its existing target deliberately, run boringcache cargo --profile cargo-target --skip-restore check --locked --all-targets.
• Use boringcache cargo build, boringcache cargo nextest run, or the complete [adapters.cargo] command when target transport is worth its restore and publication cost.
• A Rust-target snapshot can warm a new worktree while changed source files stay newer than restored files.
• Source, package version, manifest, and lockfile changes reuse the same target tag; Cargo rebuilds affected crates.
• For builds using -Z build-std, the unreleased CLI candidate rebuilds once after first recording standard-library sources. Later restores reuse their timestamps only when source contents and successful-build evidence match. Changed or unverified sources, including symlinks, force a rebuild.
• The target uses its configured tag with the existing platform and Git suffixes. Compiler versions do not add a suffix; Cargo decides which restored outputs need rebuilding.
• Target snapshots carry package versions and locked dependency versions in .boringcache/cargo-build-v1.json for inspection. This metadata does not control restore, rebuilds, or cleanup.
• CARGO_INCREMENTAL defaults to 0, which excludes Cargo incremental directories from saves. Set CARGO_INCREMENTAL=1 to enable incremental compilation and include those directories; use compiler-cache = "none" because sccache requires incremental compilation to be disabled. The rustc query cache and obsolete BoringCache artifact receipt stay excluded.
• A dirty checkout never publishes a target snapshot. Set compiler-cache = "none" for target-state reuse without sccache.
• To omit files from target saves, add exclude = ["*.tmp", "scratch/"] under [entries.cargo-target]. For one invocation, use boringcache cargo --exclude-pattern '*.tmp' build. These use the existing archive pattern rules and do not read .gitignore or change compiler caching.

Reuse target snapshots between local worktrees

CLI 1.32.0 adds optional local target snapshots. Enable them in .boringcache.toml to restore an empty target in another worktree of the same Git repository. Each worktree gets independent files or filesystem clones and keeps its own writable target.

[adapters.cargo.local-target-cache]
enabled = true
max-size = "20GiB"

The default is off. The selected profile must include cargo-target; the cargo-deps profile does not use target snapshots. Worktrees must use the same target tag and exclusions. Existing populated targets are kept.

Local snapshots need no remote credential. A successful build in a clean checkout can capture a snapshot; dirty checkouts do not publish one. The default disk budget is 20 GiB of logical file bytes, with least-recently-restored snapshots removed when space is needed.

Run boringcache cargo --profile cargo-target build --locked in the original checkout, then in an empty worktree. The CLI reports capture or restore; Cargo decides which outputs are still fresh. An oversized or busy target is skipped with a reason.

Use the same adapter in GitHub Actions

With CLI and Action 1.31.0 or later, omit [adapters.cargo].command to restore in this step and publish after the job. Run ordinary Cargo commands in later steps. A committed command runs the complete lifecycle in the Action step. Use only one Cargo Action step per job.

- uses: boringcache/one@f0fb9b2d926a32b10c543e92093ba00c5a291b79 # v1.33.0
  with:
    trust-policy: auto
    mode: cargo

- run: cargo test --locked

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

Cache several Cargo commands in one job

CLI 1.31.0 or later can restore before a job's Cargo commands and save afterward. A phase runs no Cargo command and ignores [adapters.cargo].command. It cannot be combined with a command, --skip-restore, or --skip-save.

boringcache cargo --phase restore
cargo check --locked
cargo test --locked
boringcache cargo --phase save

In GitHub Actions, omit [adapters.cargo].command and use one mode: cargo step before ordinary Cargo steps. BoringCache One restores in its main step, exports the cache environment, and publishes in its post step. A committed command keeps the complete lifecycle inside the Action step.

Choose save: always to publish the state a job reached after a failed step, or save: never to disable publication. The default is save: on-success. Trust policy, credentials, and the dirty-checkout rule still apply. A failed command embedded in the repo plan does not publish through the post step.

Direct CLI phases transfer archives only; they do not start the compiler-cache proxy. Use the wrapped command or the Action when you also need sccache setup.

Benchmarks

Deno · shared compiler-cache hits. Proteus · Cargo + sccache.

• Proteus Cargo + sccache run

  Open run →

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

• Cargo build cache
• sccache project
• Sharing Rust Build Cache