Explainer: the macOS versioning system

We all make mistakes. One of the essential features of any decent operating system is to help us recover from them.

Sometimes you’re working on a document and realise what you did a few moments ago needs to be changed. No problems, after a few Undos you’re back to where you were. But what if you cut several pages, and that was about fifteen minutes ago? You can’t normally undo that far back, and in any case you don’t want to lose all the other changes you’ve made since. Will Time Machine come to your rescue, then? Not on this occasion, as the last automatic backup was made over half an hour ago.

Some apps have their own versioning system, which keeps previously saved versions of a document you’re working on. macOS goes better than that in providing this facility to all apps which care to make use of it. Edit a Rich Text document in one app, and all its previous versions and backups can be accessed when you open it in another app. This also now works across iCloud with documents you edit on any of your Macs or devices. This is the macOS versioning system, bridging the gap between Undo and backup.

The way this works is that, each time you save the document you’re working on in a compatible app, the previous version is added to a database of versions kept in the hidden .Document-Revisions-V100 folder at the top level of that volume. To browse those saved versions, together with copies held in Time Machine backups, use the Revert To submenu in the File menu in any suitable app which supports this system.


Normally, these are displayed as if in the Time Machine app, with the current version at the left, and the version history at the right. For most purposes, that’s fine, but there are more powerful things you can do with those saved versions.

There are some notable limitations with this. Because these versions are saved in a database on the volume on which the original document is stored, when you copy or move that document to another volume, the versions don’t move with it, and are lost. If you want access to the same versions from two different Macs, that’s a problem, as each time you copy it across, all the previous versions are blown away. iCloud provides a good workaround, so long as all who access that document leave it in the same folder in iCloud Drive. When you do copy it down, though, those old versions are gone.

One consequence of this immobility of versions is that backup copies of documents saved by Time Machine or any other backup software lose their version history too. Oddly though Time Machine backups included the hidden .Document-Revisions-V100 folder in each volume, but were unable to do anything useful with them. Indeed, because that folder seems to contain a vast number of files, and possibly hard links, Time Machine backing up to HFS+ started to choke on it in Catalina and earlier. Since Big Sur, the .Document-Revisions-V100 folder has been excluded from Time Machine backups, and I think that’s also true of third-party backup utilities like Carbon Copy Cloner. There’s little point in wasting many minutes trying to back up a folder that can’t be restored.

The standard macOS interface also doesn’t make it easy to do something I’ve needed to do on several occasions. Realising that I had earlier cut out a large chunk of the document that I decided I wanted to reinstate, I went back to the last version containing the removed section, copied it from there, and pasted it into the current version.

The only downside to versions that I know of is the difficulty of maintaining them. That .Document-Revisions-V100 folder is quite rightly completely inaccessible, so you can’t even tell how many documents have versions, nor go in and weed them to save space. The only way to access a document’s versions is through that document.

Recognising these limitations, I put together a utility which addresses most of them. My free Revisionist, and its complementary DeepTools, help you copy and move files between volumes, even over the Internet if you wish, while preserving all their saved versions. Revisionist will open any file type and let you see full details of every version of that document, including their sizes. You can open or preview them too, letting you create composites from older versions, and save every revision to compare changes in each.


Although it can’t break into the .Document-Revisions-V100 folder to tell you what’s there and how much space it uses, it does have a crawler feature which analyses all the versions of files in any chosen folder. You can then open individual files and delete versions which are taking excessive space.


If you’ve not used the rich features of the macOS versioning system, and use apps which support it, perhaps it’s time to discover how useful it can be. Although I don’t use it daily, when I do use it, it gets me out of holes that nothing else ever could. It’s one of the most important productivity features in macOS.