This is kind of a sister function to hard links, which similarly avoid copying the file’s contents but where modifications apply to all copies. See also this article on the differences, including versus aliases and symlinks.

Copy-on-write is beneficial for several reasons:

• Copies don’t take up any significant space (just whatever tiny amount is necessary for their metadata).
• The initial copy operation is practically instantaneous (just a few small metadata writes & updates).
• Deferring (if not entirely avoiding) the actual disk I/O reduces wear on the disk.
• The copies can share common segments, saving disk space even when they’re not ultimately identical copies.

It does have some potential downsides:

• You don’t get the increased data redundancy and error resilience that actual copies provide (although if you’re aiming for data redundancy or backup, you should be using separate physical disks anyway).
• It can make subsequent modifications of the file slower, as even just modifying a single byte can trigger the actual copy to be performed.

And some basic limitations:

• It’s only supported on APFS (and maybe additional file systems added by 3rd party extensions, but I haven’t tested nor can I find any accounts of this).
• It only works within individual volumes (it doesn’t work even between two volumes in the same APFS container, or sharing the same physical disk).

Contrary to what I saw online in a few places, copy-on-write works on all APFS volumes, irrespective of whether they are backed by SSDs, HDDs, or some other type of storage.

Should I use it?

Yes!

For most purposes those downsides aren’t an issue, and the limitations merely mean that it’s wise to have a fallback option (of just copying the actual file contents) whenever copy-on-write isn’t available. And many of the tools & APIs fallback automatically (unless you explicitly require them not to, such as with COPYFILE_CLONE_FORCE to copyfile).

How do I use it?

Testing method

Not that this is interesting, just for posterity and to show my work a bit, in case I made a mistake.

I created large-enough files on each of my test volumes (APFS on SSD, APFS on HDD, HFS+ on SSD) that an actual copy would take tens of seconds at least, using dd e.g.:

I then ran the various command line tools on these files, attempting to clone the file to a different name in the same folder, and observed disk I/O activity with Activity Monitor and iStat Menus.

For actual copy-on-writes I would observe that the program successfully concluded practically instantly, and there’d be at most a small blip of disk writes (for metadata modifications).

For failed copy-on-writes I would observe that the program would not exit promptly and I’d see voluminous disk writes (hundreds of megabytes to gigabytes per second, depending on the disk, sustained for many seconds until I was satisfied with the results and killed the test).

For API tests the overall approach was the same, but the APIs were invoked from inside swift repl where possible, and from a throw-away Swift script otherwise³.

1. I haven’t tested it, but as far as I’ve heard APFS does not actually check if the modifications actually diverge the files. e.g. if you “modify” a byte of the file to the value it already has – a pointless but technically possible operation that leaves both copies still identical – APFS will still copy the modified block.
   
   Furthermore, APFS & Apple’s operating systems appear to have no tools (nor APIs) to deduplicate files – e.g. to detect full or partial copies and deduplicate their actual storage on disk. Not even tools that you could invoke manually if you do the hard work of first determining that two files’ contents are identical.
   
   APFS / Apple’s operating systems rely entirely on user applications using copy-on-write explicitly and upfront. ↩︎
2. Curiously, clonefile first shipped in macOS 10.12 (Sierra), according to its man page, which is the release preceding the introduction of APFS in macOS 10.13 (High Sierra). Yet, as far as I can tell HFS+ doesn’t and never did support cloning – nor do any of the other file systems supported by macOS 10.12 (e.g. FAT16 & FAT32, exFAT, NFS). It’s possible it was just convenient for Apple to include it in the prior release as they were probably testing APFS with it internally, during APFS’s development.
   
   Update: Michael Tsai pointed out that Sierra included APFS support in beta form (e.g. you could create disk images with it, but not use it for a boot disk). Thus why clonefile (and other APFS-related tools) were included in Sierra. ↩︎
3. While the C APIs worked just fine inside swift repl irrespective of what volumes I was targeting, the Foundation APIs oddly refused to work whenever the files were not on the boot volume, throwing “Operation not permitted” errors (NSCocoaErrorDomain 513, with no user info). If it weren’t for the C APIs working just fine I’d think it’s a sandboxing issue, but clearly it’s not (and swift repl -disable-sandbox makes no difference). 🤔 ↩︎

Curiously there’s very little information out on the web (at time of writing) on how to create (or expand) a Fusion Drive without erasing its contents first.  It’s entirely possible to do so – in some circumstances – and is probably what most people want, yet almost every ‘create your own Fusion Drive’ guide presumes you’re happy losing all your data in the process. 🤪

So here’s how to do it, step-by-step.  The process is fairly straightforward, but there are some edge cases that might apply to you.  The obvious & most common ones are covered by this guide, but if you find yourself in a situation that isn’t, please leave a comment at the bottom of this guide explaining what’s not working for you, and I’ll try to help you out.

Don’t be intimidated by the length of this guide – in the common case it’s only six steps, each a single operation, and someone familiar with the steps involved can complete this whole process in just a couple of minutes.  The verbosity of this guide is because it takes great pains to explain precisely what’s going on in order to prevent confusion & error.  Read it carefully, and take it slow – there is no undo option for any of these commands.

Seriously important warning

⚠️Manipulating your computer’s storage at the low level described in this guide is dangerous.  In principle it’s safe as long as you enter all the right commands.  However, a single typo in the wrong place can destroy all your data – e.g. a ‘2’ instead of a ‘1’ when typing a disk identifier.  Furthermore, in practice Apple’s tools are not completely reliable, and it’s possible that even with you doing everything exactly right, something will still go wrong and your data might be lost.

Make sure all of your data is reliably & verifiably backed up before attempting any of this.  Make sure your backups are not connected to your computer while you attempt this – if they are, they’re also just one typo or software bug or hardware glitch away from being destroyed too.

It’s recommended that you disconnect all other disks while you go through this process.  That way you eliminate the possibility of damaging them, whether as the result of a typo, confusion between similar disks, or a software bug.

A quick word on critical terminology

• “Volume” in this context is what you might casually call a “disk” – it’s what you see as a disk icon on your desktop, for example, or listed under the ‘Devices’ section in the Finder window sidebars.
  
  All Macs have at least one volume – the boot volume, usually the internal SSD, Fusion Drive, or hard disk – but you can of course add any number more of them via USB, Thunderbolt, Firewire, or even internally if you have an old enough Mac.
  
  “Volume” is used rather than “disk” because the latter is ambiguous – lots of things are called “disks”, including many things that aren’t actually disks in any physical or practical sense.  But “volume” has a specific meaning in the Mac storage lexicon, and you’ll see the word used frequently by Apple’s tools.  There are different types of volumes – “physical”, “logical”, etc.  For the most part you don’t need to worry about those distinctions here – it’ll be pointed out specifically if & when you do.  Similarly there are related constructs like “volume groups” and “volume families”, but likewise you don’t need to know exactly what those mean for the purposes of this task.  Just be aware that these distinctions exist, and read the instructions very carefully to see exactly which one is needed – particularly when dealing with UUIDs, as you’ll see.
• “Disk” is thus used only to refer to physical disks – things you can hold in your hand.  A disk can contain many volumes (sometimes called partitions).
• “Target volume” is used to denote the particular volume you want converted into a Fusion Drive.  It should be your existing volume, the one with your data already on it – data that you want preserved.
• “Additional disk” is used to denote the SSD (or similar) that you want to fuse into your target volume, to create your Fusion Drive.  In contrast to your target volume, its contents will not be preserved.  Make sure you move any data on that disk somewhere safe before starting this process.  Also note the distinction between disk and volume here – you can only add whole disks to Fusion Drives, not volumes – if your additional disk has multiple volumes on it (e.g. a Boot Camp partition in addition to a Mac volume) all of those will be erased during the fusion process.

Procedure

1.  Open Terminal.

All of the following commands are entered in Terminal, unless otherwise specified.  If you’re an admin user you won’t need to do anything more than what’s listed here, nor enter your login password at any point (nor, similarly, use sudo at any point).  If you’re not an admin user, you might be prompted for an admin’s credentials, or you might have to run all the following commands via sudo (ideally as an admin, or as root if necessary).

2.  List your existing Core Storage volumes.

Enter the following command in Terminal:

diskutil cs list

The output will ideally look something like:

CoreStorage logical volume groups (1 found)
|
+-- Logical Volume Group CF936785-3F07-4414-8512-F94E26F0ABC3
   =========================================================
   Name:         Macintosh HD
   Status:       Online
   Size:         6000831135744 B (6.0 TB)
   Free Space:   15101952 B (15.1 MB)
   |
   +-< Physical Volume C68C0FB4-B85F-4376-B9C4-BC744520A5FA
   |   ----------------------------------------------------
   |   Index:    0
   |   Disk:     disk99s2
   |   Status:   Online
   |   Size:     6000831135744 B (6.0 TB)
   |
   +-> Logical Volume Family 33A1CC8F-A3AF-4B5D-8EA0-379F4C9D6D0E
       ----------------------------------------------------------
       Encryption Type:         AES-XTS
       Encryption Status:       Unlocked
       Conversion Status:       Complete
       High Level Queries:      Fully Secure
       |                        Passphrase Required
       |                        Accepts New Users
       |                        Has Visible Users
       |                        Has Volume Key
       |
       +-> Logical Volume 10DE6E37-6701-46F8-8E1F-42759C42B5A0
           ---------------------------------------------------
           Disk:                  disk100
           Status:                Online
           Size (Total):          6000471965696 B (6.0 TB)
           Revertible:            No
           LV Name:               Macintosh HD
           Volume Name:           Macintosh HD
           Content Hint:          Apple_HFS

If you see your target volume in there as a Logical Volume – e.g. like “Macintosh HD” in the above example – then you’re all set to move on to step 3, making note of two things:

1. The target logical volume’s UUID (10DE6E37-6701-46F8-8E1F-42759C42B5A0 in the above example).  You’ll need this in step 6.
2. The target logical volume’s volume group UUID (CF936785-3F07-4414-8512-F94E26F0ABC3 in the above example).  You’ll need this in step 5.

If instead there are no volumes listed, or your target volume isn’t one of them, then you will need to perform the extra steps below.

If your target volume’s name does appear, but not on any Logical Volume – perhaps only as a Logical Volume Group – then do not proceed; your scenario is not covered by this guide.  Please leave a comment at the bottom of this guide, so I can help you figure out what’s going on and what to do in your specific circumstances.

2B.  List non-Core Storage volumes.

diskutil list

You’ll see a list of one or more disks & their constituent volumes, e.g.:

/dev/disk99 (internal):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      GUID_partition_scheme                         6.0 TB     disk99
   1:                        EFI EFI                     314.6 MB   disk99s1
   2:                  Apple_HFS Macintosh HD            6.0 TB     disk99s2
   3:                 Apple_Boot Boot OS X               134.2 MB   disk99s3

Make sure your target volume appears somewhere in that list.  If it doesn’t… then I’m not sure what to tell you – your target volume appears to not be connected to your computer.

You’d typically be using Core Storage as a side-effect of encrypting your volumes (iff they’re HFS-formatted), or if you’re using Apple’s software RAID.  If your target volume is APFS-formatted, however, and it’s not already using Core Storage underneath, you might be out of luck – you can try following 2C Option 2 below on the APFS Container volume, but I haven’t tried it myself so I don’t know if Apple’s tools support it (nor whether they can do the conversion correctly & reliably – proceed at your own risk).

2C Option 1:  Encrypt your target volume.

The easiest and most fool-proof way to do this is to right-click on the target volume anywhere it appears in the Finder, and choose the ‘Encrypt “<volume name>“…’ option from the contextual menu.  You’ll be prompted to enter a passphrase with which to encrypt the volume, and the operation might take some time, depending on the speed & size of your target volume.

This is also an excellent option because you should always encrypt your volumes, for your own security & privacy.

Alternatively, you can use Terminal:

diskutil cs convert <disk identifier> -stdinpassphrase

The disk identifier is the name associated with your target volume that looks like “diskXsY” where X & Y are numbers (e.g. disk99s2 in the prior example).

You’ll be prompted to enter the passphrase to encrypt the volume with.

Again, the operation might take some time, depending on the speed & size of your target volume.

2C Option 2:  Convert your target volume to Core Storage without encrypting it.

diskutil cs convert <disk identifier>

The disk identifier is the name associated with your target volume that looks like “diskXsY” where X & Y are numbers (e.g. disk99s2 in the prior example) – see under the ‘IDENTIFIER’ column in the output of diskutil list from step 2B.

The operation might take some time, depending on the speed & size of your target volume.

2D.  Verify the conversion succeeded.

diskutil cs list

As per the instructions in step 2, you should see your target volume now listed as a Logical Volume.

3.  Determine your additional disk’s identifier.

This is the disk you want to fuse into your target volume in order to create your Fusion Drive.  It will ideally be blank to begin with – e.g. you just bought it & connected it to your computer, and have no yet formatted it or otherwise used it.

If it is not blank, you need to move all your data off of it – it will be essentially erased as part of the fusion process (your target volume won’t be, so potentially you can move the data to there).

Also note the distinction between disk and volume here – you can only add whole disks to Fusion Drives, not volumes – if your additional disk has multiple volumes on it (e.g. a Boot Camp partition in addition to a Mac volume) all of those will be erased during the fusion process.  Make sure to move your data off of all those volumes.

To determine the disk identifier for your additional disk, run:

diskutil list

The output should look something like the following:

/dev/disk99 (internal):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      GUID_partition_scheme                         6.0 TB     disk99
   1:                        EFI EFI                     314.6 MB   disk99s1
   2:          Apple_CoreStorage Macintosh HD            6.0 TB     disk99s2
/dev/disk100 (internal, virtual):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:                  Apple_HFS Macintosh HD           +16.0 TB    disk100
                                 Logical Volume on disk99
                                 10DE6E37-6701-46F8-8E1F-42759C42B5A0
                                 Unlocked Encrypted
/dev/disk101 (external, physical):

In the above example, the last entry is the additional disk – it has the disk identifier disk101.  In this example it is not formatted, so it has no volumes listed on it.

4.  Check that you’ve identified the correct additional disk.

diskutil info <disk identifier>

The output should look something like:

   Device Identifier:        disk101
   Device Node:              /dev/disk101
   Whole:                    Yes
   Part of Whole:            disk101
   Device / Media Name:      CT2000MX500SSD1

   Volume Name:              Not applicable (no file system)
   Mounted:                  Not applicable (no file system)
   File System:              None

   Content (IOContent):      GUID_partition_scheme
   OS Can Be Installed:      No
   Media Type:               Generic
   Protocol:                 SATA
   SMART Status:             Verified

   Disk Size:                2.0 TB (2000398934016 Bytes) (exactly 3907029168 512-Byte-Units)
   Device Block Size:        512 Bytes

   Read-Only Media:          No
   Read-Only Volume:         Not applicable (no file system)

   Device Location:          External
   Removable Media:          Fixed

   Solid State:              Yes
   Virtual:                  No
   Hardware AES Support:     No

Check that info to make sure it matches what you’re expecting – in particular things like the device / media name (model number), and the disk’s size.  Be extremely careful if you have multiple disks connected to your computer of the same type or size – remember that this disk will be erased during the fusion process, so you definitely do not want to pick the wrong disk by mistake.  If in doubt – in fact as a best practice regardless – disconnect all other disks first, to ensure you can’t target them by mistake.

5.  Add your additional disk to your target volume’s Core Storage volume group.

diskutil cs addDisk <target logical volume's volume group UUID> <additional disk's identifier>

If all goes well, you’ll see something like:

Started CoreStorage operation on disk101
Unmounting disk101
Repartitioning disk101
Unmounting disk
Creating the partition map
Rediscovering disk101
Adding disk101s2 to Logical Volume Group
Switching disk101s2 to Core Storage
Waiting for Logical Volume Group to come back online
Core Storage PV UUID: D0E04199-9402-46EF-8481-98C8BADEF8FE
Finished CoreStorage operation on disk101

If you wish you can also confirm that the logical volume group now has your additional disk listed as a physical volume underneath it:

diskutil cs list

You should now see something like:

CoreStorage logical volume groups (1 found)
|
+-- Logical Volume Group CF936785-3F07-4414-8512-F94E26F0ABC3
   =========================================================
   Name:         Macintosh HD
   Status:       Online
   Size:         6000831135744 B (6.0 TB)
   Free Space:   15101952 B (15.1 MB)
   |
   +-< Physical Volume C68C0FB4-B85F-4376-B9C4-BC744520A5FA
   |   ----------------------------------------------------
   |   Index:    0
   |   Disk:     disk99s2
   |   Status:   Online
   |   Size:     6000831135744 B (6.0 TB)
   |
   +-< Physical Volume D0E04199-9402-46EF-8481-98C8BADEF8FE
   |   ----------------------------------------------------
   |   Index:    1
   |   Disk:     disk101s2
   |   Status:   Online
   |   Size:     2000054960128 B (2.0 TB)
   |
   +-> Logical Volume Family 33A1CC8F-A3AF-4B5D-8EA0-379F4C9D6D0E
       ----------------------------------------------------------
       Encryption Type:         AES-XTS
       Encryption Status:       Unlocked
       Conversion Status:       Complete
       High Level Queries:      Fully Secure
       |                        Passphrase Required
       |                        Accepts New Users
       |                        Has Visible Users
       |                        Has Volume Key
       |
       +-> Logical Volume 10DE6E37-6701-46F8-8E1F-42759C42B5A0
           ---------------------------------------------------
           Disk:                  disk100
           Status:                Online
           Size (Total):          6000471965696 B (6.0 TB)
           Revertible:            No
           LV Name:               Macintosh HD
           Volume Name:           Macintosh HD
           Content Hint:          Apple_HFS

Note however that the logical volume – your target volume; your would-be Fusion Drive – is still listed as being the same, older size.  It’s not yet making full use of the additional disk you added – that’s the next & last step.

6.  Resize your target volume to make use of the new space from your additional disk.

Since Fusion Drives split data across their constituent disks (as opposed to mirroring it, as you might do in a RAID setup for improved reliability), their size is the sum of all the disks you put into them.  You can in fact have multiple volumes on a single Fusion Drive, splitting up its total space amongst them however you wish, and having them share all the underlying disks on a kind of first-come-first-served basis.  However, the details of that scenario are left as an exercise for the reader – here we’ll only look at the simple, most common example where you just have a single volume on your Fusion Drive.

diskutil cs resizeVolume <target volume's UUID> 0g

The target volume’s UUID was listed in the output of step 2, from the diskutil cs list command.

When you run the resizeVolume command, it will typically take a little while – it does some sanity checking & validation of the target volume first, to make sure it’s in good health to begin with, and then the resize operation itself can take a few moments.  You should see output similar to:

The Core Storage Logical Volume UUID is 10DE6E37-6701-46F8-8E1F-42759C42B5A0
Started CoreStorage operation
Verifying file system
Volume was successfully unmounted
Performing fsck_hfs -fn -x /dev/rdisk100
Checking Journaled HFS Plus volume
Checking extents overflow file
Checking catalog file
Checking multi-linked files
Checking catalog hierarchy
Checking extended attributes file
Checking volume bitmap
Checking volume information
The volume Macintosh HD appears to be OK
File system check exit code is 0
Restoring the original state found as mounted
Growing Logical Volume
Resizing Core Storage Logical Volume structures
Resized Core Storage Logical Volume to 8,000,242,745,344 bytes
Growing file system
Finished CoreStorage operation

You’re now done!  Your target volume is now a Fusion Drive, ready for use, and should reflect its new, enlarged size in the Finder and elsewhere.

Note:  the new total size shown for your Fusion Drive will be slightly less than the sum of the underlying disks – usually by a few hundred megabytes.  This is presumably because some space is reserved for Core Storage metadata and other essential system data.

I was quite disappointed to see that APFS isn’t even trying to provide data integrity.  Data integrity is kind of step 0 of any file system, and checksums or use of ECC is pretty much standard in modern & leading-edge file systems.  APFS doesn’t want to be one of those, it seems.

Case in point why this matters:

I have a bunch of old backup drives, because drives are cheap and until recently I could just buy a new one once the current one filled, instead of ever deleting a backup.  Periodically I go back through these old backup drives and do some basic integrity checks (S.M.A.R.T. bad block scans, file system checks, etc).

I also run a comparison of key data between those backups and the current versions on my computer, for files which generally shouldn’t change nor disappear – e.g. photos, videos, key documents, etc.

And today I found that at least half a dozen valuable personal videos (and a few photos) were corrupt, in the versions on my computer.  Luckily, the versions in the ancient backups were still good, so I could replace the corrupt ones.

This corruption was completely silent, until my ‘paranoid’ and time-consuming checks discovered it.

It’s far from the first time.  A failing drive years back corrupted a huge portion of my music library – silently, as far as the file system & OS were concerned.  Periodically I’ve discovered photos (of which I have huge numbers – the majority of my data) which have become corrupt at some indeterminate point.  And I’ve of course had file system [metadata] corruption occur many times, sometimes requiring complete erasure of the disk, and recovery or rebuilds from backup (a few times I’ve had to use data recovery software, where backups weren’t available).

Most, if not all, of these issues would have been discovered by even the most trivial file integrity protections, in the file system.

The notion that modern disks somehow magically protect against all silent data corruption is abject poppycock.  They’re more likely to suffer from it than older disks – a byproduct of higher densities and market demand for cheaper, crappier storage products.

And the implicit assertion that Apple’s file system driver, and kernel overall, are somehow completely free of bugs… is just batshit crazy.

Addendum

Since Apple aren’t interested in protecting anyone’s valuable personal data, I’m on the look-out for other options.  Manual use of shasum is one, for now, but a more streamlined and fool-proof system would be better.  Alas, none seems to exist[1. There is chkbit, but it relies on MD5… probably acceptable for this use case, but needless in the face of decades of better hash algorithms.  And it’s written in JavaScript.  Ew.].  Yet.