Never take file attributes such as datestamps at face value. It’s only too easy to pull tricks by changing the system clock, and it’s straightforward to construct a bogus file with a made-up history.

In my case, I had a genuine excuse for a little gentle fabrication. As I’ve explained before, I use the saved versions of source code files I edit in Xcode to revert changes and similar. In this case, I wanted to merge and clean up saved versions in two copies of what would have been the same file, part of the source of LogUI. A couple of times during its development I have forked my source, and in this case have two files, one containing all the changes I made up to last summer, and the other with all those made since.

The first contains 120 saved versions dating back to the initial version on 8 July 2024, listed here in Revisionist.

The second took those on from 7 June 2025 up to last weekend, for LogUI build 77, released yesterday.

Some of the 130 versions were duplicates, so for efficiency I wanted to remove those and join the two sets of versions into one. I therefore dragged and dropped those two files onto Versatility, which saved all their versions into two folders. I then merged those into a single folder containing the versions I wanted to keep.

When Versatility reassembles those into a single file, it adds each version in numeric order, ignoring any gaps in numbering. As the version files from the first were numbered from 000 to 119, all I had to do was renumber those from the second from 200 to 209, put them into the same folder, and remove duplicate versions identified from Revisionist’s listings of the original versions.

When I dropped that composite folder onto Versatility it composed them into a single file, with 98 versions stretching from 8 July 2024 to 18 October 2025.

The date of creation of that file, which was actually 19 October 2025, is given as 7 June 2025, with a date of last modification a day before it was really created.

There, in that brand new file, are those 98 versions going right back to the first 15 months ago, each safely tucked away in the macOS version database. The version files from the first of the two source code files each have creation dates of 8 July 2024, although the Mac mini M4 Pro they are now stored on didn’t exist until that October, and its first macOS was installed on 1 November 2024.

Versatility and Revisionist are both available from their Product Page.

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.

There are many more powerful PDF and image editors, yet plenty of us use Preview for those basic little tasks, where we don’t need the complications of a heavyweight. Preview isn’t without its faults, though. It can mutilate PDF annotations made by other apps, and sometimes unexpected things happen. To deal with those it has one feature that’s almost unique among PDF and image editors: it automatically saves versions using the macOS versioning system. This article explains how to make use of that.

Ask to save changes when closing documents

One important control over the behaviour of Preview and many other apps that you may not be aware of is this in the Windows section of Desktop & Dock settings. When combined with apps that use the macOS versioning system its effects are significant.

Ignoring versioning for the moment, when this setting is turned on, if you go to close an open document that has unsaved changes, before it’s closed you’ll be asked whether you want to save that changed document. This is a long-standing safety net that continues to protect us from losing lots of work by accident.

When this setting is turned off, apps may still ask you whether you want to save unsaved changes before closing a document unless the app uses the macOS versioning system. In that case, the app automatically saves a new version without offering any option. This might appear inappropriate, but as that’s non-destructive, it avoids interrupting your workflow: you can always revert to the previous version of that document, provided that you’re aware that it has been saved automatically.

If you’re not aware of what’s going on here, and how the versioning system works, this can cause odd effects you can demonstrate using Preview.

Preview’s saving grace

To see how Preview handles versions and the effect of that setting, find a copy of a suitable PDF or image file and duplicate it in the Finder. Name one copy something like testSavesOff, and the other testSavesOn. Set Ask to save changes when closing documents off to begin with, and open testSavesOff in Preview.

Now perform some destructive editing on that document without saving it, here a radical crop.

Leave it a couple of minutes before closing the document. Following that setting, Preview shouldn’t ask you whether to save the changed document, but will simply close it. Then quit Preview.

Now set Ask to save changes when closing documents on, and repeat the same sequence with testSavesOn instead. When you try to close that document, Preview should now ask you whether you want to save the changed document, to which you should click on Revert Changes to set the document back to its previous state instead.

Inspect the two documents using Quick Look and you’ll see that testSavesOn hasn’t changed, but testSavesOff has, although in neither case did you save those changes yourself.

All in the versions

Although you can see what has happened using Preview’s Revert To menu command, the clearest way to see what has happened to those two documents is to open them using my free Revisionist, which shows their saved versions.

testSavesOn has three saved versions. The current one is the same as the original, but the second version shows the destructive edit that you didn’t save.

testSavesOff has two saved versions, the original, and the current version is that after the destructive edit, which you also didn’t save.

Thanks to Preview’s use of the macOS versioning system, either way you’ve still got access to both versions of that document.

One point to note, though, is that the versioning system doesn’t automatically clean up old versions for you. When you’ve finished editing a document in Preview and don’t want to retain its old versions, delete them either using Revert To in Preview, or with Revisionist. Versions are only retained for the original document as long as it’s stored on the same volume. So you can also wipe old versions by duplicating a document and trashing the original, or copying it to another volume. Once they’re gone, you can’t restore them, as not even Time Machine can back up versions.