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:

1. Edit the local document on Mac A. To transfer it, drop it on Versatility and save its folder archive to iCloud Drive.
2. On Mac B, drop the folder archive in iCloud Drive onto Versatility, and save that to its local location for editing there.
3. 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.

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.

The versioning system built into macOS for the last 14 years must be among its least used features, with many simply ignoring it, and some even blocking it from working. Yet among those who do use its features, it’s probably used more often than backups, and to greater effect.

A couple of weeks ago, when I was working on the code for AppexIndexer, I realised that the changes I was making to enable its search feature were getting out of hand, and should I need to undo them would have required a lot of work. Because the code editor in Xcode supports macOS versioning, I paused my editing for a few moments, opened that document’s versions and stepped back through them to reach the version saved just before I had started making those changes. I then saved that version as a separate fallback copy and resumed my editing.

All this had happened since the last Time Machine backup, which would have been of little use had I needed to revert all those changes. Even automatic hourly backups are too infrequent to capture changes as we make them in active documents. This is just what the versioning system is intended to capture, although to make best use of it, you’ll need third-party software.

Standard access

Most apps that edit documents now support the macOS versioning system by default. Some allow you to auto-save documents as you’re working on them, but all should create a new version each time you save a document. Normally, you might access saved versions using the Revert To… command in the app’s File menu, where you can Browse All Versions… in a full-screen window resembling Time Machine’s interface to it backups.

Although the design looks impressive, it’s not the only means of browsing a document’s saved versions, and in many respects doesn’t support the power and flexibility in the versioning system.

How it works

Many macOS apps that edit documents are based on AppKit, supporting actions in their File menus including Save and Revert To…. Each time you save a document, that automatically uses the Foundation API to save a copy in the hidden version database located in the folder .DocumentRevisions-V100 at the root of the volume on which that document is stored. When you Browse All Versions macOS finds all the previous versions of that document in the volume’s database and displays them, making them available to revert to. Although document-based apps developed using SwiftUI are still relatively unusual, they too should provide full support for versions and the same menu commands.

This relies on:

• support in the editing app;
• the document being stored in a volume in APFS or HFS+ format; ExFAT, MS-DOS and other file systems don’t normally work, and can’t save versions;
• the hidden folder .DocumentRevisions-V100 containing the local version database for that volume.

Although a document’s versions are normally accessed through an app that can edit that document, that isn’t a requirement, and there are several alternatives that can access and manage any versions, including Versions from the App Store, and my own free utilities Revisionist, Versatility and Deep Tools, whose use I will explain in further articles.

On APFS volumes, the version database appears to use clone files to good effect, in preserving changed storage blocks for each saved version, so using a minimum of space.

How it doesn’t work

The biggest limitation of versions is that they don’t move with the document. When you copy or move a document with versions to a different volume, its versions don’t go with it, although moving it within the same volume preserves them intact. Any document only retains the versions created during its editing on its current volume.

Say you have been working on a file named MyBigDocument when it’s stored in your ~/Documents folder, and there are versions saved for it there. Copy that to an external disk, and that copy now has no versions at all. Edit it there, and it will build its own collection of versions on that disk, but you won’t be able to access those if you open MyBigDocument from your ~/Documents folder. You can use my utilities to move its versions around from volume to volume, or to another Mac, but left to its own devices, macOS doesn’t do that for you.

Versions become complicated in iCloud Drive. iPhones and iPads also use versions, but their behaviour in iCloud storage has changed over time. I will explore current behaviour in Sequoia in a separate article.

One common fear of using versioning is that the database can accumulate a seemingly unlimited number of versions of files, and consume large amounts of space. You can get a good estimate of how large a volume’s version database folder is using the Terminal command
sudo du -sh [pathtovolume]/.DocumentRevisions-V100
followed by authentication. The correct path to use for that on the current Data volume is /System/Volumes/Data/.DocumentRevisions-V100.

macOS doesn’t provide any means of editing what’s stored in the versions database, nor of weeding old versions. On one of my Macs, its internal Data volume currently has several documents for which there are more than 100 versions, with a maximum of 153. However, the versions database on that volume is only 38 MB for a total of more than 35,000 files in ~/Documents.

Practical use

In addition to my example at the start of this article, I quite frequently use versions as an extended undo. Some minutes into an editing session I might realise that an earlier change such as deleting paragraphs needs to be undone. Rather than working my way back through a long series of Undo commands, the easiest way to fix that is to open the document’s versions using Revisionist, locate an earlier version containing the deleted paragraphs, copy those from that version and paste them into the current document that I’m editing.

Some documents have important previous versions that I want to preserve when I move them across to another Mac or to external storage. For those I drag and drop the document onto Versatility to create a folder containing all that document’s versions, move that to the other Mac, and drop that folder onto Versatility there. That recreates the original document with all its versions stored safely in its new location.

When certain documents have been very active, and are now complete so I don’t want to preserve all those old versions, I can clear them all by moving that document to another volume, and moving it back again. If I want to reduce the versions but keep some of them for posterity, then I open them using Revisionist and delete the old versions I don’t want to retain any longer.

Most important of all, I know that so long as I have saved a document, if I want to recover any previous version I can do so using Revisionist without having to look through my Time Machine backups. With macOS versioning, Command-S doesn’t just save my work, it also maintains that document’s change history.

Key points

• Many apps support macOS versions. They normally feature a Revert To… command in their File menu, although not all do.
• Save (Command-S) creates a new version of a document automatically, and maintains its change history.
• Use additional apps like Revisionist and Versatility to get the most out of versions.
• A document’s versions don’t move with it to another volume or Mac, but can be preserved using Versatility.
• Documents can accumulate a large number of versions when they’ve been saved many times.
• Delete all a document’s versions by moving it to another volume, then moving it back again.
• Using versions gives you finer detail of changes that are lost in backups.