Versions in motion: how to preserve document versions
In my introduction to the macOS document versioning system, I explained that a document could lose all its saved versions when moved to another volume. This sequel provides more detail about how you can preserve or lose those saved versions.
When you save the first version of a document, a record is created in the hidden database on the same volume as that containing that document. That record refers to the file not by its name or path, but by its inode, its unique file system number. Anything that preserves that inode number will thus tend to keep its saved versions; anything that creates a new file with its different inode number is guaranteed to lose all versions.
What’s safe
The following actions are version-safe:
- moving the file anywhere within the same volume;
- renaming the file, changing its permissions, adding extended attributes, adding a custom icon, or editing the file’s data;
- creating a Finder Alias or symbolic link to the file;
- rolling back a local snapshot, which will return the versions to the same state as at the moment that snapshot was made; volume snapshots include the whole version database, and preserve inode numbers;
- ‘cloning’ the whole volume to make an identical copy of everything in it;
- if the file is stored inside a disk image, then that disk image can be copied or moved safely, or backed up; that also applies to files stored inside Virtual Machines.
What loses versions
The following actions are destructive of versions:
- moving the file to a different volume; the original file on its original volume will retain its versions, but they won’t copy across to the new volume;
- duplicating the file; the duplicate, an APFS clone file, will have no versions at all;
- saving the file as a new file, with a Save As command;
- compressing or archiving the file; the copy in the archive won’t have any versions;
- saving the file to a file system like ExFAT or MS-DOS, which don’t support versions;
- backing the file up to another volume, as versions can’t even be backed up by Time Machine;
- moving or copying the file over a network.
If you try to save versions on a file system that doesn’t support them, you aren’t warned when saving those versions, as those appear to remain cached. Normally the first warning is given when you try to close the file.
If you want to keep versions, click on Cancel and save that file to a volume that does support versions.
The version database can only be created on a volume that has sufficient space to support it. This doesn’t normally affect working with regular APFS volumes, but can be a problem if you’re intending to store the file in a disk image or sparse bundle. You should find that a minimum size of 1 GB will support limited versions, but 500 MB is definitely too small for support, and will result in a warning when you try to close the file.
iCloud Drive
The behaviour of versions in iCloud Drive might appear confusing unless you remember the rule that they are saved for that file’s inode number. Here I’ll look at the example of a file that’s in a different folder from iCloud Drive (or Documents in iCloud) and is moved to iCloud Drive.
If that file is already in the current Data volume, that’s the same volume as local copies of what’s in iCloud Drive, so moving it to iCloud Drive keeps it within the same volume, and versions are preserved. If that file is evicted from local storage, that only removes the data for that file, and doesn’t change its inode number. When the file is downloaded again and opened, its versions are still there.
On another Mac connected to the same iCloud Drive, though, the versions are on a different volume on another Mac, so if that opens the file, there are no saved versions available. If that Mac adds its own versions to the file, they will be saved locally, and will be accessible to that Mac.
Saving versions to files already in iCloud Drive is more complex, as different versions of macOS, iOS and iPadOS have saved some into iCloud, so I will look at that in a separate article.
Preserving versions whatever
The only way that I know to preserve all the versions of any file is to save each of them individually in a folder, numbered so that the original versions can be recreated on another volume. While you can use my utility Revisionist to do that, a simpler drag-and-drop approach is provided by Versatility.
There’s no screenshot to show: all you do is drag a file with versions onto Versatility’s blue landing pad. You’ll then be prompted to name and locate the folder it creates containing the file’s versions. Once made, you can move them around like any other Mac folder, back them up, Zip the folder and send it to a colleague.
To reconstitute the original, simply drop the folder onto Versatility’s pad. You’ll then be prompted for the name and location of the file to be saved. That file will contain all the versions saved in the original, ready to use.
If you wish, you can edit the versions in the archive folder created by Versatility. When the file is reconstituted the individual versions will simply be reassembled in numerical order.
I’m also delighted to confirm that both Versatility and Revisionist are fully compatible with macOS Sequoia.
Key point
Versions are linked to the inode number of their file. Actions that preserve that on the same volume should retain those versions. Anything that creates a new inode number or uses a different volume won’t retain those versions.