One of the biggest problems in trying to work with the macOS versioning system is its lack of tools. For example, the only way to discover how many versions there are of any particular document is to open that document using an app with support for the versioning system, and browsing its versions. If your versioning database has become huge, or you have problems with it, or you just need to do some housekeeping, there doesn’t appear to be any tool to help.

Well, there weren’t any.* Here are the first beta versions of a couple of tools which look specifically at the macOS versioning system: Revisionist and RevisionCrawler: revisionist10b1
and they are available from Downloads above.

Please read their brief documentation before starting to use them. They are simple to use, and currently provide information rather than performing any potentially destructive actions, but it is worth spending a few minutes understanding where they are coming from.

In many cases, you will start with RevisionCrawler. This simply iterates through a selected folder, identifies all those files which have more than the standard single version, and tells you which files to get interested in because they have many versions.

Before using this myself, I thought that I would come across a few files with a few versions, and that would be it. In fact, I have discovered that almost all my text documents have multiple versions, and the file with the highest number of versions that I have seen so far has over 1200. Having more than 100 versions is apparently not at all uncommon.

Having identified the files that are worth examining more closely, open them using Revisionist. You can do this by drag-and-drop, or through its Open command, as you wish.

Revisionist then gives the number of versions of that file known to the versioning system, and for each gives the version number, the full path to that version file, its size in bytes, and the datestamp on it, i.e. when it was saved. The last version listed is always the current version of the file which you opened in the first place.

I am here deliberately breaking an instruction by Apple, from its documentation:
Do not display any part of this URL to the user. The location of file versions is managed by the system and should not be exposed to the user.

The reason behind this is that any attempt to delete, move, or remove the file from the versioning database will damage that database. However, when diagnosing and trying to fix problems with versioning, it is important to know the location of the version file itself, which is why I reveal it here. The alternative is to follow Apple’s recommendation:
If you want to present the name of a file version, use the localizedName property.

Unfortunately, in all the cases that I looked at during development, that localised name is exactly the same across different versions, and is thus of no help in diagnosis or repair.

The important message is that you should never tamper with the versioning database or the files stored within it, unless you really do know exactly what you are doing.

In this first release, Revisionist doesn’t provide any means of thinning or removing revisions: those will come in a future release, with other maintenance features. However, the combination of RevisionCrawler and Revisionist can now at least inform you of where problems may lie.

Both apps should run on El Capitan (but haven’t yet been tested on it), on Sierra, and on High Sierra with both HFS+ and APFS. If you come across any bugs or other issues, please report them here, or let me know by email.

I hope that you find them as revelatory as I have.

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