Main navigation

Document Versioning

It’s almost seven years since OS X 10.7 Lion introduced the automatic saving of documents and a versioning system to many apps, but even today they are by no means standard features of all apps, and can be opaque in use.

The user interface is simple and common across many apps. Instead of the traditional Save and Save As… commands in the File menu, enabled apps offer Save, Duplicate, Rename, and Revert To. Whenever you save the current document, or the app autosaves it for you, that becomes the current version of the document, and the previous current version becomes the last version preceding the current one.

The Version Browser

If you decide to step back and revert to an earlier version, you browse those versions with an interface much like that of the Time Machine app, allowing you to step back through time and see each previous version, and decide which to revert to.

Apple has hidden three valuable features of the version browser, which are now easily missed. First, you can restore a copy of a previous version, either by holding the Option key down in the browser or using the command in the File menu.

Second, you can delete versions using the Revert To command in the File menu from within the version browser. Simply display the version that you want to delete on the right side, then use this command to delete it.

Third, you can perform many edit functions within the version browser. If you wanted to copy a section of text from an old version and paste it into the current one, for example, that is readily achieved here by copying from the older version on the right, and pasting into the current version at the left. It is thus much more than just a browser.

Implementation

Previous versions of a document are not stored with the current version, and in many circumstances performing file operations on documents with previous versions results in breakage of that link. This is good in that it prevents orphaned versions from accumulating in the versions database, but bad because it makes versions so ephemeral.

Versioning is implemented as part of the services offered by the macOS File Manager, so is fully integrated with Finder’s features and commands used in Terminal’s command line. When you empty the Trash, macOS locates any extant versions of deleted documents and removes them too. The same happens if you delete a document using the rm command in Terminal.

Versions remain associated with a document so long as that file remains the same entity as far as the File Manager is concerned. You can move it within a volume, or rename it, but any copy made to the same or a different volume, or duplicate, will lose its association with all previous versions of the document.

The one useful exception to this is moving the file to your iCloud Drive, which maintains association with its versions when accessed from the same Mac. You can also move it back from iCloud Drive to the same volume without losing them. However, if you access that same document in iCloud Drive from a different Mac, the versions are not associated with it for that other system. This is probably because iCloud Drive retains its connection with the versions stored on the local volume, but does not transfer them to any remote versioning database.

Versioning Database

Other than the current version, which is stored where the document is, all previous versions are kept in the hidden .DocumentRevisions-V100 folder at the top level of that volume. That folder is normally backed up in Time Machine backups, and in volume clones made by utilities such as Carbon Copy Cloner and SuperDuper!, so can be restored when needed.

Not only is .DocumentRevisions-V100 hidden, but it requires root permissions to access it. Inside you will find the following:

.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 xattrs.

purgatory, a folder presumably for versions due to be purged.

staging, a folder which is often empty.

For example, the folder PerUID/501 contains many more folders numbered in time order, within each of which is another folder named com.apple.documentVersions containing that batch of version files for Apple’s apps. Each version file is named by UUID, with the correct extension.

The chunks contained in .cs and the individual version files in PerUID are all referenced by the database. Deleting or removing any of those files will render the database out of sync, and require its reconstruction. It is sometimes suggested that deleting large version files is a good way of fixing problems: it may also cause its own. At worst, it could disable the versioning system, or cause it to malfunction.

The contents of .DocumentRevisions-V100 are not intended to be manipulated even by advanced users, and the risks of tampering with them are great.

Versions stored in the macOS versioning database, in .DocumentRevisions-V100, are included in the calculation of free space made by the Finder and Disk Utility. As versions are not transferred when copying or moving files to other volumes, they do not need to be taken into account in the total size required by the copy/move.

However, the database can sometimes grow to substantial size. On Macs which make light use of its features, it is likely to be up to 100-200 MB in size on the boot volume. Some users report sizes of 5 GB or more when it is used heavily. You can check current size using a command of the formsudo du -sh /.DocumentRevisions-V100
followed by authentication.

I haven’t been able to find any other tools which do anything useful with the versioning database, and welcome news of any that are available.

Postscript:

Thanks to @schackspelar for pointing out corecode’s VersionsManager 1.1.5, available from here. If you want to use that to remove versions, you have to use its in-app purchase to add that feature. Oddly, I was unable to locate that app using Google or the App Store search feature.

4Comments

Thank you for this article, it answered a number of questions for me. I think this is an example of Apple introducing a major, and very useful to some, feature with so little fanfare that it is often overlooked. Many of us probably didn’t got past ” where’s Save As gone?”. This wasn’t helped by Apple’s initial assumption that there was no remaining use case for Save As (which might explain some things about their current eternally unfinished software?).

Wondering about the size of my database (524MB) let me into two blind alleys. My user account is not an administrator account so sudo no longer works with a simple authentication but the wonderful Shift-Command-dot lets me look at the database folder in the Finder. APFS reports its size as zero. Surprisingly, logging into an administrator account produces the same result (ie zero bytes), is that a SIP effect? Your sudo command does, of course, work from the administrator account.

Tools coming tomorrow too! I found one document here with over 1200 versions. Thankfully it’s a smallish text file.
In Sierra, HFS+ never completes estimating the size of that folder. I’m surprised that in High Sierra with APFS it just returns a 0 – returning no value would make sense, but returning an incorrect one looks like (another) bug.
Howard.

Thank you.
Although both those articles contain some interesting material, the AppleHelpWriter one is six years old, and both are surprisingly lacking in their research – they don’t appear to have come across the macOS versioning system, despite it being documented by Apple!
The second article in particular thinks that the versions database is part of Time Machine, which it isn’t, and both seem to think that it’s a good thing to trash the whole lot, without realising that macOS will only recreate it, and they may well be throwing the baby out with the bathwater.
Howard.