How to keep, or lose, a document’s previous versions

If you find the macOS feature to keep previous versions of documents useful, you may have been disappointed when you looked for previous versions only to find there weren’t any. This article explains why that might be, and what you can do to preserve those versions.

In many apps, each time that you save (or autosave, when available) a document, the previous saved version is moved into that volume’s Versioning database, a locked and hidden folder named .DocumentRevisions-V100 at the root of each volume. The database there uses inodes to reference both the current versions of documents, as saved where you want them, and previous versions contained with that hidden folder. On each volume, an inode is a unique reference to that file (or folder), which is unchanged no matter where the file is moved on that same volume.

So long as the inodes of the current document and its previous versions are unchanged, while they all remain on the same volume, the document’s previous versions remain accessible to apps which use the Versioning system.

Actions which change document inode and lose versions include:

  • Save As… a new document, which creates a new file with its own unique inode, and starts saving its own versions;
  • Finder copies and Duplicates (and copies made in Terminal), which also create a new file for the copy;
  • Copy/move to another volume (except iCloud), as the new document will have a new inode for that volume, and previous versions aren’t copied across;
  • Deleting the document, either when you empty the Trash or in Terminal, which removes its inode from the file system metadata, and all previous versions should be removed from the Versioning database;
  • Backing up (except Time Machine), which makes a copy of the document, normally to a different volume;
  • Archiving to another storage medium, which again makes a copy on a different volume.

Documents stored in iCloud used to lose their previous versions, but that has changed in more recent releases of macOS and iOS, most noticeably in Mojave and iOS 12. It’s now possible to edit the same document stored in iCloud on multiple devices, and for versions to be saved and synced across them all. However, this depends on having a good Internet connection, iCloud synchronisation being responsive, modest document size, and saving less frequently to allow versions to sync properly between saves. It’s possible for two devices to end up with different sets of versions, which can be confusing.

Documents edited using Handoff present a different problem, in that you can end up with two conflicting versions because the same document is being edited on both devices. When conflicting versions arise, you’re asked to choose which version to keep.

Although Time Machine makes backup copies of the Versioning database, previous versions aren’t accessible in Time Machine backups, nor are they restored if you restore individual documents. They may be restored when the whole volume is restored from a backup, though. Third party cloning and backup tools don’t now attempt to back up or restore previous versions, which is the most practical solution as macOS prevents direct access to the Versioning database.

The most robust and reliable way to preserve previous versions is to convert the document into a folder containing each version using my free apps in DeepTools, or Revisionist, which is a complete toolkit for accessing versions and the macOS Versioning system. These are simple to use:

  1. To convert a document and all its previous versions into an archive folder, use the DeepArchive app or Revisionist’s Archive button.
  2. You can then Zip up the folder, move or store it wherever you want.
  3. To convert an archive folder back into a document and its previous versions, use the DeepUnarchive app or Revisionist’s UnArchive menu command, and save the new file on the volume you wish to keep it on.

These work in all versions of macOS from El Capitan to Catalina.