The other day we found a helpful command line tool option, only to discover later that the option was only available in macOS Monterey. Since we also need to target Big Sur, this would not be an option for us. So we created something to help us overcome similar issues in the future: a way to compare man pages between macOS system versions. And that’s what we want to share with you today.
The Original Problem
When testing Kaleidoscope 3 on the first release candidate of macOS Monterey, we noticed an alert that we hadn’t seen before: “Kaleidoscope” needs to be updated. That’s not the kind of message you want your customers to see less than 3 weeks after releasing a brand new major update.
The information offered by the “Learn More…” button led us to believe that we must be using Python 2 somewhere inside Kaleidoscope.
And sure enough, we found it buried in a script to extract the version number of a property list. In Python, it’s very simple to get the content of a plist entry.
Since Python 2 is end-of-life, what could be more obvious than switching to Python 3? But we quickly realized that Python is no longer installed by default on macOS. You need to have the Xcode command-line tools.
So the search went on for something simple we could use within a shell script.
The next step was the most obvious candidate to begin with. There’s a command called plutil (property list utility) for exactly that task. We remembered faintly that we tried this in the past but failed. But we tried again.
And sure enough, it worked. There’s an -extract [keypath] raw option, which we obviously missed last time, that does exactly what we needed.
#!/bin/sh
plutil -extract "version" rawBut when we ran our app on macOS Big Sur, we learned that plutil only gained this new raw format only in macOS Monterey. So we had to come up with yet another way of accomplishing our task. Here’s the current solution:
#!/bin/sh
plutil -extract "version" xml1 -o - - | xpath -n -q -e "/plist/string/text()"Building a Changelog for Man Pages
What did we learn here? It is fairly complex to figure out which tool and which options of any given tool are available on a specific release of macOS. Certainly, proper release notes by Apple would be awesome, but we’ve not been getting such detailed release notes in a long time.
What we needed is something like this:
So why not come up with a solution to this problem? Assuming the man pages are up-to-date, what if we could compare those man pages between releases? We already have an app that is pretty good at showing differences in text files. Now we just need a way to get those man pages into Kaleidoscope. And maybe a proper way of seeing which pages have changed.
We applied some shell scripting in order to get those man page source files into readable plain text. Then we put the releases we wanted to compare, in this case macOS 11.6 and macOS 12.0, into a git repository. And voilà, out of approximately 3200 man pages, 817 had changes.
But nobody wants to go through 817 changed files. The good news is, you don’t have to: A Perl version update was responsible for 492 changed files. After filtering out those and a few other simple layout and whitespace changes, the number was down to 191 changed files, A much more manageable number.
A Solution Everyone Can Use
We think that our solution can be useful to more people, so we published the formatted results on GitHub. Just clone the repository, and make sure you have Kaleidoscope installed and set up as git difftool. Enter git difftool changeset/macOS11 changeset/macOS12, and you will get this:
Now you can immediately spot that the cat tool underwent changes for macOS Monterey, because there is a blue “pencil” icon showing the modified state. Selecting the entry in the side bar reveals that it gained a new -l option. You can also see green “plus” icons that indicate new files and red “minus” icons for files that have been removed in the latest release. At the top of the left column, you can the total number of files that have been changed, added, and deleted.
If you are looking for a particular man page, just click into the search field in the lower left and start typing. There’s also ⌥⌘J for those who prefer keyboard shortcuts…
Returning to our original problem, now we can just type pl into the search field and we can spot that plutil was indeed changed for macOS Monterey.
If we had this solution in the beginning, it would have saved us time. Now we hope the existence of this repository together with Kaleidoscope can save you some time with your next project that needs to target both Big Sur and Monterey. If you feel inclined to contribute other macOS releases, contact us, and we’ll figure out how to go about it.
Try it yourself
Now check out the GitHub repository and see for yourself what’s new in the macOS Monterey command line.
# Clone repo
git clone https://github.com/kaleidoscope-app/man-diff.git
cd man-diff
# See all changes
./man-diff.sh -all
# Quickly lookup a single man page
./man-diff.sh plutil
