macOS provides a fine-grained version management system which, in apps that support it, stores multiple versions of documents saved over periods of minutes rather than hours or days. Unlike Time Machine and other backup systems, this is entirely automatic, and requires no configuration. In many apps, it just works.

When you’re working in an app which supports this version system, each time that you save, or the app autosaves, a document, the previous document state is moved to the hidden database on that volume, and the new version is saved as its current state. At any time that you want to look back at saved versions, use the Revert To command in the File menu, and you can either go one step back, or browse all the previous versions using an interface like that of the Time Machine app.

Each volume’s versioning database is stored in a locked and hidden Data Vault named .DocumentRevisions-V100 at the root of that volume; in Catalina and Big Sur, with their startup Volume Group, this exists only on the Data volume, typically named Macintosh HD – Data, and other data volumes. Because this is a Data Vault, you can’t look inside it, and can’t even get an estimate of its size. It’s likely that its contents have changed in Catalina, and may now save previous versions on a block basis rather than as individual files, which should reduce the space it requires. However, those changes have also brought problems when trying to copy that hidden folder to Time Machine backups. This can be worked around by adding the .DocumentRevisions-V100 folder to Time Machine’s list of exclusions, a behaviour now standard in Time Machine in Big Sur.

A document’s previous versions don’t necessarily move with that document, and one of the most significant limitations of the version system is that it’s all too easy for previous versions to become lost. The fundamental rule is that previous versions are associated not with the document file, but with its inode number. On each volume, an inode is a unique reference to that file (or folder), which is unchanged no matter where the file is moved on that same volume. If you do anything which leads to that inode changing, then all previous versions will be detached, and you won’t see them listed when you use the Revert To menu command.

So long as the inode of the document remains unchanged, and it remains on the same volume, its previous versions will remain accessible to apps which use the versioning system.

Actions which change document inode and lose versions include:

• Save As… a new document, which creates a new file with its own inode, and starts saving its own versions;
• Finder copies and Duplicates (and copies made in Terminal), which also create a new file for the copy;
• Copy/move to another volume (except iCloud), as the new document will have a new inode for that volume, and previous versions aren’t copied across;
• Deleting the document, either when you empty the Trash or in Terminal, which removes its inode from the file system metadata, and all previous versions should be removed from the Versioning database;
• Backing up or achiving to a different volume, which makes a copy of the document.

Documents stored in iCloud used to lose their previous versions, but that has changed in more recent releases of macOS and iOS, most noticeably from Mojave and iOS 12 onwards. It’s now possible to edit the same document stored in iCloud on multiple devices, and for versions to be saved and synced across them all. However, this depends on having a good Internet connection, iCloud synchronisation being responsive, modest document size, and saving less frequently to allow versions to sync properly between saves. It’s possible for two devices to end up with different sets of versions, which can be confusing.

Documents edited using Handoff present a different problem, in that you can end up with two conflicting versions because the same document is being edited on both devices. When conflicting versions arise, you’re asked to choose which version to keep.

Although Time Machine prior to macOS 11.0 makes backup copies of the versioning database, previous versions aren’t accessible in Time Machine backups, nor are they restored if you restore individual documents. They can be restored when the whole volume is restored from a backup, though. Third party cloning and backup tools don’t now attempt to back up or restore previous versions, which is the most practical solution as macOS prevents direct access to the versioning database.

The most robust and reliable way to preserve previous versions is to convert the document into a folder containing each version using my free apps in DeepTools, or Revisionist, which is a complete toolkit for accessing versions and the macOS Versioning system. These are simple to use:

1. To convert a document and all its previous versions into an archive folder, use the DeepArchive app or Revisionist’s Archive button.
2. You can then Zip up the folder, move or store it wherever you want.
3. To convert an archive folder back into a document and its previous versions, use the DeepUnarchive app or Revisionist’s UnArchive menu command, and save the new file on the volume you wish to keep it on.

These work in all versions of macOS from El Capitan to Big Sur, and now run native on both Intel and Apple Silicon Macs.