Skip to content

Cache lifecycle

CacheCow 0.1.0 is published. Native CoW and process-lifecycle acceptance remain unverified; package installation does not establish native support or performance benefits.

Prepare, run, and inspect

Once installed and configured, use these intended commands from a Git project directory:

ccow status --preset cargo
ccow prepare --preset cargo
ccow run --preset cargo -- cargo test
ccow doctor

status inspects cache state. prepare prepares a cache without running a build. run prepares or reuses a cache and runs the requested command. doctor diagnoses configuration, environment, cache, and lock problems. Rspack and Rsbuild use their corresponding presets and configuration requirements.

If the worktree already has a cache, keep using it. On first preparation without an existing cache, CacheCow clones a compatible source cache while coordinating source access. Subsequent builds modify the worktree's own writable cache. Source changes are not pulled in automatically, and derived changes are not pushed back.

Explicit replacement

To request a fresh copy from a selected source:

ccow prepare --preset cargo --source "../main-checkout" --replace

Interactive replacement requires confirmation. Noninteractive replacement requires explicit --replace. CacheCow must finish preparing the new copy before replacing the old cache. A preparation failure must preserve the old cache and remove incomplete copies.

If CoW is unavailable and you accept the storage cost of an ordinary copy, explicitly add --allow-copy. CacheCow must report ordinary-copy use on stderr before the managed command starts. This option does not authorize ignoring permission errors, disk exhaustion, incompatible sources, or other preparation failures.

Unusable source

For a missing, corrupt, or incompatible source, interactive run offers:

  1. Build in the current worktree without the source cache.
  2. Select another source.
  3. Build in the source first.
  4. Cancel.

Before a source build, CacheCow must show the exact requested command and source working directory and obtain confirmation. It runs that same command there, not a separate preset build command. Source building must not recurse into another source-build flow or copy a cache into itself.

Noninteractive execution must fail with remediation when it needs this decision. It must not silently continue without a source cache. For CI, establish a usable source and matching configuration before retrying. A default-primary-checkout build can create its own cache directly.

prepare has no build command. With an unusable source, it offers only another source or cancellation; source building requires ccow run. Noninteractive prepare returns an actionable error.

Preparation and build failures

Disk-full, permission, and other actual preparation errors stop before launching the build. CacheCow must preserve the old cache, remove incomplete preparation, and explain the cause and remedy. Fix that cause before retrying.

Failed or cancelled builds retain their working cache. The build tool decides whether partial results remain usable. A normal rebuild after restoration is permitted; CacheCow must not bypass freshness checks to hide it.

Manual cleaning

ccow clean --preset cargo

ccow clean deletes the selected verified cache without confirmation and without --yes, including in scripts. Check ccow status and the preset before running it. It immediately refuses an in-use cache. Stop the managed build and allow its process tree to exit before retrying.

Only preset-verified cache paths may be deleted. Sources, Git metadata, CacheCow settings, external link targets, and unrelated files must remain intact. Normal cache subdirectories within a worktree are allowed; the entire worktree is never a cache.

A source cache may contain relative symbolic links that stay inside the cache, such as the .dSYM link Cargo creates with packed debug information. CacheCow copies them as links with the same target and never follows them, so writing through a copied link changes only the new cache. Absolute links, links that leave the cache, Windows junctions, and special files make preparation fail with an actionable error; remove them or select another source. On Windows, copying a symbolic link requires Developer Mode or the symbolic link privilege.

There is no age-based or capacity-based eviction. Retention is manual. Removing incomplete preparation after a failure is recovery, not eviction.

An activated Cargo shim handles cargo clean differently: it waits for the cache lock, performs no preparation or cloning, then preserves Cargo's own arguments and deletion semantics. See shims.