In my last account of the macOS version system, I looked in detail at how versions are now essentially ignored by iCloud, but didn’t consider other forms of sharing, such as macOS shares and those on networked storage such as a NAS. This article tries to complete the account, and suggests how you can ensure that a document’s versions are preserved wherever they might go.

Non-native file systems

The version system depends on the hidden and locked top-level folder .DocumentRevisions-V100 on the same volume as the document. Although Apple doesn’t disclose any information about what’s in the folder, it appears to include components such as bookmarks which are file-system dependent. While macOS is happy to create and maintain the version database on APFS and HFS+ volumes, it refuses to attempt this on non-native file systems such as ExFAT.

If you create a new document on a non-native file system, macOS continues to retain versions in memory, perhaps supported by cache files on your current Data volume. Changes are saved normally, but when you come to close the file, you’re warned that versions can’t be saved because the document “is on a volume that does not support permanent version storage.”

If you continue and close the document, only the current version will be accessible, and any attempt to access old versions by browsing all versions through the Revert To sub-menu will fail. Typically, these result in a Time Machine error, reported erroneously as an “Error retrieving versions from Time Machine”.

Of course, this error is itself an error, and probably occurs because Time Machine and the version system use the same error codes with different meanings. This could mislead you into thinking the problem lies with Time Machine, which isn’t needed to support the version system at all.

Shared folders

When sharing a folder on an APFS volume between Macs (both running macOS 12.5), both file systems are capable of supporting versions, but only the server has direct access to the version database of that volume. The result is that the macOS version system isn’t available on the client when it’s editing documents shared from the server. The effect is identical to that seen when using a volume with a non-native file system, as are the error messages: any existing versions are lost.

Disk images

One potential workaround for file sharing would be to store documents in a disk image on the server.

Fixed-size standard read-write Disk Images in APFS format can be suitable, but prove very inefficient because of the size required by the version database. It’s hard to estimate the free space needed to support that database, but it appears significantly larger than reported sizes. In tests involving less than six versions of a file of less than 15 KB, the version database ran out of room on a 100 MB Disk Image. Yet the estimated size of the whole version database remained below 500 KB.

Running out of space for the version database isn’t a good experience. Everything may seem fine until you come to close the document, at which point macOS warns of the space problem.

You’re then given the choice of leaving the document open and retaining its versions, which can’t be saved to disk, or closing the document and losing all those versions. If this happens to you in real life with an important document, there is no preferred option, as whichever you choose your document’s versions are doomed.

By far the best of the types of disk image available are those supporting sparse storage, either in a Sparse Bundle or a single-file Sparse Disk Image, as those will grow to accommodate the expanding version database. Provided they use a native file format (HFS+ or APFS), these work well with versions.

To preserve versions of a document in a shared folder, create a Sparse Disk Image or Sparse Bundle in that shared folder, attach and mount it on the client, and edit the document within that mounted volume. Versions will then be retained and made available to all clients and the server itself, within that disk image.

How to retain versions whatever

The current implementation of versions in macOS is fragile. One false move to a different volume, sharing over a network, or transfer to iCloud, and all previous versions are blown away.

One strategy which preserves versions robustly no matter what happens is to store the document(s) in a Sparse Disk Image or Sparse Bundle, and edit it within that. When transferred with a little care, you can even pass that over the Internet.

Conclusions

• Versions are fragile, and all too easy to lose.
• Versions are only supported on native file formats, APFS and HFS+, and not on ExFAT, etc.
• Versions aren’t supported over file shares, even between APFS volumes.
• The most robust way to retain versions is to encapsulate the document(s) in its own volume, using a Sparse Disk Image or Sparse Bundle, which will preserve them wherever it goes.