Support for document versions in iCloud Drive has a curious history. Both iCloud Drive and the macOS versioning system were introduced in OS X 10.7 Lion, in 2011, but haven’t fully integrated over those 14 years. Until 2018, versions were only saved locally and never propagated to other Macs and devices through files shared in iCloud Drive. Then sharing of versions was added, but proved patchy and unreliable, although sometimes versions were propagated in a frenzy. By 2023, that experiment had ended, and behaviour reverted to the original. This article explains how it works now.
Demonstration
To show this, I used Versatility to convert a Pages document into a folder containing each of its seven versions, and moved that folder into iCloud Drive. Once there, I dragged and dropped that folder onto Versatility again to convert it back to a versioned Pages document in my iCloud Drive folder. I then dropped that onto Revisionist to browse those versions and confirm that they remained good.
Although the current version is located in iCloud Drive, with a path from ~/Library/Mobile Documents/com~apple~CloudDocs/, each of its previous versions ‘has local contents’ in a path from /System/Volumes/Data/.DocumentRevisions-V100/PerUID/501/, inside the Data volume’s version database.
On another Mac connected to the same Apple Account and iCloud Drive, that document only has the current version, again with ‘local contents’, as its previous versions are left stored on the other Mac.
If you then edit that document on the second Mac and save a new version there, then make more changes and save another version, those previous versions will remain stored in the second Mac’s version database, but only the current version will be synced to iCloud Drive, and appear as the current version on the first Mac. That still sees the six previous versions stored there from before, but can’t see those added by the second Mac.
Conclusion
Thus each Mac and device – as this applies similarly to versions saved in iOS and iPadOS – sees the common current version synced across iCloud Drive, and only those older versions created and saved on that Mac or device. There is no sharing of document versions in iCloud Drive.
While this behaviour is reliable and consistent, unlike the profusion of versions that occurred in macOS Mojave, it demonstrates how readily versions are discarded when they could or perhaps should have been preserved.
Beware Sonoma
In this respect, I have one important warning concerning versions and iCloud Drive: never use those in macOS Sonoma 14.4. That version of macOS has a serious bug that strips all local versions from any document that’s evicted (its download is removed) from iCloud Drive. Apple fixed that swiftly in the update to 14.4.1, so if you are still using Sonoma, ensure it’s 14.4.1 or later.
How to transfer document versions through iCloud Drive
If you need to work on a document with shared versions, the only solution is clumsy but effective, using Versatility. Keep the live document outside iCloud Drive, in local storage, and transfer it in iCloud Drive using its folder archive generated by Versatility:
Edit the local document on Mac A. To transfer it, drop it on Versatility and save its folder archive to iCloud Drive.
On Mac B, drop the folder archive in iCloud Drive onto Versatility, and save that to its local location for editing there.
To return the live document to Mac A, drop it onto Versatility, and save its folder archive to iCloud Drive, ready to reconstitute on Mac A.
Postscript: Use a disk image
I’m very grateful to @Remo_Pr0 for suggesting an alternative method: save the document in a disk image that you keep in iCloud Drive. Provided that’s larger than 1 GB (smaller sizes are unable to create a local version database), versions will be saved inside the disk image, and preserved for all those Macs that access that document within it. This should also work with a sparse bundle either in iCloud Drive, or in a network share.
If you can think of a better way, please let me know so I can code it into Versatility.
Time Machine and other backup utilities don’t back up absolutely everything. The list of folders and files that don’t get saved in your Mac’s backups is long, and hidden away out of sight. For Time Machine that used to be in /System/Library/CoreServices/backupd.bundle/Contents/Resources/StdExclusions.plist but now in .exclusions.plist at the top level of any backup. This article explains the more important in that list, and others that could trip you up. I’ll consider these according to the categories in that file.
TM Backup Exclusions
apiExclusionPaths
These are added by individual third-party apps, by setting the isExcludedFromBackupKey URLResourceKey for that file every time it’s saved. Otherwise this category might be empty.
standardExclusionPaths
This is a long list of standard paths that are set by macOS as not for backup, including:
.DocumentRevisions-V100 – the version database on each volume, added to this list in Big Sur,
.Spotlight-V100 – Spotlight metadata including indexes, which will be regenerated after restoring a volume,
.Trashes – the contents of all Trash folders,
.fseventsd – the File System Events database,
/Library/Logs – traditional text log files, not those for the Unified log which are included in backups,
/Users/Guest – any guest user files,
/private/var (partial) – various transient files,
among many other ephemeral items.
Of those, only one results in any significant loss of data, the version database. Although this was dutifully copied by Time Machine into backups for several years, the current structure of that database makes it impossible to restore successfully, even when restoring a complete volume. By the middle of the Catalina cycle, it had become a frequent cause of Time Machine choking, so was added to the standardExclusionPaths for Big Sur. As far as I’m aware this was never fixed in Catalina.
stickyExclusionPaths
These are items with an extended attribute of type com.apple.metadata:com_apple_backup_excludeItem attached, including various database and related files inside Photos Libraries. In the event that a library is restored from a backup, they’re freshly regenerated from the library’s contents.
Another interesting exclusion here is the Siri Analytics database included in any sysdiagnose stored in the volume(s) being backed up, in the path
sysdiagnose[datestamp]/logs/SiriAnalytics/SiriAnalytics.db. Presumably that’s for privacy reasons.
systemFilesExcluded
This key is set to true to ensure the whole System volume is always excluded.
userExclusionPaths
These are exclusions the user has set using tmutil or in Time Machine settings, using the Options… button.
By default, volumes on external storage are automatically added to this exclusion list; if you want an external volume to be backed up by Time Machine then you’ll need to remove it from the exclusion list manually.
iCloud Drive
When backing up the current Data volume, by default all files in iCloud Drive that are downloaded to that Mac at the time the backup is made, will be included in that backup. However, any that have been evicted (their download has been removed) will not be backed up, as their data isn’t present locally on the Mac, and that file is dataless. To ensure that those are backed up, download them all prior to the backup starting, and ‘pin’ those you want to remain downloaded in future.
Local snapshots and backups
Any snapshots of a volume aren’t backed up, indeed they can’t be copied to another volume. The same applies to Time Machine backups.
Local snapshot exclusions
All items in the volume at the time a local snapshot is made are included in that snapshot. There are no exclusions from local snapshots, apart possibly from some obscure items internal to APFS.
Third-party backups
Mike Bombich gives a thorough and detailed account of what CCC doesn’t copy on this page. Other backup utilities should also provide full lists on their support site.
Replicated or ‘cloned’ volumes
These should also include the entire contents of the volume as if a snapshot.
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.
APFS has two special file types designed to economise on storage space: clone and sparse files. Clone files are two or more distinct files within the same volume whose data is shared; sparse files save space by skipping empty data and only storing data containing information. This article explores how they behave in use, with particular emphasis on Time Machine backups and iCloud Drive. The latter also involves a third type of special file, dataless files.
Clone files
In contrast to hard-linked files, clone files are two or more distinct files within the same file system (volume) whose file extents are identical, so share the same data, as shown below. They’re created by variants of normal file copying, including duplicating in the Finder (and drag-copying within the same volume), and the cp -c command.
Instead of duplicating everything, only the inode and its attributes (blue and pink) are duplicated, together with their file extent information. You can verify this by inspecting the numbers of those inodes, as they’re different, and information in the attributes such as the file’s name will also be different. There’s a flag in the file’s attributes to indicate that cloning has taken place. At first, the two cloned files share the same data blocks and extended attributes, but as the two files are changed by editing, they start to drift apart and become uncloned.
Clone files are becoming more popular thanks to the Hyperspace app, which deduplicates files within the same volume by replacing copies with clones.
Because they can only exist within the same file system, clone files are fragile. Any copy or move to another file system is invariably accompanied by the copying of their full data, and their economy of storage can only remain as long as they stay within the same volume.
Backups
One notable exception to this same-volume rule is in Time Machine backups. As clone files are preserved in local snapshots, when Time Machine constructs a backup as a snapshot in the backup storage volume, shared file extents are retained, so preserving clones. This is reflected in the size of the backup snapshot, and in the report written to the log. For example, when backing up three distinct files and ten clones of one of those, that report included: 14 Total Items in Backup (l: 16 GB p: 11.02 GB)
3 Files Copied (l: 6 GB p: 1.02 GB)
1 Directories Copied (l: Zero KB p: Zero KB)
10 Files Cloned (l: 10 GB p: 10 GB)
Backups made by other utilities are unlikely to reproduce this behaviour, though, as they can’t synthesise snapshots in the way that Time Machine does. To preserve clone files in their backups, they’d have to identify clones in the source and explicitly perform cloning in their backup store. Although Carbon Copy Cloner claims that “in some cases CCC may clone a file on the destination prior to updating its contents”, it doesn’t appear to attempt to preserve clone files in the backups it makes. I’m not aware of any third-party utility that does.
Unfortunately, Time Machine appears unable to restore directly from backup snapshots in the backup store, and performs Finder copies when restoring. That saves each of those clone files as a completely separate file, without any sharing of data. As a result, the space occupied on disk for a restored volume can be substantially greater than the original or its backup. Extensive use of clone files could thus cause problems when restoring from backups.
Of course, rolling a volume back to a local snapshot, such as one made during Time Machine backups, preserves all clone files within that volume.
iCloud Drive
Clone files created within the same volume as local iCloud Drive storage on the Data volume, or cloned when within a folder in iCloud Drive, remain within the same file system and clones are therefore preserved, and when the file is moved to other folders in the same volume.
However, clone files are treated as simple copies as far as iCloud Drive’s remote storage is concerned. While a pair of cloned 5 GB files only use a total of 5 GB local storage, they require a full 10 GB of your iCloud allocation, indicating that their cloud storage is separate and not common to both. Although the effects of eviction (removing local data) and materialisation (restoring local data from cloud storage) are difficult to observe directly, they appear to lose the benefits of cloning.
When the local copy of a file also stored remotely in the cloud is evicted, its data is removed from local storage, rendering it dataless, as shown below.
When that file is to be used locally again, its data has to be downloaded from the cloud service, and the local dataless file is materialised by adding its data back. As far as I can tell, that doesn’t result in the reconstruction of the shared file extents, so changes cloned files into normal copies with different file extents. You would then need to use Hyperspace to restore them as clone files. Other Macs sharing the same iCloud Drive also see them as full copies rather than clones.
These behaviours could also catch the user by surprise.
Sparse files
Unlike clone files, the structure of sparse files in APFS is conventional, as shown below.
They achieve their economy in storage by only including file extents containing non-null data, and thus aren’t dependent on remaining within the same file system (volume), making them more robust. Their primary requirement is that they’re created and maintained using specific file system operations, and are only copied or moved to other APFS file systems.
Backups
When backed up by Time Machine to another APFS volume, sparse files are preserved reliably, and are also restored as sparse files. That isn’t likely to hold, though, if the file is transferred using a network file system such as SMB, as all network transfers currently appear to explode sparse files to full size prior to transfer. Because of the way in which they have to be created, only the app maintaining that file could restore its sparse format. In the case of disk images, this should normally occur the next time they’re mounted in the Finder and Trimmed by APFS.
iCloud Drive
Assessing what happens with sparse files in iCloud Drive is considerably simpler than with clone files. As long as they remain downloaded to local storage, they are preserved, and can be moved in and out of iCloud Drive storage without exploding in size. However, they too are stored in full when in iCloud storage, requiring their full size in your iCloud allocation, and the eviction-materialisation cycle explodes them to full size, and their sparse file flag is removed.
The only way to return a former sparse file to its original economical format is then to open and save it using the app that creates and maintains it. In the case of disk images, this should occur when they’re next mounted and Trimmed.
Conclusions
Clone files:
are only preserved when moved within the same file system (volume);
are preserved and restored from local snapshots;
are preserved in Time Machine backups, but aren’t restored from them;
aren’t preserved in other backups;
could result in a restored volume being substantially larger than its original;
occupy their full space in your iCloud allocation;
are only preserved in iCloud Drive when they aren’t evicted from local storage;
can be regenerated using Hyperspace.
Sparse files:
are only preserved when copied or moved directly between APFS volumes;
aren’t preserved when copied or moved over network connections, or using SMB;
aren’t preserved when copied or moved to different file systems, including HFS+;
are preserved in and restored from local Time Machine backups;
should be preserved in and restored from other local backups;
occupy their full space in your iCloud allocation;
are only preserved in iCloud Drive when they aren’t evicted from local storage;
can only be regenerated by the app that creates and maintains them.
Both clone and sparse files can result in substantial savings in storage space. However, because that’s fragile, their greatest value is in minimising erase-write cycles in SSDs, hence slowing their ageing.
Login
