Archiving and version control for Keyboard Maestro

As much as I rely on our own Many Tricks' apps every day, there's one I rely on more: Keyboard Maestro (KM), the macro app for macOS that can do pretty much anything. How much do I rely on it? The shrunken image at right lists all of my macro groups—not macros, just the groups holding the macros. In terms of actual macros, there are over 425 at present. (These are not all user-facing; many are macros that support other macros.)

I use KM for everything from gathering monthly utility bills to inserting HTML code in blog posts to generating replacement license files for users to controlling iTunes to decrufting URLs when copying (future post coming on that one) to automatically naming and filing documents I scan to storing snippets for insertion into our apps' help files to opening oft-used URLs to adding key functionality to many apps such as Excel, Mail, Messages, Photos, Preview, Safari, etc. In short, it's the single most-used app on any of my Macs.

For as much as I love KM, it has one major shortcoming: All of those macros live in one large XML file. Yes, I back it up to many local and cloud locations, so I'm not worried about losing it. It does mean, though, that if I mangle a single macro while trying to fix something, there's no easy way to get back to the working version (assuming I've gone past the point of multiple undo steps).

But now I can recover from such stupidity, thanks to the amazing Macro Repository Suite from Dan Thomas. This suite consists of two macros: One that updates (and initially creates) the repository, and one that restores a given macro from the repository.

Usage is about as simple as it could be—install the macros, read the brief how-to and customize a few settings, then run the Update macro. When it's done, you'll find each of your macros stored in an independent file, organized into parent folders based on the groups you use in KM. Use the Importer macro to bring back a macro (or macro group); it won't overwrite what's there, so you can compare the before-and-after versions.

On its own, it's pretty amazing…but pair it with a version control system, and suddenly, my macro collection isn't such a black hole any more. Here's how I did that (it's incredibly easy to do). Because each macro is in a separate file, and is a pure text file, you can use git (built into macOS) to manage the repository. Initial setup (after you've used the macro to create the repository) is really simple.

Open Terminal and cd to the top-level repository folder—the one holding the Data folder. Once there, just use these two commands:

$ git init
$ git add Data/

Your repository is now set up. Make a change in some macro in KM, re-run the archive updater macro, then return to Terminal and run git status. Here's what I saw after I changed the icons on some macros:

$ git status
On branch master
Changes not staged for commit:
  (use "git add ..." to update what will be committed)
  (use "git checkout -- ..." to discard changes in working directory)

	modified:   Data/_URL Decrufter.4AC407D3-81E6-455D-8456-F3CC388D9181/macros/s-Check clipboard contents.B65918CF-B227-4B01-A3CF-C45183D76230.json
	modified:   Data/___ 3 - General Subroutines.2A11CBE9...etc.
        modified:   ...etc.

no changes added to commit (use "git add" and/or "git commit -a")

You can then use git commit -a to commit your changes, etc. But really, that's about everything I know about git, and I'd prefer not to manage the repository in Terminal.

Enter the GUI git clients for Mac. There are 31 to choose from, and I'll have more to say about them (from a Keyboard Maestro user's perspective) in a future post. For now, here's a screenshot from SourceTree, which I also use to track the work Peter does on the Many Tricks' apps.

This screenshot shows 14 uncommitted changes, with the changed files themselves listed in the lower left panel; the panel to the right shows the changes in the selected file. In green (new content) you can see CustomIconData, because that's the change I made. The red rows are ones that have been removed. If I'd actually changed something in the macro, I'd see a more-detailed change log, like this from a test comment I added:

You can review the changes and (if you wish) individually approve each change. But since I've already made the changes in KM, to me they're done, so I leave them all selected, add a commit message, and click the Commit button. Once that's done, the main window updates, displaying a very nice version history, highlighting the changes I just committed:

Having the repository tracked in git is useful for a few reasons. First, I can see exactly what I changed and when I changed it. Second, in theory I can roll back a macro change that's not behaving as I'd expect it to. This isn't an automatic process—and I haven't yet tested it!—but it should work like this...

First, revert the change(s) in git. This will put the pre-modified file back into the repository. Next, within Keyboard Maestro, run the Importer macro, and select the macro to import. It won't overwrite the existing macro, so the last step is to move it into place, and delete the now-not-needed bad version. (There will be a bit more work to do if that macro was referenced in other macros, as I think those references will also need updating.)

While this isn't an automatic and seamless operation, it's far far better than what I had before, which was basically nothing. I've been using the macro suite and git for a few days now, and together they're a great addition to Keyboard Maestro.