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.

我一直和家人使用 iCloud 共享相册来备份一些合照，每个人用自己手机拍摄的照片汇总起来就有了更完整视角的记录，它又不占用自己手机和 iCloud 的空间，所以算是挺实用的方法。而且，如果想把共享相册临时分享给其他人查看，只需打开相册的公共网站开关，就能得到一个网址，通过浏览器就能查看相册。前几天有这样的需要，于是复制了链接发过去，结果对方反馈说浏览器里显示的是 iCloud 找不到该网页。我这才后知后觉地知道，原来早在 2022 年就有网友发现「由于当地法规，这个功能在中国不再可用」了。

fin.