How to Merge Giant Folders on macOS in Milliseconds with Zero Storage Overhead

If you have ever dragged a folder into another directory with matching names on macOS, you know the sinking feeling in your stomach. Finder pauses, displays a modal dialog with three blunt choices: "Stop", "Replace", or "Keep Both".

Clicking "Replace" is catastrophic: Finder completely deletes the existing target folder before writing the new one, permanently wiping any unique subfiles that only existed in the target. Clicking "Keep Both" is barely better: it produces messy renamed folders like Photos (1), doubling disk usage and leaving you with the headache of manually sorting thousands of files.

"On modern NVMe SSDs, why are we still duplicating gigabytes of raw data blocks when our operating system's filesystem can clone files in milliseconds for zero extra bytes?"

When Apple introduced the Apple File System (APFS) in macOS High Sierra, it brought a fundamental architectural breakthrough: Copy-on-Write (CoW) extents. In this deep dive, we will explore how APFS extents work, examine the low-level Darwin C system call that powers instant cloning, and demonstrate how you can merge 50 GB+ folders safely without duplicating disk space.

1. The Anatomy of APFS Copy-on-Write (CoW)

On traditional filesystems (like FAT32, exFAT, or older HFS+), duplicating a file requires reading every single byte from disk into memory and writing it out to newly allocated physical sectors. A 50 GB 4K video or RAW photo shoot takes several minutes to duplicate, strains the SSD controller, and consumes 50 GB of valuable disk space.

APFS decouples file metadata (inodes) from data storage (extents):

• Inodes: Small records storing file permissions, ownership, timestamps, and extended attributes.
• Extents: Contiguous ranges of physical disk blocks where the file payload actually lives.

When you create an APFS clone, the kernel creates a new inode that points directly to the exact same physical block extents on your SSD. No file content is read. No payload is written to flash memory. Both files now share the exact same storage.

The "magic" happens when one of the files is later modified: the kernel allocates new blocks only for the altered bytes and updates that specific file's extent map. The unchanged data continues to be shared.

2. The Low-Level System Call: Darwin copyfile(3)

Many developers assume that calling standard Swift APIs like FileManager.default.copyItem(at:to:) will automatically use APFS cloning. Unfortunately, in practice, FileManager frequently falls back to standard block-by-block copying depending on attribute flags, sandboxing contexts, and permission masks.

To guarantee kernel-level Copy-on-Write extents, we must drop down to Darwin's native POSIX API in <copyfile.h> and pass the COPYFILE_CLONE flag:

import Darwin
import Foundation

func cloneFile(from sourcePath: String, to destinationPath: String) throws {
    let state = copyfile_state_alloc()
    defer { copyfile_state_free(state) }

    // Request native APFS extent cloning while preserving POSIX permissions
    let cloneFlags = copyfile_flags_t(COPYFILE_ALL | COPYFILE_CLONE)
    let result = copyfile(sourcePath, destinationPath, state, cloneFlags)

    if result != 0 {
        let err = errno
        // If the filesystem does not support cloning (e.g., target is exFAT or cross-volume)
        if err == ENOTSUP {
            // Fallback to high-speed buffered streaming
            let standardFlags = copyfile_flags_t(COPYFILE_ALL)
            let fallbackResult = copyfile(sourcePath, destinationPath, state, standardFlags)
            if fallbackResult != 0 {
                throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
            }
        } else {
            throw POSIXError(POSIXErrorCode(rawValue: err) ?? .EIO)
        }
    }
}

Understanding the Critical Flags:

• COPYFILE_CLONE: Instructs the APFS filesystem driver to perform extent-sharing cloning. If the operation cannot be completed via cloning, it returns -1 with errno = ENOTSUP.
• COPYFILE_ALL: Preserves file permissions, extended attributes (xattr), POSIX access control lists (ACLs), and creation timestamps.
• ENOTSUP Handling: If the destination is an external drive formatted in exFAT, FAT32, or a network SMB share, Darwin gracefully falls back to streaming copy without failing the batch.

3. Benchmarking: Traditional Copy vs. APFS Clone

To measure the performance difference, we benchmarked merging a real-world photo archive containing 1,200 RAW files (48.6 GB total) on a MacBook Pro with an M-series Apple Silicon chip and internal APFS SSD:

4. The Danger of Silent Overwrites: Why Reversibility Matters

While APFS cloning solves the speed and storage problem, it introduces a severe safety risk if implemented naively: What happens when a file with the same name already exists in the destination folder?

If you blindly clone over an existing file, the original destination file's extent pointer is deleted. If you made a mistake and replaced a newer edit with an older file, that file is gone forever.

To make directory merging genuinely safe for production workflows, a merge system must enforce two architectural invariants:

1. Strict Read-Only Source: The source folder must never be modified under any circumstances. No deletes, no renames, no metadata changes.
2. Atomic Rollback Snapshots: Before overwriting any conflicting file in the destination folder, the destination file must first be archived into a hidden, timestamped snapshot journal.

5. How DirMerge Packages This into a Native Mac App

Building raw shell scripts with copyfile is great for quick terminal hacks, but handling nested directories, symbolic links, file permissions, diff classification, and safety rollbacks across millions of files requires a purpose-built native tool.

We designed DirMerge 2.0 from the ground up in pure Swift 6 and SwiftUI to solve this exact challenge:

• Single-Window Workbench: Drag and drop your Source and Target folders side by side.
• Diff Tree Categorization: Instantly categorizes files into New, Conflicting, and Identical with live search.
• 100% Offline Sandbox: Strictly respects Apple App Sandbox rules. We intentionally omitted network permissions (com.apple.security.network.client), ensuring absolute privacy.
• Featherweight Native Architecture: Starts in 0.08 seconds, weighs only 1.3 MB, and consumes less than 25 MB of RAM.