In recent discussions here about the version system built into macOS, two potential problems were raised: first that a file’s versions don’t go with it wherever the file goes, and second that versions wouldn’t preserve datestamps. This article demonstrates how you can easily work around the first, and how the second isn’t correct.

The tools I use here are admittedly my own, but they’re free, and available from this Product Page. They’re also compatible with all versions of macOS from Big Sur (or earlier), and should work perfectly next week when Tahoe is released.

To pose my apps a challenge, I deliberately picked one of my source code files (for LogUI) that I can’t afford to move out of its current folder. This has a total of 230 versions tracking that file’s changing contents, and the development of that app, from its inception last year. Of course, as this is in Xcode I could have used a Git server for full version control, but versioning can do everything I want without going to that trouble.

These are the last few versions shown in Revisionist, simply by dragging and dropping the original file onto it. For each saved version, this displays its datestamp and size in bytes. To preview any of those, just double-click its entry and it will be opened as a QuickLook preview.

With the file open in Revisionist, I could click on the Archive button to save all its 230 versions to their own folder. However, if you just want to archive or move the file with all those versions, that’s quickest using the drag and drop feature in Versatility. Drop the original file on its window, then find the right location to save its versions in their own folder.

This is the result: the top of that folder of 230 versions, each numbered in sequence. QuickLook any of those and you’ll not only see their contents, but the datestamps on each version are those for that original saved (version) file. This original version was created on 7 July 2024, and last saved the following day.

You can now compress that folder of versions and move it wherever you want. I dropped mine onto my drag-and-drop compression utility Cormorant to turn the folder into a 16 KB Apple Archive, just 1.6 KB larger than the current version of that document. I have thought about building that option into Versatility, but you’ll probably prefer to use your own compressor like Keka.

If you wished, you could discard unwanted versions from that folder, because Revisionist and Versatility will reassemble the versions in order, and don’t notice if some of the numbers are missing. If you really wanted to, you could reorder the numbers, but that would be extremely confusing. The version system doesn’t rely on differences between versions, as it stores each version complete.

Once you’ve got your version archive where you want it, decompress it back to a folder, and drag and drop that onto Versatility. Save the file where you want it, and every one of those 230 versions is back inside it, just as they were in the original.

Here’s the copy I made earlier, seen in Revisionist, with the very first version previewed in QuickLook.

There are some relevant notes:

• Versions do still work in iCloud Drive, but each Mac only sees the versions created and saved on that Mac, not those created by others. I try to avoid mixing versions with iCloud Drive because of that added complication.
• If you select a version in Revisionist and click the Save button, the copy of that version is faithful, but is created as a new file, so has fresh datestamps.
• Versions only work on HFS+ and APFS volumes, although you can pass archived versions across any file system.

In addition to reading laid-out documents, the most popular purposes for PDFs are forms and annotation. As far as filling in PDF forms are concerned, I have just one word to say: Fillably, Joel Norvell’s outstanding app available from the App Store, which transforms Preview into the ideal platform for tax and other forms. Rather than struggling with the tangle of tools in a general PDF editor, Fillably provides the perfect suite for creating PDF forms.

Annotating PDFs is more complicated, though.

Encoding annotations

Annotations aren’t an afterthought, but a central part of PDF. All PDF documents consist of a list of hundreds or thousands of objects of different types, including annotations of the Annot type, and those are listed in one of the file’s standard dictionaries, its Annotations Dictionary, Annots.

There are at least 27 sub-types of Annot, including Caret, Highlight and Stamp, which are reflected in the annotation tools provided by apps from Acrobat to Preview. Seemingly complex annotations like popup notes are straightforward to code in PDF, requiring just two linked objects, one for the popup and its text, the other to specify its placement on the page. Others are more involved, as they can extend to include file attachments, sound, movie and other multimedia.

PDF versions

Despite their original simplicity, there are multiple problems that can arise with annotations.

With more recent versions of PDF, the ways in which they can be coded has increased. Mark up a PDF using the latest versions of Adobe Acrobat Reader or its ‘Pro’ CC colleague and they’ll cast it in PDF-1.6 and you’re unlikely to see a single Annot in their source. Most apps built on the Quartz PDF engine should write their files in PDF-1.3 so they can be accessed more widely, and should use regular Annot sub-types throughout. However, Preview likes to use opaque AAPL:AKAnnotationObjects that you won’t encounter anywhere else.

What Quartz does is to ‘flatten’ each PDF into a common 1.3 format for rendering, and that can be saved to disk. At present, that seems to work faithfully, but might give the impression that macOS can’t render more recent versions of PDF, which isn’t true. You can demonstrate that by opening an Acrobat PDF-1.6 document using an app that relies on the Quartz engine, such as PDF Expert, Preview or my Podofyllin, and comparing that with the original in Acrobat.

Podofyllin has a convenient feature for doing just that, in its source window. The uppermost of its three views displays Quartz ‘flattened’ code in PDF-1.3, the middle shows the original, here in PDF-1.6, and the lowermost is a summary of the latter.

Hidden annotations

The biggest dangers with annotations arise because of PDF’s ancient origins and a file format that doesn’t make sufficiently clear distinction between data and metadata. All annotations are metadata added to the underlying document, but in PDF, objects for each are mixed freely within the source. When they’re clearly distinguished with the Annot type, they should be easy to remove as a group, and PDF Expert offers that as a convenient command. That’s ideal when a document has been developed with the aid of reviewers’ annotations, to prepare the finished version for release.

Unfortunately this can cause its own problems, as PDF source is notorious for retaining old content that’s no longer visible in the rendered document, but can be read by anyone with a little knowledge about PDF. Like incomplete redactions, such hidden annotations have caused many embarrassments in the past, and will continue to catch folk out.

Preview’s bugs

Finally, Preview has had more than its fair share of bugs in handling PDF annotations. During my research for this article, Preview 11.0 (1069.7.1) in macOS 15.6 was generally well behaved, but did mangle comments added to a test document by PDF Expert and Adobe Acrobat. Preview has two behaviours that can appear disconcerting: that of its Highlights and Notes tool, and its use of versioning.

All Preview’s tools are single-shot apart from Highlights and Notes, the drawing pencil icon to the left of its popup menu. Click this once to apply highlighting to selected blocks of text, and to remove existing highlighted sections. Unfortunately when this tool is turned on, its own highlighting is so weak that it’s hard to see.

Overwritten files

Preview has a habit of saving PDF documents automatically when closing them, without any warning. If it has just mutilated an annotation, for example, you might assume the original file has just been overwritten and lost. However, Preview saves PDFs using the macOS document versioning system, so you can always recover the previous version.

This might at first seem an impossible task: use Preview to restore that old version and it will repeat its mutilation, defeating the purpose. Yet the original PDF editor won’t have access to previous versions, as it doesn’t use the versioning system. The solution is to use Revisionist, or Versatility, which can save the original as a separate document.

Key points

• Annotations are a central feature of PDF, come in many sub-types, and can be complicated as they can be expressed in different ways.
• The macOS Quartz PDF engine transforms them into PDF-1.3, which makes them simpler and more explicit, so they can be saved ‘flattened’.
• PDF format mixes document data with metadata and annotations.
• Few PDF editors offer to remove all annotations, and there’s a risk of some remaining hidden from view, but still remaining in the PDF source, potentially causing embarrassment when they’re discovered.
• Preview’s earlier bugs in annotations have improved, but it can still mutilate those made by other PDF editors.
• If Preview saves a mutilated PDF, you should be able to recover the previous version of that file using Revisionist or Versatility.