Whether you make use of it or not, each APFS or HFS+ volume contains data to support macOS versioning, a feature in many Mac apps now, including most of Apple’s own, such as Preview, TextEdit, Pages and Numbers. Unless you block the database from being created, every time you save a document in an app that offers a Revert To command in its File menu, the current version will be saved to that database. There is no way to disable this feature in individual apps. In some cases, that database can cause problems.

Each volume used to store normal working files has at least three hidden folders at its root level:

• .fseventsd with file system events for that volume recorded in a series of files,
• .Spotlight-V100 containing the volume Spotlight indexes, detailed here,
• .DocumentRevisions-V100 containing the volume’s version database.

The last of those is locked away securely to prevent user access. As far as I’m aware, unlike the other two, it hasn’t been described in detail recently, and doesn’t appear in the otherwise comprehensive accounts of macOS by Amit Singh or Jonathan Levin. This article tries to rectify that.

Structure and function

The .DocumentRevisions-V100 folder contains:

• .cs, containing ChunkStorage, with the ChunkStoreDatabase, and deeply nested folders of numbered storage chunks
• AllUIDs, containing a nested com.apple.documentVersion folder with each version stored in a dataless file named by its UUID
• db-V1, containing db.sqlite, the database of versions
• LibraryStatus, a property list indicating whether the database state is trustable
• metadata, a property list containing DISK_UUID and tookThinningOver values
• purgatory, most commonly an empty folder
• staging, also commonly empty.

When an app that supports versioning saves a file, the current version is added as a dataless file to a folder in AllUIDs, with its UUID as its name, its data are added to the ChunkStoreDatabase, and its details are added to the database in db-V1. Chunk sizes typically range up to just over 20 MB. The service responsible for versioning is revisiond, and the subsystems you’ll encounter in the log are com.apple.foundation.filecoordination and com.apple.chunkinglibrary.

Retrieving a version thus consists of looking it up in the db.sqlite database, and reconstituting that version as a file, using the dataless file with its attributes and metadata in the file UUID, and its data restored from the ChunkStore.

Apps other than the original used to create those versions can also access all the saved versions of any file, but to do so they must be able to open the current version, so having appropriate privileges and privacy settings. This effectively protects access to the contents of the versions database according to the restrictions imposed on its current version.

Backing up

For many years, until macOS Catalina, Time Machine dutifully backed up .DocumentRevisions-V100 folders, although it has never been able to restore them successfully. This is because of its dependence on reuniting chunks of data with a dataless file, and apparent reliance on inode numbers. Copying a .DocumentRevisions-V100 folder to another volume produces a weird result, as the dataless files in the com.apple.documentVersion folder may then point to completely different files.

Third-party backup utilities like Carbon Copy Cloner also don’t back up the folder, as they too are unable to restore it successfully. As a consequence, restoring from a backup, or migration from another volume or Mac, always loses all saved versions.

Housekeeping

The most common cause of problems with the version database is excessive size. Although its size isn’t readily discoverable, it can be a major contributor to that attributed to System Data in Storage settings and third-party utilities, and in some cases can exceed 100 GB.

In the past I had suspected versioning of using hard links or, in APFS, clone files, to achieve economic use of storage, but that appears to be the role of the ChunkStore. Multiple versions of some file types such as JPEG images appear to require a similar amount of storage as would individual files, but others such as RTF can appear significantly more efficient.

ChunkStore size is also dependent on its housekeeping. When a single large JPEG image with 12 versions was deleted, the size taken by chunks didn’t change until the Mac was shut down and started up again. ChunkStore housekeeping routines are clearly performed following start up, but may also occur at periodic intervals later.

Thus the best way to reduce the size of the ChunkStore is:

• Identify documents whose saved versions are likely to be taking a lot of space in the version database.
• For each of those documents, to remove unwanted versions.
• Restart the Mac and leave it to perform ChunkStore housekeeping.

How to identify documents with many versions

My free utility Revisionist has a version crawler that will list all files in a volume or folder with the number of versions they currently have stored in that volume’s .DocumentRevisions-V100 folder. This is accessed in its Open Crawler command in the Window menu. That doesn’t attempt to estimate their size, though.

It’s not uncommon to discover some files with more than 100 versions. On one of my Macs, the current record is 230 versions, and it has several with over 100. Some apps such as Pages often generate large files, where even 20 saved versions can use substantial storage.

How to remove versions

To remove all versions of a document quickly and simply:

• Select the document in the Finder and Duplicate it using Command-D.
• Delete the original file and rename the duplicate.

This is because versions aren’t retained by clone files.

To remove some versions of a document, open that document in Revisionist, select the version(s) you want to delete, then click the Delete button. Note that, because of the way the version database works, there is no undo. Deleted versions cannot be recovered, and because they’re not backed up, you can’t restore that document and recover the versions from there.