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.


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 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 form
sudo 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.


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.