feat: add file_clone option for reflink-based disk cache

[quake]

Summary

Add a file_clone option for the disk cache that stores cache entries as uncompressed files and restores them using filesystem reflinks (e.g. clonefile() on APFS or FICLONE on Linux).

When supported by the filesystem, restored artifacts share underlying storage blocks with the cache entry, avoiding both decompression and physical data duplication on disk.

This mode is particularly useful for workflows with frequent cargo clean + rebuild cycles (for example when switching branches), where build artifacts are repeatedly restored from cache.

Key points:

• New config option file_clone = true in [cache.disk]
  • env: SCCACHE_FILE_CLONE=true
  • default: false
• Cache entries stored as uncompressed directory structures
• Cache restores use reflink (via reflink-copy)
• Automatic fallback to the existing compressed ZIP+zstd format when reflinks are not supported
• Mixed-format reading: both compressed and uncompressed cache entries are supported

---

Benchmark Results

Benchmarks were run on macOS (APFS) using three Rust projects:

• ripgrep
• fd
• bat

Build Times

Project	Cold (Compressed)	Cold (File Clone)	Warm (Compressed)
fd	1m 06s	1m 04s	46.70s
bat	2m 03s	2m 01s	1m 02s
ripgrep	28.34s	28.42s	9.84s

Build times are effectively identical across both modes.

This indicates that file_clone does not materially change compile performance for typical Rust workloads.

---

Cache Storage

Metric	Compressed	File Clone
Cache size	184 MiB	523 MiB
Avg cache write	0.001s	0.008s
Avg cache read (hit)	0.001s	<0.001s

As expected, storing entries uncompressed increases cache size (~2.8×).

Read and write latencies remain sub-millisecond in both modes.

---

Disk Usage on Cache Restore

During warm builds, ~650 MiB of artifacts were restored from the cache.

On APFS, df reported no additional disk usage, confirming that restored files share underlying storage blocks with the cache via reflink.

For my local development workflow on a large project where I frequently switch branches and rebuild, this feature can reduce disk usage by tens of gigabytes. Since restored artifacts are reflinked from the cache instead of being fully copied, repeated cargo clean + rebuild cycles no longer multiply disk usage.

---

Tradeoffs

	Compressed (default)	File Clone
Cache size	Smaller	Larger (~2.8×)
Disk usage on cache hit	Full copy of artifacts	Shared blocks (reflink)
Filesystem requirement	Any	APFS / XFS / Btrfs
Build time	Baseline	Essentially unchanged

---

Notes

This feature is conceptually similar to the file_clone option in ccache, which also leverages filesystem reflinks to avoid unnecessary data duplication.

Related issues:
#1174
#1053

[codecov-commenter]

Codecov Report

❌ Patch coverage is 81.50376% with 123 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.91%. Comparing base (7b751fc) to head (1fbfc34).

Files with missing lines	Patch %	Lines
src/lru_disk_cache/mod.rs	70.61%	77 Missing ⚠️
src/compiler/compiler.rs	17.24%	24 Missing ⚠️
src/cache/cache_io.rs	79.62%	11 Missing ⚠️
src/cache/disk.rs	97.08%	7 Missing ⚠️
src/config.rs	84.61%	2 Missing ⚠️
src/reflink.rs	96.77%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2640      +/-   ##
==========================================
- Coverage   73.37%   72.91%   -0.47%     
==========================================
  Files          68       69       +1     
  Lines       37338    37019     -319     
==========================================
- Hits        27396    26991     -405     
- Misses       9942    10028      +86     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[quake]

@sylvestre I force pushed to resolve a windows unit test error, could you help to trigger workflow running again, thanks.