Troubleshooting and performance
CacheCow 0.1.0 is published. Native CoW and process-lifecycle acceptance remain unverified; package installation does not establish native support or performance benefits.
Diagnose before changing state
Run ccow doctor in the affected project and inspect ccow status. Use --verbose for paths, versions, CoW capability, lock state, and failure causes. For interception or executable-selection problems, use ccow shim doctor.
Source recovery is different from actual preparation failure. A missing or incompatible source can prompt for a decision in interactive run; a failed copy does not implicitly authorize continuing uncached. See the full cache lifecycle.
Rebuilds after cloning
A copied cache can still be invalidated. Cargo/rustc, Rspack, and Rsbuild must retain their freshness decisions. Different paths or settings can reduce reuse. Dirty and untracked files must cause the rebuilds needed for correct results.
Do not modify fingerprints or timestamps to manufacture a hit. Compare the resulting build with a clean build if you suspect stale output. Upstream tool improvements are separate work, not a first-release freshness bypass.
Measure benefits and costs
No CacheCow performance result is asserted for 0.1.0. CoW does not share compiler heaps or guarantee shared file page-cache memory. It does not guarantee lower memory use, faster builds, or a fixed percentage of storage savings. Writes after cloning allocate additional blocks; ordinary-copy fallback consumes independent storage.
For a useful comparison, measure cold preparation, a warm original build, a cloned-worktree build, and a later build after changing the worktree. Record:
- Physical allocated storage, not only apparent file sizes.
- Cache preparation time separately from build time.
- Peak and observed memory use with the measurement method.
- Tool versions, build settings, OS, architecture, filesystem, source revision, and whether CoW or ordinary copy was used.
- Source-cache state, workload changes, run count, and unmeasured limits.
Verify physical sharing and write isolation on the actual filesystem. A successful copy API, fixture, cross-build, or archive does not prove native CoW support. Modifying or cleaning one derived cache must not modify its source or another worktree. APFS, Btrfs, reflink-enabled XFS, and ReFS require their own native evidence.
Report a problem
Use GitHub Issues. Include the CacheCow version, tool and OS versions, filesystem, observed copy mode, safe reproduction steps, expected behavior, actual result, and exit code. State which checks you actually ran. Remove credentials, private contents, environment values, and sensitive command arguments before posting. There is no response-time SLA.