feat: add file_clone option for reflink-based disk cache

Cherry-picked from upstream PR mozilla#2640.

Adds a file_clone option for the disk cache that stores cache entries
as uncompressed files and restores them using filesystem reflinks
(clonefile() on APFS, FICLONE on Linux). When supported, restored
artifacts share underlying storage blocks with the cache entry.

Configure with SCCACHE_FILE_CLONE=true or file_clone = true in
[cache.disk] config.

Upstream: mozilla#2640

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mmastrac

Cargo.lock

@@ -75,6 +75,7 @@ opendal = { version = "0.55.0", optional = true, default-features = false, featu
 ] }
 openssl = { version = "0.10.75", optional = true }
 rand = "0.8.4"
+reflink-copy = "0.1"
 regex = "1.10.3"
 reqsign = { version = "0.18.0", optional = true }
 reqwest = { version = "0.12", features = [

Cargo.toml

@@ -0,0 +1,52 @@
+# FileClone Storage
+
+## Overview
+
+The `file_clone` option enables uncompressed cache storage with Copy-on-Write (CoW) filesystem support for faster cache hits.
+
+## Configuration
+
+Add to your sccache config file (e.g., `~/.config/sccache/config`):
+
+```toml
+[cache.disk]
+file_clone = true
+```
+
+Or set via environment variable:
+
+```bash
+export SCCACHE_FILE_CLONE=true
+```
+
+## How it Works
+
+When `file_clone` is enabled:
+
+1. **Detection**: sccache checks if the cache directory is on a CoW filesystem (APFS on macOS, Btrfs/XFS on Linux)
+2. **Uncompressed Storage**: Cache entries are stored as directories with raw files instead of ZIP+zstd
+3. **Reflink Extraction**: On cache hit, files are copied using reflink (near-instant on CoW filesystems)
+4. **Fallback**: If CoW is not supported, automatically falls back to traditional compressed storage
+
+## Performance Benefits
+
+On CoW filesystems:
+- Near-zero copy time for cached files (reflink uses filesystem-level COW)
+- Reduced CPU usage (no decompression step)
+- Trade-off: Slightly higher disk usage (uncompressed files)
+
+## Compatibility
+
+Works on:
+- macOS with APFS
+- Linux with Btrfs
+- Linux with XFS
+- Other filesystems with reflink support
+
+If the filesystem doesn't support reflink, sccache automatically uses compressed storage and logs a warning.
+
+## Implementation Details
+
+- Cache entries stored as directories under `cache/a/b/{hash}/`
+- Each directory contains: `{object_name}`, `stdout`, `stderr`
+- Original ZIP+zstd format still supported for backwards compatibility

docs/FileClone.md

@@ -629,6 +629,7 @@ pub fn storage_from_config(
         preprocessor_cache_mode_config,
         rw_mode,
         config.basedirs.clone(),
+        config.fallback_cache.file_clone,
     )))
 }
 

src/cache/cache.rs

@@ -48,8 +48,10 @@ pub struct FileObjectSource {
 
 /// Result of a cache lookup.
 pub enum Cache {
-    /// Result was found in cache.
+    /// Result was found in cache (compressed ZIP format).
     Hit(CacheRead),
+    /// Result was found in cache (uncompressed directory format).
+    UncompressedHit(UncompressedCacheEntry),
     /// Result was not found in cache.
     Miss,
     /// Do not cache the results of the compilation.
@@ -62,6 +64,7 @@ impl fmt::Debug for Cache {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match *self {
             Cache::Hit(_) => write!(f, "Cache::Hit(...)"),
+            Cache::UncompressedHit(_) => write!(f, "Cache::UncompressedHit(...)"),
             Cache::Miss => write!(f, "Cache::Miss"),
             Cache::None => write!(f, "Cache::None"),
             Cache::Recache => write!(f, "Cache::Recache"),
@@ -283,3 +286,80 @@ impl Default for CacheWrite {
         Self::new()
     }
 }
+
+/// An uncompressed cache entry stored as a directory.
+#[derive(Debug)]
+pub struct UncompressedCacheEntry {
+    pub(crate) dir: PathBuf,
+}
+
+impl UncompressedCacheEntry {
+    pub fn new(dir: PathBuf) -> Self {
+        Self { dir }
+    }
+
+    pub async fn extract_objects<T>(self, objects: T, pool: &tokio::runtime::Handle) -> Result<()>
+    where
+        T: IntoIterator<Item = FileObjectSource> + Send + Sync + 'static,
+    {
+        pool.spawn_blocking(move || {
+            for FileObjectSource {
+                key,
+                path,
+                optional,
+            } in objects
+            {
+                let src = self.dir.join(&key);
+
+                if !src.exists() {
+                    if optional {
+                        continue;
+                    }
+                    bail!("Required object '{}' not found in cache", key);
+                }
+
+                let dir = path
+                    .parent()
+                    .context("Output file without a parent directory!")?;
+                fs::create_dir_all(dir)?;
+
+                // Read permissions from the cached source file directly
+                let mode = get_file_mode(&fs::File::open(&src)?);
+
+                // Write to a tempfile and then atomically rename to the final path,
+                // so parallel builds don't see partially-written files.
+                let tmp_path = NamedTempFile::new_in(dir)?.into_temp_path();
+                // Remove the empty temp file so reflink can create the destination
+                let _ = std::fs::remove_file(&tmp_path);
+
+                if let Err(e) = crate::reflink::reflink_or_copy(&src, &tmp_path) {
+                    if !optional {
+                        bail!("Failed to copy object '{}' to {:?}: {}", key, path, e);
+                    }
+                    continue;
+                }
+
+                tmp_path.persist(&path).map_err(|e| {
+                    anyhow::anyhow!("Failed to persist {:?} to {:?}: {}", e.path, path, e.error)
+                })?;
+
+                if let Ok(Some(mode)) = mode {
+                    set_file_mode(&path, mode)?;
+                }
+            }
+
+            Ok(())
+        })
+        .await?
+    }
+
+    pub fn get_stdout(&self) -> Vec<u8> {
+        let path = self.dir.join("stdout");
+        fs::read(&path).unwrap_or_default()
+    }
+
+    pub fn get_stderr(&self) -> Vec<u8> {
+        let path = self.dir.join("stderr");
+        fs::read(&path).unwrap_or_default()
+    }
+}