macOS has some of the best safeguards to enable you to recover from errors when working with documents. These include:

• Undo/Redo, providing immediate reversal of recent changes, even when they’ve not been saved;
• Revert To previously saved versions of a document using the macOS version system;
• Time Machine automatic backups, creating an independent copy of each changed document every hour;
• APFS snapshots, local retention of previous versions of every changed file, made every hour with backups and retained for up to 24 hours.

This article looks at the least used of those four, the macOS version system supporting the Revert To feature.

Classic Mac OS supported a Revert command, which discarded all unsaved changes and reverted to the last saved version of a document. This carried over into Mac OS X, and by OS X 10.7 had developed into a full version system, providing access to all previously saved versions of each document. Initially, few apps supported this version system, but it has since caught on, so well that most modern apps now include full support for Revert To commands and the version system.

How it works

All apps developed using AppKit’s NSDocument class automatically create and save a new version of each document whenever that document is saved, unless the app opts out (and some apps may make that a user choice). In this case, saves include both those made manually by the user, and any automatic saves made by the app (under an optional feature of the NSDocument class).

Saving a document thus results in:

• the last-saved version of the document is added to the list of versions of that document in that volume’s version database, and
• the current version of the document is written to storage, in the document file.

Adding the previous version to the version database also involves transferring its data, although Apple doesn’t document how that takes place. It’s most likely, on APFS volumes at least, that no file data is actually copied, but that the database contains references to the changed storage blocks for that version, minimising the space required to store version data. At least some references in the version system appear to use bookmarks, a relative of the Finder alias intended for in-app use.

A version database is stored on each HFS+ or APFS volume on which there are files with stored versions, in the hidden and locked top-level folder .DocumentRevisions-V100. Prior to macOS Big Sur, that folder was normally backed up by Time Machine, even though versions can’t be restored from backups. In Catalina particularly that folder could take a long time to back up, so for Big Sur it was added to the system exclusion list. In earlier versions of macOS, you’re strongly recommended to add it to the user exclusion list manually, as it’s of no value in a backup, and just wastes space and can reduce the speed of backing up to a snail’s pace.

Standard access to previous versions of a document is only possible through an app that can open the current version of that document. Once that has been opened, using the File/Revert To/Browse All Versions… command displays all saved versions using an interface similar to that of the Time Machine app. This allows reversion to an earlier version, or modifications to the current version containing content copied from an old version.

There is one significant problem with this: if the current version of the document has become damaged and can’t be opened in an app. Without opening that version, macOS allows no other means of access.

Retention of old versions

Old versions of a document are retained indefinitely in that volume’s version database until the original document is deleted from that volume. Although the version database can grow very large, its size isn’t readily accessible, and it’s lumped within the category System Data by the Storage tab in About This Mac. In theory, old versions could be purgeable when free space becomes low, but that doesn’t appear to be the case. There’s also no direct way to empty the version database.

Because versions are stored for the original document and in a local database, many file actions result in loss of all previous versions. Those include:

• copying or moving the file to a different volume,
• duplicating the document, or saving it as another file,
• moving the file to or from iCloud,
• making any form of backup.

Moving the file within the same volume doesn’t lose any previous versions, though, nor does changing its name.

iCloud

Originally, iCloud had no support at all for versions, but this later improved, so that files stored in iCloud could retain old versions until they were moved out of iCloud, although synchronisation of those versions was patchy and unreliable.

That has changed again more recently. Apple’s current developer documentation for this, in the NSFileVersion class, doesn’t fully explain how versions behave in iCloud. Apple states that
“For files in the cloud, there is usually only one version of the file at any given time. However, additional file versions may be created in cases where two different computers attempt to save the file to the cloud at the same time.”

What happens in Monterey is more complex, and severely limits the value of versions of documents in iCloud. To illustrate this, here are the lists of available versions of the same document in iCloud Drive, accessed by two different Macs at the same time, after allowing several hours for both to fully synchronise.

This Rich Text document was created using the Mac showing the first of those two views of its versions. That Mac then saved a series of versions, increasing in size, until version 4 at 06:17:19. The other Mac shown in the lower of those views then synced successfully at 06:17:19, and received only the last of those versions. It then modified that document, saving versions 2-5 between 08:32 and 08:42. The first Mac then synced with iCloud, and received only the last version as saved by the second Mac, which then appears as the current version on the first of the two views. At no time was there any attempt made by both computers to save the file at the same time, so there has been no conflict or contention over versions from different clients.

The end result is that each of the two Macs holds part of the version history, but neither is able to sync old versions to assemble a complete history. It seems most likely that those versions are held in the local version database, and no old versions are held in iCloud at all. Previous implementations of versions in iCloud did attempt to sync versions, but Apple appears to have abandoned that altogether. For the time being you should assume that documents edited in iCloud will have no shared version history, only local versions and a synced latest version.

Unleashing the power of versions

I have a suite of free utilities designed to get more from the version system. The master app is Revisionist, which does everything from crawling through folders discovering which files have versions stored, to previewing and saving any version of a document. Three smaller utilities in DeepTools are intended to address the problem of moving versions between volumes and different Macs. They’re available from here, and are fully compatible with macOS from El Capitan to Ventura.

Here are some quick tips:

• To remove all versions from documents or folders, copy them to another volume, trash the originals, and copy them back again. Once gone, though, there’s no way to recover old versions, even from a snapshot.
• To copy a document complete with all its current versions to another volume or Mac, use Revisionist’s Archive and UnArchive features, or DeepCopy. These create an archive folder containing all the different versions, which you can Zip up to move if you wish. Once in place, UnArchive that folder to regenerate the original document with all its versions safely in the local version database.
• To recover a previous version of a document which can no longer be opened using its app, open it in Revisionist, check which version to save, and save it ready to edit again.
• When you revert to a previous version of a document, older versions are still retained in the version database, so you can revert back to any of those versions later if needed.
• Before restoring an existing document from your backups, check whether there’s an older version of that document that would do instead. Reverting to that will preserve its older versions; restoring from a backup will destroy all versions.
• Save working documents frequently, to maintain a good version history. If you need to revert to an older version to undo changes, that makes it much easier. Use Revisionist later to remove unwanted versions.
• Recover removed document contents from an old version to paste them into the current version. This is a powerful technique when you realise the section you removed a couple of days ago needs to be reinserted into the document.
• Don’t assume that your favourite apps don’t support versions. Some, like Xcode, do, even though accessing the Revert To command might appear impossible. Try opening one of the app’s documents using Revisionist to see whether there are versions available.