Undo is invaluable for stepping back quickly, but soon becomes too complex when you’ve made several changes to a document since a major revision, and need to rescue part or all of what was revised then. Backups are also essential, but even Time Machine only makes them every hour, a long time in the history of many active documents. In OS X 10.7 Lion, twelve years ago, Apple introduced a versioning system to bridge the gap between Undo and backups.

Most apps built using Apple’s preferred AppKit and some others can save documents automatically, and take advantage of macOS versioning. The latter gives you access to previously saved versions through the Revert To… commands in the File menu. If an app supports that, it should mean that you can access those previous versions through an interface closely resembling the Time Machine app, and use third-party tools too.

If you’re unsure whether an app can and does do this, open one of its documents using my free app Revisionist: if that document has saved versions, then you’ll be able to browse them using that app.

How it works

Each time an enabled app saves a document, the version of that document being saved is added to the top of the list of versions stored in the top-level hidden folder named .Document-Revisions-V100 on the same volume as that document. That folder

• isn’t backed up by Time Machine from Big Sur onwards, nor by Carbon Copy Cloner, or other backup apps;
• is permanently locked away from view, showing a no-entry sign;
• for your current data volume isn’t at the top level of the root volume (by default Macintosh HD), but in the path /System/Volumes/Macintosh HD instead.

Versions are served from the relevant hidden folder by the service revisiond, running as root, and started by /System/Library/LaunchDaemons/com.apple.revisiond.plist. When you open one of the commands in Revert To…, revisiond fetches the last saved, last opened, or all saved versions according to the command used.

Apple doesn’t document the Document Revisions database, but it appears to reference documents by their inode (when in local storage), against which it stores copies of previously saved versions. This allows any app to look up and obtain saved versions of a document. Before Apple locked the folder away, it contained:

• .cs, which contains the ChunkStorage folder containing nested folders of data chunks, and the very large ChunkStorageDatabase.
• LibraryStatus, a small file.
• PerUID, which contains a folder for each user ID, each in turn containing numbered folders containing saved versions of documents.
• db-V1, which contains the sqlite database in which version files are maintained.
• metadata, a larger file containing various metadata and extended attributes.
• purgatory, a folder presumably for versions due to be purged.
• staging, often an empty folder.

For example, the folder PerUID/501 contained many more folders numbered in time order, within each of which was another folder named com.apple.documentVersions containing that batch of version files for Apple’s apps. Each version file was named by UUID, with the correct extension. The chunks contained in .cs and the individual version files in PerUID were all referenced by the database. Deleting or removing any of those files would render the database out of sync, and require its reconstruction.

It also used to be possible to discover the size of the hidden folder using
sudo du -sh /.DocumentRevisions-V100
but that no longer works with the locked-down version.

Mobility

Because document versions are referenced by inode, actions that result in a document being assigned a new inode will lose access to all its previous versions. These 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, and all previous versions should be removed from the Document Revisions database;
• Backing up, archiving or migrating to a different volume, which makes a copy of the document.

In almost all cases, ‘cloning’ a volume also loses all versions in the Document Revisions database, unless the method of duplication creates an absolutely identical copy, with the same inodes and file system.

iCloud is more complicated. There was a time when it didn’t support versions at all, then it started to support them but had some serious bugs making them unreliable. Those have been gradually resolved, and iCloud Drive now effectively keeps its own Document Revisions database, making versions available to all Macs and devices accessing them.

Blocking versions

If a disk is so short of space that there isn’t sufficient to support a Document Revisions database, some users sacrifice its benefits by deleting the hidden directory and replacing it with a file of the same name, so preventing revisiond from using its database. However, that could result in unexpected behaviour, and should only be considered as a last resort. I don’t know of any control in macOS to disable this subsystem.

Version tricks

Although the built-in interface can prove cumbersome to use, with a third-party tool such as Revisionist you can perform complex partial reversions of documents by combining content from their current and two or more previous versions. I have used this several times when editing code in Xcode, which has good support for versions.

You can use Revisionist to open and revert documents that can no longer be opened in their normal editing app. If a versioned document is sufficiently damaged that it can’t be opened using its regular app, you can’t access its last good version using that app. Instead, open the document in Revisionist and save the previous good version from there.

If you do want to move a document’s previous versions to another volume, disk or Mac, use Revisionist or Deep Tools (see below). You can also use them to create an archive containing every version of a document, saved as a separate file.

Although you can no longer see the size of the Document Revisions database, you can weed unwanted old documents easily using Revisionist. The app can also scan folders and report how many versions of each document are stored, so you can do your weeding where it’s most needed.

Further information

Troubleshooting version problems
Revisionist and Deep Tools (free)