Does macOS Sonoma have problems with union mounts?

In Monday’s article about file systems in macOS, I mentioned one, the union file system or union mount, that I had expected to be compatible with APFS, but didn’t work for me. Although others share that expectation, I’ve now undertaken further tests confirming my suspicion that in Sonoma 14.4.1 it doesn’t work as advertised.

How union mount should work

In macOS, union mounts can’t be achieved in the Finder or even Disk Utility, but require the command line. Let’s say you have two APFS volumes unimaginatively named Volume1 and Volume2. Although currently unmounted, they are devices /dev/disk8s2 and /dev/disk8s3 respectively. If you then mount them at a folder named union, either in /Volumes where regular volumes are mounted, or in a temporary mount point at /tmp/union, then you can create a union mount from them, using commands like
mount -t apfs -o union /dev/disk8s2 /Volumes/union
mount -t apfs -o union /dev/disk8s3 /Volumes/union

If you then list the contents of /Volumes/union, you should see the items on both volumes merged together as if in a single volume. This has many applications, among them being the ability to effectively replace files on volumes that can’t be changed. That occurs to resolve the problem of items on both volumes having the same name. Let’s say that both volumes had a file named this.text. To resolve the conflict, only one of them is exposed in the union mount, that on the second (or last) volume overlaid in the union, in this case Volume2.

Test

To test this out, create two volumes with different names, in plain APFS format. Add a couple of text files to each as shown in the screenshots.

When we join these two volumes in a union mount, we’d therefore expect to see the contents as:

a.text containing 1, from Volume1
b.text containing 2, from Volume2, overlaid on Volume1
c.text containing 2, from Volume2

Reverse the order of the commands creating the union mount, and b.text should be overlaid with the file from Volume1, thus contain 1 rather than 2.

Results

First we create the union folder in /Volumes
sudo mkdir /Volumes/union
One nuisance here is that won’t persist when the union mount is unmounted, and has to be recreated each time, although a mount point at /tmp/union does persist.

If the two volumes are currently mounted, they first have to be unmounted, and their device IDs checked ready for use in the mount commands:
sudo mount -t apfs -o union /dev/disk8s2 /Volumes/union
sudo mount -t apfs -o union /dev/disk8s3 /Volumes/union
where -o union should create the union mount.

If you then list the union mount using
ls /Volumes/union
all you’ll see are the contents of Volume2
b.text c.text

The Finder is more confusing, though, as it shows both volumes as having identical contents, here Volume1 being exactly the same as Volume2.

If you then unmount both volumes, something that can take a bit of doing, as they may be ‘busy’ at first, recreate the union mount point in Volumes, then repeat the commands in the reverse order
sudo mount -t apfs -o union /dev/disk8s3 /Volumes/union
sudo mount -t apfs -o union /dev/disk8s2 /Volumes/union

What you’ll see is Volume1, not the union, when listed using
ls /Volumes/union
showing the contents of Volume1 alone:
a.text b.text

This time, the Finder shows Volume2 as having the same contents as Volume1.

I have repeated this using Disk Images in APFS format instead of real volumes, and using /tmp/union as the mount point, and the results are identical every time, on both Apple silicon and Intel Macs.

What good are union mounts?

Wikipedia gives one good example that is readily extended to other situations. Say you have a read-only volume such as an optical disc, but want to make updated contents available. Rather than having to burn a new disc, you can union mount a writeable volume containing the updates over it. The union of both volumes will then effectively be an updated single volume.

If you can spot my unintentional errors in trying to create union mounts, I’d be most grateful if you’d point them out. Otherwise, I can only assume that macOS Sonoma 14.4.1 has a bug in union mounts.