Sometimes OS X thrusts change in your face, other times you only gradually realise what is going on.

OS X 10.7 (Lion) brought apps enabled to automatically save versions of your documents as you worked on them. Initially confined to Apple’s own products, notably iWork, the implications and effects passed many of us by: apart from losing the traditional menu commands of Save, Save As, and Revert in favour of Save, Duplicate, Rename, and Revert To.

Now that more apps have followed Apple’s lead, we have switched from Mavericks to Yosemite and soon El Capitan, what seemed another Apple quirk has become a sea change in the way that apps work.

Old -v- new

The Old School seemed clear and simple: a document, a single file, is opened by an app. The app changes the document, saving periodically to overwrite the original. To make a new version of a document, use Save As to create a new document with a different name. The snag is that this leaves us to do all the work; forget to save your work periodically, and a crash or freeze could blow your work away.

The New Way is not just changed menu commands, but a whole new model for apps and documents. This is founded on software architecture known as Model-view-controller (MVC) which has evolved with the Mac and other graphical interfaces, smarter behaviour which protects the user from disaster. Instead of leaving individual apps to work out their own solutions for autosaving and maintaining a history of changes to their documents, these are integrated as standard, free for use by all software developers.

Now when you open a document using a suitably enabled app, a version of that document is saved for future reference. Start editing it, and every hour (more often when making lots of changes) a fresh version is stored away. At any time you can browse old versions, and revert to one as desired. When you want to make a fresh copy of a document, without the legacy of old versions, use the Duplicate command. And when you want to change the name of a document, use Rename.

If you want to pretend that none of this ever happened, hold the Option key down when opening the menu and you should see old-style command like Save As… and Revert.

Internal changes

Behind the scenes, things are more complex.

Versions of documents are not stored in the app’s folders, but through internal OS X functions. These do not keep versions as separate documents, but dump changed content into an SQLite database hidden away in the .DocumentRevisions-V100 folder at the top level of your startup volume. Not only is this folder hidden from view (and locked away from even admin users), but its contents are spread through a labyrinth of folders, completely opaque to the user.

Currently the only way that you can access stored versions is through the limited interface of enabled apps, which can only access versions of documents which they are designed to handle. The only maintenance feature provided is removal of old versions, but this is not always available, and has to be accessed through the version view. When available, it appears from an arrow icon just to the right of the filename at the top of the old version window; holding the Option key may allow you to remove all old versions.

The versions database is a boon when you need to retrieve a version from a few days ago.

But it has its problems. Versions of massive Keynote presentations can swallow worrying amounts of disk space unless you thin old versions out. Trashing a document with a long and large version history can orphan those versions forever. Removing an app which stored versions can strand its version database, with no means of getting rid of that.

Features that are a boon to the average user can cause problems to power users, who currently have no tools to address them.

Technique: Maintaining Versions

The only supported way of accessing versions of a document is through the app which created that document. Its key menu command is Revert To, in the File menu of apps which support versioning.

When the versions database holds previously-saved copies of a document, you may be able to delete individual versions in the Time Machine-like versions view from the disclosure triangle next to the window title of an old version, but this feature is unreliable.

When you are going to trash a document with a significant version history, you should ideally open it using its creator app and remove old versions if that is possible, to ensure that orphaned versions are not left for posterity. Similarly before trashing an app which creates versioned documents, open its remaining documents and remove old versions on each to clear their database storage.

If things go wrong with the versions database, for instance it occupies tens or hundreds of gigabytes with most of that data apparently orphaned, the method of last resort is to delete the complete .DocumentRevisions-V100 folder, which requires the sudo command to assume root privileges. However that blows away all stored versions for all apps and all users. It is not recommended.

(Thanks to Dick Powell for helping to open this can of worms.)

Updated from the original, which was first published in MacUser volume 31 issue 1, 2015.