APFS Copy-on-Write Deduplication: Free Up Space Without Deleting Files

What is APFS Copy-on-Write Cloning?

Traditional duplicate file finders force a destructive choice: keep one copy and delete the rest. This breaks paths, disrupts build systems, and can corrupt project references.

APFS (Apple File System) offers a fundamentally different approach. Using the Darwin clonefile(2) system call, two files can share the exact same physical disk blocks — while still appearing at their original paths with full read/write access. This is called Copy-on-Write block sharing.

How clonefile(2) Works Under the Hood

When MacPilot calls clonefile(2) on a pair of duplicate files:

1. The filesystem creates a new directory entry pointing to the same B-tree extent nodes as the original.
2. Both files remain accessible at their original paths.
3. The physical disk blocks are not duplicated — they are shared.
4. Only when one copy is modified does the filesystem allocate new physical blocks for the diverging data (Copy-on-Write semantics).

The result: instant space reclamation with zero data loss and zero path changes.

Where This Matters Most for Developers

• Ollama model weights: LLM models stored in multiple hub directories (Ollama + LM Studio + HuggingFace) are often byte-identical.
• Node module copies: Different projects often install identical package tarballs.
• iOS Simulator runtimes: Multiple simulator runtimes share many identical system libraries.
• Build artifacts: Xcode reuses many object files between builds that may be identical across targets.

What MacPilot Does Differently

Most duplicate finders use SHA-256 hashing to find matches. MacPilot does too — but it then applies clonefile(2) instead of deleting. It also:

• Skips cloud-synced stubs that would trigger downloads on hash read.
• Respects SIP-protected system files.
• Verifies both files are on the same APFS volume (required for clonefile).
• Shows you projected savings before committing.