filefold

Keep the files. Reclaim the space.

filefold is a conservative macOS storage optimizer for exact duplicates you intentionally keep. It replaces redundant allocation with APFS copy-on-write clones while preserving every pathname, each file's independent identity, and supported metadata.

Duplicates are not always clutter. Project archives, copied workspaces, reusable media, and historical snapshots may need to stay complete—even when they contain the same large files.

Traditional duplicate cleaners ask which copy to delete. Hard links keep multiple paths, but make them names for the same mutable file. filefold takes a different approach: the files remain independently writable, while APFS shares their identical storage until either file changes.

Before:  archive-2025/video.mov  ── independently allocated data
         archive-2026/video.mov  ── independently allocated data

After:   archive-2025/video.mov  ─┐
                                  ├─ shared APFS storage, independent files
         archive-2026/video.mov  ─┘

Built for files you want to keep

filefold is a strong fit when:

• project or archive directories must remain self-contained;
• copied workspaces contain large, repeated assets;
• paths and metadata carry workflow meaning;
• either copy may need to change independently later;
• deleting a “duplicate” is not an acceptable answer.

If your duplicates are disposable clutter, use a duplicate cleaner. If they are similar rather than byte-for-byte identical, use a media curation tool. filefold deliberately handles neither case.

Conservative by design

Filesystem optimization deserves a higher standard than “the hashes matched.” filefold changes a file only when it can re-prove the properties it promises at mutation time.

• Exact, not similar. Data forks and resource forks are compared byte for byte before mutation.
• Fail closed. Unsupported filesystems, metadata, links, changed identities, races, and ambiguous recovery states are skipped or stopped—not guessed through.
• Recoverable replacement. Every mutation is durably journaled around atomic APFS operations.
• Explicit deletion authority. Originals are retained by default; removing a verified backup requires --execute or finalize --delete-old.
• Inspectable and auditable. Dry runs explain outcomes, transaction state survives crashes, and completed operations retain checksummed audit records.
• Tested where it matters. Deterministic crash models, fault injection, mutation testing, and disposable APFS swarms exercise production recovery logic.

Read the complete safety contract and its requirement-to-test evidence.

How it works

1. Scan — find exact duplicate groups without changing files.
2. Preflight — repeat execution-like eligibility and accounting checks.
3. Reclaim — replace independently allocated duplicates with APFS clones through a recoverable transaction.
4. Verify — re-check content, metadata, identities, and clone-family evidence before completion.

Already-shared clones are recognized rather than counted as new savings. Reports distinguish logical duplicate bytes, existing sharing, maximum additional logical savings, and APFS private-byte estimates. Because snapshots and filesystem allocation affect observed free space, filefold never claims guaranteed physical savings.

Quick start

filefold requires macOS on APFS and Rust 1.85 or newer.

cargo build --release --locked
install -m 755 target/release/filefold /usr/local/bin/filefold

Start read-only:

# Discover exact duplicate groups.
filefold scan ~/Projects ~/Archives

# Run execution-like checks without creating clones or journals.
filefold reclaim --dry-run ~/Projects ~/Archives

# Inspect APFS allocation, clone information, and metadata eligibility.
filefold inspect ~/Archives/example.mov

The safest mutating workflow retains every original backup for separate review:

filefold reclaim --keep-old ~/Archives
filefold transactions
filefold finalize TRANSACTION_ID --delete-old

Or perform verified replacement and deletion as one recoverable operation:

filefold reclaim --execute ~/Archives

Execution stops on the first uncertainty. Never manually delete .filefold-old-* files or edit transaction records; use filefold recover after an interrupted operation.

What filefold does not do

• It does not delete files merely because they are duplicates.
• It does not detect similar photos, videos, or documents.
• It does not reclaim across different APFS volumes or on non-APFS filesystems.
• It skips symlinks, hard-linked files, unsupported flags, and unsupported metadata cases.
• It cannot promise that logical duplicate bytes equal an immediate increase in Finder free space.
• It is a focused command-line utility, not a general-purpose Mac cleaner.

Documentation

• Usage and recovery — commands, accounting, transaction recovery, and JSON output
• Safety contract — mutation authority, race protection, journaling, and compatibility
• Development and releases — tests, fuzzing, benchmarks, and local packaging
• APFS system testing — disposable-volume matrix and replayable swarms
• Safety requirements — stable guarantees mapped to regression evidence
• JSON schemas — versioned machine-readable output contracts

License

MIT