Version Control with Git for Your Keyboard Maestro Macros

I’ve talked quite a bit lately about learning to automate things on the Mac using the fabulous tool Keyboard Maestro. Keyboard Maestro is essentially like a little programming language with a graphical user interface, but it’s missing an essential part of any document creation tool – there’s no way to save versions of what you create. If you change something in one of your macros, there’s no way to get back to a known good version.

If you’ve got a simple little macro you’re working on with 3 steps and you try to add a 4th step and it falls over in a heap, it’s pretty easy to roll back the change by removing that 4th step. But what if you’re working on a more complex macro with 20 or 30 separate steps and it’s almost working, but you tweak it in a couple of different places over the course of days or weeks and it breaks? How do you figure out what you changed?

Mike Price worked out a really nifty macro for me that streamlines the addition of chapter marks into my recording software, Hindenburg. If you like the chapter marks in the NosillaCast, you should thank Mike for them.

When something got fiddly with the macro, I started poking at it changing things. For a while it got better, but then whatever I did completely broke the macro. I’ve had to ask Mike to send the original to me again and now I have to try to get it back to the configuration that did work.

Since Keyboard Maestro doesn’t have its own built-in version control, I went on a hunt for a way to do this.

In the Programming By Stealth podcast, Bart Busschots taught a 20-part mini-series within the series all about version control, and specifically the tool Git to do version control. It’s pretty nerdy, but I’ve really grown to enjoy the safety net that it creates when I program. Not that I would ever break my own code of course.

With Git, when you want to save a version of a file, you do what’s called a commit. When you commit, you also add a commit message. This commit message tells future you something about that version of the file. These commit messages are essential to figuring out which version you might want to roll back to.

All of these committed versions of the same file live on your computer, but you can also push them to another machine on your network for safe keeping, or push them up to a repository on the web such as GitHub or Bit Bucket. It’s all built into the Git system. If you mess up your code (or any kind of document you put into Git) you can always revert back to a previous version by looking at those commit messages you carefully crafted.

When I decided I really needed a way to do version control on my Keyboard Maestro macros, my first thought was to do it in Git. I had no idea how hard this would be. The good news for you is this isn’t going to be a 20-minute dissertation on everything I tried to do and how it failed and finally I figured it out. Nope, I Googled for Keyboard Maestro and Git and discovered someone else had solved it already. I’m glad I found this solution because I never would have known how to do what this somebody did.

The reason this problem is a sticky wicket is that Keyboard Maestro doesn’t store each macro you create in its own file — everything is one giant file in the file system. In Keyboard Maestro, you save macros in groups and can have them work only in specific applications, so that makes this one file even more complex.

The hero of this story is a lovely gentleman named Dan Thomas. He solved this problem, and interestingly he used Keyboard Maestro to solve it. He created two macros: Macro Repository Updater and Macro Repository Importer. He released both of these macros on GitHub and made them open source under his own, very generous license. This means you can download his macros, open them in your own copy of Keyboard Maestro and use them.

The first macro called Macro Repository Updater saves all of your groups and macros within them to individual source files. This solves the main problem of all the macros being mashed into one file, and preserves the groups. It takes a while the first time you run it because it’s got to disentangle all of those files and sort them into separate folders.

After the first time you run the Macro Repository Updater macro into a folder, you can then initialize the folder as what’s called a Git repository, and commit all of the files for the first time. This action gives you that precious save state as of when you ran Dan’s macro.

Dan’s Macro Repository Updater macro creates a folder structure that starts with a folder called Data. Inside Data are folders that start with your Group names and have a long UUID appended to the end. Inside each of these folders are your macros, and they also have a very long UUID appended to the end of their names.

So far so good, we’ve got a Git repo filled with the current state of our macros. Now let’s say we go work on Mike Price’s Hindenburg macro. We change a few things and it seems to be working. We can now run the Macro Repository Updater and it runs much more quickly because just that one macro gets exported to the Git repo. We can run the Git commands to commit that one macro and most importantly add a message for future us telling us what we changed.

Now let’s say we break Mike’s macro and we want to go back to a known good version. This is when the second macro Dan Thomas wrote comes into play. The second one is called Macro Repository Importer, and it does what you suspect, it lets you restore previous versions of your group or macro source files into Keyboard Maestro. I haven’t tested that part of the process yet, but I really should when I’m calm and haven’t actually just broken something!

You can use Dan’s macros to just keep version-controlled macros on your computer, or you can then also push the macros to GitHub or BitBucket or even another machine on your local network to make sure they’re safe. I’m doing that with my macros and it makes me feel warm and fuzzy to know that all of these versions of the files are protected.

Let’s review the process to follow then to keep versions of your macros:

1.  Change/create/delete a macro in Keyboard Maestro
2.  Run Macro Repository Updater macro
3.  Either from the command line or a GUI Git tool
    ⁃   stage and commit changes to that macro
    ⁃   push to GitHub or whatever other repo if desired

The hard part is to remember to keep running Dan’s macro and committing the changes right when you make them. I’m sure I’ll remember on the trickier macros but I’ll make you a dollar bet that I get too lazy to do it on the smaller macros!

Dan’s macros are really well documented in his GitHub repository, so I’m actually not going give you any more detail on it. If you use Keyboard Maestro and if you know Git, I highly recommend you check out his repo and follow his instructions.

I’m really happy that Dan figured this out, and I’m really happy that he gave it back to the community, and I’m really glad that Bart taught us all about Git. Of everything he’s taught us, I think the miniseries on Git is the part that people write to us the most about saying they appreciate what they’ve learned.

Now I have to go back and figure out how to get Mike’s Hindenburg macro working again!