The versioning system built into macOS for the last 14 years must be among its least used features, with many simply ignoring it, and some even blocking it from working. Yet among those who do use its features, it’s probably used more often than backups, and to greater effect.

A couple of weeks ago, when I was working on the code for AppexIndexer, I realised that the changes I was making to enable its search feature were getting out of hand, and should I need to undo them would have required a lot of work. Because the code editor in Xcode supports macOS versioning, I paused my editing for a few moments, opened that document’s versions and stepped back through them to reach the version saved just before I had started making those changes. I then saved that version as a separate fallback copy and resumed my editing.

All this had happened since the last Time Machine backup, which would have been of little use had I needed to revert all those changes. Even automatic hourly backups are too infrequent to capture changes as we make them in active documents. This is just what the versioning system is intended to capture, although to make best use of it, you’ll need third-party software.

Standard access

Most apps that edit documents now support the macOS versioning system by default. Some allow you to auto-save documents as you’re working on them, but all should create a new version each time you save a document. Normally, you might access saved versions using the Revert To… command in the app’s File menu, where you can Browse All Versions… in a full-screen window resembling Time Machine’s interface to it backups.

Although the design looks impressive, it’s not the only means of browsing a document’s saved versions, and in many respects doesn’t support the power and flexibility in the versioning system.

How it works

Many macOS apps that edit documents are based on AppKit, supporting actions in their File menus including Save and Revert To…. Each time you save a document, that automatically uses the Foundation API to save a copy in the hidden version database located in the folder .DocumentRevisions-V100 at the root of the volume on which that document is stored. When you Browse All Versions macOS finds all the previous versions of that document in the volume’s database and displays them, making them available to revert to. Although document-based apps developed using SwiftUI are still relatively unusual, they too should provide full support for versions and the same menu commands.

This relies on:

• support in the editing app;
• the document being stored in a volume in APFS or HFS+ format; ExFAT, MS-DOS and other file systems don’t normally work, and can’t save versions;
• the hidden folder .DocumentRevisions-V100 containing the local version database for that volume.

Although a document’s versions are normally accessed through an app that can edit that document, that isn’t a requirement, and there are several alternatives that can access and manage any versions, including Versions from the App Store, and my own free utilities Revisionist, Versatility and Deep Tools, whose use I will explain in further articles.

On APFS volumes, the version database appears to use clone files to good effect, in preserving changed storage blocks for each saved version, so using a minimum of space.

How it doesn’t work

The biggest limitation of versions is that they don’t move with the document. When you copy or move a document with versions to a different volume, its versions don’t go with it, although moving it within the same volume preserves them intact. Any document only retains the versions created during its editing on its current volume.

Say you have been working on a file named MyBigDocument when it’s stored in your ~/Documents folder, and there are versions saved for it there. Copy that to an external disk, and that copy now has no versions at all. Edit it there, and it will build its own collection of versions on that disk, but you won’t be able to access those if you open MyBigDocument from your ~/Documents folder. You can use my utilities to move its versions around from volume to volume, or to another Mac, but left to its own devices, macOS doesn’t do that for you.

Versions become complicated in iCloud Drive. iPhones and iPads also use versions, but their behaviour in iCloud storage has changed over time. I will explore current behaviour in Sequoia in a separate article.

One common fear of using versioning is that the database can accumulate a seemingly unlimited number of versions of files, and consume large amounts of space. You can get a good estimate of how large a volume’s version database folder is using the Terminal command
sudo du -sh [pathtovolume]/.DocumentRevisions-V100
followed by authentication. The correct path to use for that on the current Data volume is /System/Volumes/Data/.DocumentRevisions-V100.

macOS doesn’t provide any means of editing what’s stored in the versions database, nor of weeding old versions. On one of my Macs, its internal Data volume currently has several documents for which there are more than 100 versions, with a maximum of 153. However, the versions database on that volume is only 38 MB for a total of more than 35,000 files in ~/Documents.

Practical use

In addition to my example at the start of this article, I quite frequently use versions as an extended undo. Some minutes into an editing session I might realise that an earlier change such as deleting paragraphs needs to be undone. Rather than working my way back through a long series of Undo commands, the easiest way to fix that is to open the document’s versions using Revisionist, locate an earlier version containing the deleted paragraphs, copy those from that version and paste them into the current document that I’m editing.

Some documents have important previous versions that I want to preserve when I move them across to another Mac or to external storage. For those I drag and drop the document onto Versatility to create a folder containing all that document’s versions, move that to the other Mac, and drop that folder onto Versatility there. That recreates the original document with all its versions stored safely in its new location.

When certain documents have been very active, and are now complete so I don’t want to preserve all those old versions, I can clear them all by moving that document to another volume, and moving it back again. If I want to reduce the versions but keep some of them for posterity, then I open them using Revisionist and delete the old versions I don’t want to retain any longer.

Most important of all, I know that so long as I have saved a document, if I want to recover any previous version I can do so using Revisionist without having to look through my Time Machine backups. With macOS versioning, Command-S doesn’t just save my work, it also maintains that document’s change history.

Key points

• Many apps support macOS versions. They normally feature a Revert To… command in their File menu, although not all do.
• Save (Command-S) creates a new version of a document automatically, and maintains its change history.
• Use additional apps like Revisionist and Versatility to get the most out of versions.
• A document’s versions don’t move with it to another volume or Mac, but can be preserved using Versatility.
• Documents can accumulate a large number of versions when they’ve been saved many times.
• Delete all a document’s versions by moving it to another volume, then moving it back again.
• Using versions gives you finer detail of changes that are lost in backups.