In this last batch of updates to my apps for the next few weeks, there are four more popular tools, covering Unicode normalisation, appexes, logs, and document versions.
Unicode normalisation
Perhaps the earliest problem with APFS was its lack of Unicode normalisation for file and folder names. This has been a standard way to address accented and other characters that appear identical but have different codes. Apple addressed that, first in providing a normalisation layer on top, then by incorporating it into APFS. However, it can still prove a problem, both within apps and when working with other file systems. Apfelstrudel is a simple app that reveals any potential problems with normalisation, and helps you use the form most appropriate. Version 1.6 has an overhauled interface, and has been rebuilt with a new app icon ready for macOS 26 Tahoe. This version supports macOS from Big Sur onwards.
App extensions, or appexes, are numerous in recent versions of macOS, and widely used by apps. This simple utility shows all those managed by PlugInKit, complete with their UUIDs, to help you manage them. Version 1.1 has an overhauled interface, and has been rebuilt with a new app icon ready for macOS 26 Tahoe. This version supports macOS from Sonoma 14.6 onwards.
AppexIndexer 1.1 is now available from here: appexindexer11
and from its Product Page. It doesn’t yet support auto-update.
Logs
Until I started development of LogUI, Ulbow was my preferred app for browsing the Unified log. It has extensive features, with full support for the use of predicates, a chart showing the most frequent sources of log entries, and support for creating and using logarchives, including those from iOS and iPadOS. Unlike LogUI, it uses the log command to obtain log extracts, enabling it to show entry times in nanoseconds. It also displays extracts in Rich Text rather than as a list. Version 1.11 fixes a crashing bug when handling some logarchives, has an overhauled interface, and has been rebuilt with a new app icon ready for macOS 26 Tahoe. This version supports macOS from Big Sur onwards, and is recommended for all users.
Ulbow 1.11 is now available from here: ulbow111
from its Product Page, and via its auto-update mechanism.
Document versions
While Revisionist (also recently updated) provides a suite of tools to work with macOS document versions, Versatility handles one of those tasks with greater ease, creating version archives, and reconstituting them into documents. Simply drop a file onto its window and it will be converted into a folder containing each saved version as a separate document. Drop one of those archive folders onto its window and it will be reconstituted into a document with all those previous versions. This makes it simple to preserve versions when moving documents between volumes or computers, and for archival purposes. Version 1.1 has been rebuilt with a new app icon ready for macOS 26 Tahoe, and supports macOS from Big Sur onwards.
Most of my other apps that haven’t yet been updated for Tahoe should still run perfectly well, although their app icons won’t appear the same as before. I’m now turning my attention to the successor to SilentKnight and Skint, and my virtualisers Viable, ViableS, Vimy and Liviable. Once I’m done with those, I’ll return and complete my other apps.
This next batch of updates to my apps includes more popular tools, covering iCloud, document versions, sparse bundles, and Time Machine backups.
iCloud
Cirrus gives you detailed insight into what’s stored in iCloud Drive, provides a ready-made log browser for checking what’s going on, and a simple test for syncing. Version 1.16 has an overhauled interface, and has been rebuilt with a new app icon ready for macOS 26 Tahoe. This version supports macOS from Big Sur onwards.
Cirrus 1.16 is now available from here: cirrus116
from its Product Page, and via its auto-update mechanism.
Document versions
Revisionist gives you direct access to versions of documents saved automatically by macOS, and a powerful suite of tools to work with them. You can run checks to discover which documents have saved versions, then browse those, previewing them with Quick Look. It can save individual versions as new files, and create archive folders containing all versions, that can be reconstituted into the original with those versions preserved. Version 1.10 has an overhauled interface, and has been rebuilt with a new app icon ready for macOS 26 Tahoe. This version supports macOS from Big Sur onwards.
Spundle creates and maintains sparse bundle disk images, offering a range of supported file systems, and features such as compaction to maintain their efficiency. Version 1.9 has an overhauled window, and has been rebuilt with a new app icon ready for macOS 26 Tahoe. This version supports macOS from Big Sur onwards.
Spundle 1.9 is now available from here: spundle19
from its Product Page, and via its auto-update mechanism.
Time Machine backups
The Time Machine Mechanic, T2M2, is the standard utility for checking your Mac’s Time Machine backups. It checks and reports on their performance, free space on backup storage, how much has been transferred in each backup, and much more. Version 2.03 has an overhauled interface, and has been rebuilt with a new app icon ready for macOS 26 Tahoe. This version supports macOS from Big Sur onwards, backing up to APFS.
Depending on any changes finalised in the full public release of Tahoe later this year, I may need to make further adjustments to its code.
T2M2 2.03 is now available from here: t2m2203
from its Product Page, and via its auto-update mechanism.
Although there was no ambiguity in Apple’s announcement that later this year it will be releasing macOS 26 Tahoe, together with version 26 of its other operating systems, there have been claims that this might just be a ‘marketing version’ and not really the case. There is some evidence that could be misinterpreted as confirming that, where some of Apple’s developer web pages refer to macOS 16.
But others choose to differ.
Cast your mind back five years to macOS 11 Big Sur, when what had been expected to be macOS 10.16 but was announced as 11.0 instead. That had the potential to upset a lot of code and scripts that had become used to checking the minor but not major version number. Apple foresaw those problems, and devised an ingenious scheme that allowed Big Sur to be simultaneously both 10.16 and 11.0. It’s hardly surprising that has been implemented once again for Tahoe.
Rules
There are two fundamental rules provided by Apple:
In compiled languages, the version returned by macOS depends on the SDK which the software has been built against. When built against the 15 SDK or earlier, Tahoe returns 16 for compatibility with previous numbering and all existing apps; when built against the 26.0 SDK, it returns 26.0 for forward compatibility.
In scripted languages run within a shell environment, there’s an environmental variable to control the version number given. Set SYSTEM_VERSION_COMPAT=1 and Tahoe returns 16; leave that variable unset, or SYSTEM_VERSION_COMPAT=0, and it returns 26.
AppleScript
Move a script across to Tahoe, and it will be compiled in the 26 environment, so system version of (system info)
returns 26.0, as will that code inside an AppleScript app built on Tahoe.
Scripts and other languages
One method commonly used to look up the macOS version number is to obtain the string value for the ProductVersion key in /System/Library/CoreServices/SystemVersion.plist. However, depending on the environment of the caller, Tahoe plays tricks with that file, which should return a version of 26.0. If the caller has set SYSTEM_VERSION_COMPAT=1, then the version number returned isn’t obtained from that property list at all, but its companion SystemVersionCompat.plist, which is 16.0.
You can test this at the command line, by entering the two commands SYSTEM_VERSION_COMPAT=1 cat /System/Library/CoreServices/SystemVersion.plist
and SYSTEM_VERSION_COMPAT=0 cat /System/Library/CoreServices/SystemVersion.plist
Which is it – 16 or 26?
macOS Tahoe is very definitely, and not just for marketing purposes, macOS 26, but depending on how you ask that question, it could pretend to be 16 if you wish.
With strong rumours that Apple intends changing its version numbering system for the next major release of macOS and its other operating systems, it’s a good time to see how we got to macOS 15.
Early Classic Mac OS
The first version of Classic Mac OS released with the original Macintosh 128K naturally came with System 1.0 and Finder 1.0. Within a few months, version numbering was already becoming confusing, when the successor System Software 0.1 had apparently started at 0.0, but the System itself had reached 1.1. This worsened when System Software 1.0 was released two years later, and came with System 3.1 and Finder 5.2.
Apple then adopted its first triplet numbering scheme that resembled modern Semantic Versioning in System 6.0 of June 1988. Over the following three years that worked its way steadily up to version 6.0.8, then handed over to System 7 on 13 May 1991 without any minor versions being released.
System 7
The first full use of the triplet numbering scheme came with System 7. That had four minor versions, 7.0, 7.1, 7.5 and 7.6, with each having patch releases such as 7.0.1 in between. This scheme followed the rules:
the first number gives the major version;
the second number gives the minor version that should remain backward-compatible in its changes;
the third number gives the patch version denoting backward-compatible bug fixes.
It was then that Apple started to release special versions of Mac OS to support new models, for example 7.1P5 for Performa models, complicating the numbering. This was even worse with System 7.1.2, which was only supplied with some early Power Macs and a few 68K Quadra models. That was accompanied by System 7.1.2P, a special version for models released around the time that Apple also released System 7.5, in September 1994.
System 7.5 brought a different numbering scheme to deal with exceptions. For example:
System 7.5.3 Revision 2 followed 7.5.3 without any Revision 1, and made various improvements;
System 7.5.3 Revisions 2.1 and 2.2 were released on the same day to address problems with Revision 2 on different models;
System 7.5.4 was never released at all, and the next release was 7.5.5.
Fortunately, the remaining versions of Classic Mac OS were conventional in their numbering, until the last in Mac OS 9.2.2 in December 2001.
Mac OS X
The public beta of Mac OS X introduced build numbers to supplement their triplet version numbering. At this time, the build number was based broadly on three components:
the first number or build train gives the major version, starting from 4 for 10.0, as this includes NeXTSTEP up to version 3;
the letter gives the minor version number, starting from A, which can also be bumped for hardware-specific builds, so may not match the triplet minor version number;
the remaining number is the sequential build number within that minor version, usually incremented daily. That’s normally three digits, but an additional digit can be prefixed to indicate specific hardware platforms.
Triplet versions and build numbers were surprisingly well behaved until 2010, although separate build numbers were used during the transition from PowerPC to Intel architecture in Mac OS X 10.4 Tiger.
The first signs of complications came with Mac OS X 10.6.3, in March-April 2010, which came in three different builds and a v1.1, and 10.6.8 also had a v1.1 released a month after the original update. Mac OS X 10.7 Lion set a trend for a final Supplemental Update to 10.7.5, and frequent Security and Supplemental Updates became the rule by 2018, with macOS 10.12 Sierra and its successors.
By 2019, these updates had become uncontrollable. macOS 10.14 Mojave, for example, had three Supplemental Updates in the two months after its final release, named as 10.14.6 Supplemental Update, 10.14.6 Supplemental Update (a second time), and 10.14.6 Supplemental Update 2 (really 3).
macOS 11
The first version of macOS to support Apple silicon Macs, macOS 11 Big Sur, had been generally expected as macOS 10.16, but shortly before its announcement at WWDC in June 2020 the decision was made for it to become macOS 11, incrementing the major version number for the first time in almost 20 years. As that reset the minor version number from 15 to 0, there was the potential for chaos, as many scripts and much code had come to ignore the major version number, and to rely on the minor version to determine which release was running.
To cater for this, when those checked ProcessInfo.processInfo.operatingSystemVersion.minorVersion (or its equivalent), Big Sur identified itself as macOS 10.16. Apps ported to Xcode 12 used the 11.0 SDK; when they checked ProcessInfo.processInfo.operatingSystemVersion.minorVersion (or its equivalent), Big Sur identified itself as macOS 11.0. Those who relied on command tools were provided with a workaround, as sw_vers -productVersion
returned 10.16 when running in Big Sur on an Intel Mac, but 11.0 on an Apple Silicon Mac.
This enabled Apple to return to a triplet scheme without the complications of Supplemental Updates or other vagaries. Each year’s major version of macOS has thus been x.0, with scheduled minor versions numbered from x.1 to x.5 or x.6, and intermediate patch releases (usually security updates) from x.x.1 upwards. At the end of its year as the current release of macOS, x.6 marked the start of its first year of security-only support, and x.7 for the second and final year. The exception to this has been Sonoma, which started its first year of security-only support with version 14.7, so its security updates have coincided in their minor and patch numbers with the older Ventura.
The only complication to this much clearer system was introduced in Ventura with Rapid Security Responses (RSRs). Those didn’t change the triplet version, as macOS proper remained unchanged, but added a letter to form, for example, macOS 13.4.1 (c). That proved clumsy, and when reflected in a resulting Safari version number it broke a lot of major websites that were unable to identify the browser version correctly. Since RSRs have fallen out of favour, this proved to be a passing phase.
When I wrote about the unexpected change in version numbering brought in Big Sur, I claimed that “no matter what Apple may eventually settle on, I shouldn’t have to change that again for many years.” I’m not sure that five counts as many, but here we go again.
Support for document versions in iCloud Drive has a curious history. Both iCloud Drive and the macOS versioning system were introduced in OS X 10.7 Lion, in 2011, but haven’t fully integrated over those 14 years. Until 2018, versions were only saved locally and never propagated to other Macs and devices through files shared in iCloud Drive. Then sharing of versions was added, but proved patchy and unreliable, although sometimes versions were propagated in a frenzy. By 2023, that experiment had ended, and behaviour reverted to the original. This article explains how it works now.
Demonstration
To show this, I used Versatility to convert a Pages document into a folder containing each of its seven versions, and moved that folder into iCloud Drive. Once there, I dragged and dropped that folder onto Versatility again to convert it back to a versioned Pages document in my iCloud Drive folder. I then dropped that onto Revisionist to browse those versions and confirm that they remained good.
Although the current version is located in iCloud Drive, with a path from ~/Library/Mobile Documents/com~apple~CloudDocs/, each of its previous versions ‘has local contents’ in a path from /System/Volumes/Data/.DocumentRevisions-V100/PerUID/501/, inside the Data volume’s version database.
On another Mac connected to the same Apple Account and iCloud Drive, that document only has the current version, again with ‘local contents’, as its previous versions are left stored on the other Mac.
If you then edit that document on the second Mac and save a new version there, then make more changes and save another version, those previous versions will remain stored in the second Mac’s version database, but only the current version will be synced to iCloud Drive, and appear as the current version on the first Mac. That still sees the six previous versions stored there from before, but can’t see those added by the second Mac.
Conclusion
Thus each Mac and device – as this applies similarly to versions saved in iOS and iPadOS – sees the common current version synced across iCloud Drive, and only those older versions created and saved on that Mac or device. There is no sharing of document versions in iCloud Drive.
While this behaviour is reliable and consistent, unlike the profusion of versions that occurred in macOS Mojave, it demonstrates how readily versions are discarded when they could or perhaps should have been preserved.
Beware Sonoma
In this respect, I have one important warning concerning versions and iCloud Drive: never use those in macOS Sonoma 14.4. That version of macOS has a serious bug that strips all local versions from any document that’s evicted (its download is removed) from iCloud Drive. Apple fixed that swiftly in the update to 14.4.1, so if you are still using Sonoma, ensure it’s 14.4.1 or later.
How to transfer document versions through iCloud Drive
If you need to work on a document with shared versions, the only solution is clumsy but effective, using Versatility. Keep the live document outside iCloud Drive, in local storage, and transfer it in iCloud Drive using its folder archive generated by Versatility:
Edit the local document on Mac A. To transfer it, drop it on Versatility and save its folder archive to iCloud Drive.
On Mac B, drop the folder archive in iCloud Drive onto Versatility, and save that to its local location for editing there.
To return the live document to Mac A, drop it onto Versatility, and save its folder archive to iCloud Drive, ready to reconstitute on Mac A.
Postscript: Use a disk image
I’m very grateful to @Remo_Pr0 for suggesting an alternative method: save the document in a disk image that you keep in iCloud Drive. Provided that’s larger than 1 GB (smaller sizes are unable to create a local version database), versions will be saved inside the disk image, and preserved for all those Macs that access that document within it. This should also work with a sparse bundle either in iCloud Drive, or in a network share.
If you can think of a better way, please let me know so I can code it into Versatility.
In my introduction to the macOS document versioning system, I explained that a document could lose all its saved versions when moved to another volume. This sequel provides more detail about how you can preserve or lose those saved versions.
When you save the first version of a document, a record is created in the hidden database on the same volume as that containing that document. That record refers to the file not by its name or path, but by its inode, its unique file system number. Anything that preserves that inode number will thus tend to keep its saved versions; anything that creates a new file with its different inode number is guaranteed to lose all versions.
What’s safe
The following actions are version-safe:
moving the file anywhere within the same volume;
renaming the file, changing its permissions, adding extended attributes, adding a custom icon, or editing the file’s data;
creating a Finder Alias or symbolic link to the file;
rolling back a local snapshot, which will return the versions to the same state as at the moment that snapshot was made; volume snapshots include the whole version database, and preserve inode numbers;
‘cloning’ the whole volume to make an identical copy of everything in it;
if the file is stored inside a disk image, then that disk image can be copied or moved safely, or backed up; that also applies to files stored inside Virtual Machines.
What loses versions
The following actions are destructive of versions:
moving the file to a different volume; the original file on its original volume will retain its versions, but they won’t copy across to the new volume;
duplicating the file; the duplicate, an APFS clone file, will have no versions at all;
saving the file as a new file, with a Save As command;
compressing or archiving the file; the copy in the archive won’t have any versions;
saving the file to a file system like ExFAT or MS-DOS, which don’t support versions;
backing the file up to another volume, as versions can’t even be backed up by Time Machine;
moving or copying the file over a network.
If you try to save versions on a file system that doesn’t support them, you aren’t warned when saving those versions, as those appear to remain cached. Normally the first warning is given when you try to close the file.
If you want to keep versions, click on Cancel and save that file to a volume that does support versions.
The version database can only be created on a volume that has sufficient space to support it. This doesn’t normally affect working with regular APFS volumes, but can be a problem if you’re intending to store the file in a disk image or sparse bundle. You should find that a minimum size of 1 GB will support limited versions, but 500 MB is definitely too small for support, and will result in a warning when you try to close the file.
iCloud Drive
The behaviour of versions in iCloud Drive might appear confusing unless you remember the rule that they are saved for that file’s inode number. Here I’ll look at the example of a file that’s in a different folder from iCloud Drive (or Documents in iCloud) and is moved to iCloud Drive.
If that file is already in the current Data volume, that’s the same volume as local copies of what’s in iCloud Drive, so moving it to iCloud Drive keeps it within the same volume, and versions are preserved. If that file is evicted from local storage, that only removes the data for that file, and doesn’t change its inode number. When the file is downloaded again and opened, its versions are still there.
On another Mac connected to the same iCloud Drive, though, the versions are on a different volume on another Mac, so if that opens the file, there are no saved versions available. If that Mac adds its own versions to the file, they will be saved locally, and will be accessible to that Mac.
Saving versions to files already in iCloud Drive is more complex, as different versions of macOS, iOS and iPadOS have saved some into iCloud, so I will look at that in a separate article.
Preserving versions whatever
The only way that I know to preserve all the versions of any file is to save each of them individually in a folder, numbered so that the original versions can be recreated on another volume. While you can use my utility Revisionist to do that, a simpler drag-and-drop approach is provided by Versatility.
There’s no screenshot to show: all you do is drag a file with versions onto Versatility’s blue landing pad. You’ll then be prompted to name and locate the folder it creates containing the file’s versions. Once made, you can move them around like any other Mac folder, back them up, Zip the folder and send it to a colleague.
To reconstitute the original, simply drop the folder onto Versatility’s pad. You’ll then be prompted for the name and location of the file to be saved. That file will contain all the versions saved in the original, ready to use.
If you wish, you can edit the versions in the archive folder created by Versatility. When the file is reconstituted the individual versions will simply be reassembled in numerical order.
I’m also delighted to confirm that both Versatility and Revisionist are fully compatible with macOS Sequoia.
Key point
Versions are linked to the inode number of their file. Actions that preserve that on the same volume should retain those versions. Anything that creates a new inode number or uses a different volume won’t retain those versions.
The versioning system built into macOS for the last 14 years must be among its least used features, with many simply ignoring it, and some even blocking it from working. Yet among those who do use its features, it’s probably used more often than backups, and to greater effect.
A couple of weeks ago, when I was working on the code for AppexIndexer, I realised that the changes I was making to enable its search feature were getting out of hand, and should I need to undo them would have required a lot of work. Because the code editor in Xcode supports macOS versioning, I paused my editing for a few moments, opened that document’s versions and stepped back through them to reach the version saved just before I had started making those changes. I then saved that version as a separate fallback copy and resumed my editing.
All this had happened since the last Time Machine backup, which would have been of little use had I needed to revert all those changes. Even automatic hourly backups are too infrequent to capture changes as we make them in active documents. This is just what the versioning system is intended to capture, although to make best use of it, you’ll need third-party software.
Standard access
Most apps that edit documents now support the macOS versioning system by default. Some allow you to auto-save documents as you’re working on them, but all should create a new version each time you save a document. Normally, you might access saved versions using the Revert To… command in the app’s File menu, where you can Browse All Versions… in a full-screen window resembling Time Machine’s interface to it backups.
Although the design looks impressive, it’s not the only means of browsing a document’s saved versions, and in many respects doesn’t support the power and flexibility in the versioning system.
How it works
Many macOS apps that edit documents are based on AppKit, supporting actions in their File menus including Save and Revert To…. Each time you save a document, that automatically uses the Foundation API to save a copy in the hidden version database located in the folder .DocumentRevisions-V100 at the root of the volume on which that document is stored. When you Browse All Versions macOS finds all the previous versions of that document in the volume’s database and displays them, making them available to revert to. Although document-based apps developed using SwiftUI are still relatively unusual, they too should provide full support for versions and the same menu commands.
This relies on:
support in the editing app;
the document being stored in a volume in APFS or HFS+ format; ExFAT, MS-DOS and other file systems don’t normally work, and can’t save versions;
the hidden folder .DocumentRevisions-V100 containing the local version database for that volume.
Although a document’s versions are normally accessed through an app that can edit that document, that isn’t a requirement, and there are several alternatives that can access and manage any versions, including Versions from the App Store, and my own free utilities Revisionist, Versatility and Deep Tools, whose use I will explain in further articles.
On APFS volumes, the version database appears to use clone files to good effect, in preserving changed storage blocks for each saved version, so using a minimum of space.
How it doesn’t work
The biggest limitation of versions is that they don’t move with the document. When you copy or move a document with versions to a different volume, its versions don’t go with it, although moving it within the same volume preserves them intact. Any document only retains the versions created during its editing on its current volume.
Say you have been working on a file named MyBigDocument when it’s stored in your ~/Documents folder, and there are versions saved for it there. Copy that to an external disk, and that copy now has no versions at all. Edit it there, and it will build its own collection of versions on that disk, but you won’t be able to access those if you open MyBigDocument from your ~/Documents folder. You can use my utilities to move its versions around from volume to volume, or to another Mac, but left to its own devices, macOS doesn’t do that for you.
Versions become complicated in iCloud Drive. iPhones and iPads also use versions, but their behaviour in iCloud storage has changed over time. I will explore current behaviour in Sequoia in a separate article.
One common fear of using versioning is that the database can accumulate a seemingly unlimited number of versions of files, and consume large amounts of space. You can get a good estimate of how large a volume’s version database folder is using the Terminal command sudo du -sh [pathtovolume]/.DocumentRevisions-V100
followed by authentication. The correct path to use for that on the current Data volume is /System/Volumes/Data/.DocumentRevisions-V100.
macOS doesn’t provide any means of editing what’s stored in the versions database, nor of weeding old versions. On one of my Macs, its internal Data volume currently has several documents for which there are more than 100 versions, with a maximum of 153. However, the versions database on that volume is only 38 MB for a total of more than 35,000 files in ~/Documents.
Practical use
In addition to my example at the start of this article, I quite frequently use versions as an extended undo. Some minutes into an editing session I might realise that an earlier change such as deleting paragraphs needs to be undone. Rather than working my way back through a long series of Undo commands, the easiest way to fix that is to open the document’s versions using Revisionist, locate an earlier version containing the deleted paragraphs, copy those from that version and paste them into the current document that I’m editing.
Some documents have important previous versions that I want to preserve when I move them across to another Mac or to external storage. For those I drag and drop the document onto Versatility to create a folder containing all that document’s versions, move that to the other Mac, and drop that folder onto Versatility there. That recreates the original document with all its versions stored safely in its new location.
When certain documents have been very active, and are now complete so I don’t want to preserve all those old versions, I can clear them all by moving that document to another volume, and moving it back again. If I want to reduce the versions but keep some of them for posterity, then I open them using Revisionist and delete the old versions I don’t want to retain any longer.
Most important of all, I know that so long as I have saved a document, if I want to recover any previous version I can do so using Revisionist without having to look through my Time Machine backups. With macOS versioning, Command-S doesn’t just save my work, it also maintains that document’s change history.
Key points
Many apps support macOS versions. They normally feature a Revert To… command in their File menu, although not all do.
Save (Command-S) creates a new version of a document automatically, and maintains its change history.
Use additional apps like Revisionist and Versatility to get the most out of versions.
A document’s versions don’t move with it to another volume or Mac, but can be preserved using Versatility.
Documents can accumulate a large number of versions when they’ve been saved many times.
Delete all a document’s versions by moving it to another volume, then moving it back again.
Using versions gives you finer detail of changes that are lost in backups.
Login
