I quite frequently use document versions as the quickest way to reverse fumbled changes in a document. Sometimes, running back through the Undo history doesn’t actually recover from your error, and the only alternative is your Time Machine backup. If it’s only a few minutes since the problem occurred, and your last backup was over half an hour ago, browsing all versions can be a lifesaver.

As we work more collaboratively, not just with others, but across our own range of different devices, iCloud’s lack of support for document versions has become more than just a nuisance. I might work on a report on my iMac, then want to make some corrections when I am out and only have my iPad with me. It is galling that I can run the same app, such as Pages, on the same document, but can’t rely on document versions.

The reason is that, until recently, document versions have been implemented by storing those old versions inside a locked and hidden folder, .DocumentRevisions-V100, at the root level of each volume. So my iMac can find stored versions in its own local .DocumentRevisions-V100, and show them when I use the Browse All Versions command.

When that iMac is working on documents in iCloud which it owns, it continues to store generated versions in its local store. But when I work on the same document on my iPad, it doesn’t have access to those versions, so just sees the current document. Then when I return to access it using my iMac, the previous version stored there is from my last editing session on the iMac, not from my iPad.

It makes it impossible to switch seamlessly between platforms, and working on documents in the cloud becomes half-baked and clumsy.

I don’t know why it has taken Apple so long to come up with a solution, and they haven’t even announced it. Instead it has leaked out in a support note which you probably won’t have stumbled across.

I don’t even know when this changed, but suspect from its software requirements that it is part of Mojave which has been implemented in Pages 7.2, Numbers 8.2, and Keynote 8.2, which were released on 17 September 2018.

Apple’s support note doesn’t mention those app versions as a requirement, neither does it mention that most other apps which support document versions through the Browse All Versions command should equally have support, once they are built using Xcode 10, which was released just prior to Mojave.

I have searched Apple’s developer release notes for Mojave, and the Xcode 10 documentation for its SDK, and can find no mention of this change there, nor in release notes for High Sierra. So, as far as I can tell, developers too are unaware that their own apps, once built with Xcode 10, will also miraculously preserve document versions across iCloud Drive.

One reason that Apple may not be promoting this new feature is that it doesn’t work properly yet. As I showed yesterday, there’s at least one major bug which makes it misbehave so badly that it can’t be relied on. For the moment, until Apple fixes this, you may well be so bamboozled when trying to use it that you give up in disgust. Don’t worry, with certain provisos you can still rely on my app, Revisionist, and related tools to preserve document versions wherever they go.

Since writing my account yesterday, I have had a chance to unscramble what happens when you try to use versions for a document stored in iCloud Drive.

When you edit a document using an app which has been built against the macOS 10.14 SDK, even though you may not be running it on Mojave, if that app uses Apple’s built-in support for document versions accessed using the Browse All Versions command, and you save your edits to a document stored in iCloud Drive, macOS will make its versions available to other macOS and iOS systems able to access that document in iCloud Drive.

When you first edit the app and versions are saved, this works much the same as with locally-stored versions. Each version is held locally in that volume’s .DocumentRevisions-V100, in a path like /.DocumentRevisions-V100/PerUID/501/5d6/com.apple.documentVersions using a UUID as the filename for that version. Because these are stored locally, they are not accessible to others sharing that document in iCloud Drive.

macOS then works with iCloud to create iCloud versions of those local document versions, although this stage in the process usually omits some of the versions available in the local version store. When you try to browse all the versions of that document in iCloud Drive, the app will then be offered any versions already stored in its local version database .DocumentRevisions-V100, and those from the iCloud-hosted database of available versions.

When you Browse All Versions from the same Mac that created those versions in the first place, it will find the versions in its own local version database, and those in iCloud, and offer them both. So if you originally had six ‘real’ versions, it will offer you anything up to a total of 12. You can tell which in the .DocumentRevisions-V100 database are the original versions, as those are named by their UUID alone, while those provided by iCloud have file names like com~apple~CloudDocs_[UUID]_s[version number]. However, the user has no such assistance, and just sees most of the versions duplicated.

When you first open that same document on another system sharing the same iCloud Drive, that system won’t have any local versions in its .DocumentRevisions-V100 database. If you examine the document using Revisionist, it will report that there is only the current version, and no older ones. If you then Browse All Versions on that system, the iCloud versions database will report the versions available from there, but won’t normally preview or deliver them unless you click on the icon to download them from the cloud.

The moment that you download a version from iCloud, it is then added to that system’s local .DocumentRevisions-V100 database, and becomes visible to Revisionist.

The bugs in this which currently make it almost unusable are:

• Not all locally-held versions are also stored in iCloud. Typically, of around 6 versions in a local store, only 4 or 5 will show up in the iCloud copies. If it happens that the version you need to revert to is one that is missing, the whole versioning system has failed you. This will also mean that, when a document is moved back to local storage from iCloud Drive, some of its previous versions will be lost.
• When a system has access to both originally locally-held versions and those provided from iCloud, both are stored in its local versions database. This is unnecessary duplication, and the local database should hold one or the other.
• Only apps built with Xcode 10 appear able to use this new feature. As neither users nor developers have been warned about this, there will be confusion when using different apps on different platforms, such as a mixture of Pages 7.1 and 7.2 on different macOS systems. Even when/if this is all properly documented by Apple, there is still ample room for user error and frustration.
• Versions are added to the local versions database in the order in which they are delivered to it. The iCloud versions database delivers them in seemingly random order, which disorders the versions in each local database. Software accessing the local database can only therefore rely on the datestamps of the versions to determine which are duplicates, and for the sequence of available versions.
• The NSFileVersion class needs to be updated, so that otherVersionsOfItem(at:) returns information about versions currently only held in iCloud and not yet stored locally, and a method needs to be provided to download such remote versions to local version storage.
• Absolutely none of this has been correctly documented, for the developer or user.

If these issues are not addressed, then the engineering effort so far devoted to this worthy cause will have been wasted, because users won’t be able to trust what should have been a valuable new feature.