First time use

Using MBU is incredibly easy: After installing and activating the macro, just run the •main | MacroBackerUpper macro. On first launch, you'll be taken through the setup process, which requires you to answer some setup questions.

You'll choose a name for your backups folder, as well as the location for that folder to be stored. Then you'll answer some settings-related questions (use of hard links, backup quantity limit, use of Finder, labels, etc.). You can change these settings in the future via the Settings Manager.

After this one-time setup, the first backup will run, and provide a onscreen summary of what it did—how many macros were backed up, how long it took, and how much drive space it used.

Subsequent use

Go back to work in Keyboard Maestro, then when you want a new backup, run the •main | MacroBackerUpper macro again at some point. After the second backup finishes, the macro will then compare the two backups, and generate a report on the differences between the two. Please read the Deep dive on MBU's features section below for further details on the backups and the report.

Backup summary report

When each backup and analysis is done, you'll see an on-screen summary of what was done:

From the summary, you can directly open the full backup report or the folder that was just created. Notice in the summary section that MBU shows both the total disk space taken for all backups, as well as the space taken for the most-recent backup.

The size figures you see there are the correct values; Finder will show the folder taking up much more space. That's because Finder doesn't account for the hard links, and shows every file as if it were taking up the space of the original—in the screenshot above, Finder reports 312MB of disk usage for those 12 backups. That's how much space the backups would take if copied to a new location in Finder. (See the aside on hard links for details on how to copy and retain the hard links.)

Interacting with MBU

MBU is a mostly hands-off macro: You launch it, it does its thing, then it's done. But what if you want to change your settings, or don't want a backup to run for some reason? Immediately after launching the macro, you'll see this onscreen message:

Press each key to do what it says it'll do—Control to get to the Settings Manager (see below), Option to check for updates to the macro, Command to open a list of modified macros in the last backup and choose one to see its changes in detail, and Escape to cancel the macro.

This message remains onscreen for three seconds, though you can change this in the Settings Manager. Press the Control key to get to the Settings Manager's main screen:

If you wish to cancel the macro, you can press Escape, or you can modify any of the settings used by MBU. Please read The Settings Manager section for more information on what you can do there—including safely moving your full collection of backups to a new location.

If your last backup included any modified macros (that are in the same group, with the same name, as in the prior backup), pressing the Command key on the timer box will open a list of all those macros:

The macro will first try to use OpenDiff, Apple's visual file comparison tool. However, this is only available with a full Xcode install. If Xcode isn't installed, the macro will then try to find Visual Studio Code, and use it if present. If neither of those two are available, the macro will use the built-in diff tool.

NOTE: As of version 1.3 and later, this process is built into the macro; there should be no need to do this manually.

What happens if something goes wrong? The good news is that almost nothing really can go horribly wrong, given the macro simply runs one command in Keyboard Maestro, then processes those files on you drive. But let's say something does happen—your cat reboots your Mac while the backup is running, the power goes out, whatever.

The fix for any issues related to what you think may be a partial or incorrect backup is the same:

1. Delete the troublesome most-recent backup.
2. In your backups folder is a folder named zSupport Files - Do not delete. Open that folder, and delete the database file (zDatabase.db) within it. No, really, delete it. The macro will notice it's missing, and recreate it on the next run. Do not delete the zSettings.db file!

That's really all you should have to do to recover from any backup-related issues you may have—run MBU again, and a new backup will be created, and you should be good to go.

If you have other issues related to MBU, please get in touch with me via the Keyboard Maestro forums.

This is the tool you use to modify the settings for the macro…but it's real feature is the ability to safely move all your backups to another hard drive, retaining the hard links. It's a simple choose-from-list menu:

The titles make each function self-explanatory, though it's also possible to see two additional options here: One to reset the duplicates/invisibles warnings, and another to change the method used to locate the backups folder. These will only appear when needed.

When would that be? Some users have same-named macro groups or macros, and/or macros and groups whose names start with a period. In those cases, MBU shows a dialog explaining the impact those things will have on its operations. A button in each dialog lets you suppress future warnings; if suppressed, a new entry in the Settings Manager lets you reset the warnings.

Similarly, if a backup ever fails, MBU will switch to have you manually locate your backup folder, to make sure the backup runs. If this happens to you, another option in the Settings Manager will let you switch back to automatic mode.

If you ever decide you want your backups to live elsewhere, I strongly recommend using the 'Change location (and move existing)' feature in the Settings Manager. You'll be asked to point to the new location for the backups, and then asked if you want to move them there. If you say yes (you should!), MBU will use rsync to safely copy the backups with hard links intact. It will then run a diff command to compare the two sets of backups. If they're identical, the originals will be deleted. If they're not, nothing is deleted an you'll receive a warning.

This is much easier than trying to move the files yourself, especially as you'd need to use the Settings Manager anyway to change the location of future backups.

If you use the Escape key to exit the Settings Manager, the macro will end without running a backup. To back up after using the Settings Manager, please select the 'Exit Settings Manager and run back up' entry in the list.

By default (and by design), MBU uses hard links for any files (macros) that are identical between the last two backups. This is similar to how Time Machine works, though it also uses hard links for folders, which MBU does not. The advantage of hard links is that they're incredibly small, and in most MBU backups, the majority of the macros won't have changed—so a ton of space is saved by replacing identical files with hard links.

If you'd like to know more about what a hard link is, and how it compares to both symbolic links and Apple's Finder-base aliases, The Eclectic Light Company has a great article available that explains the differences.

The main downside of hard links is that they're not easily portable across hard drives, and they confuse Finder when it's trying to figure out the sizes of folders. If you copy your backups to a new drive in Finder, each hard link will be converted into an actual copy of the source file. If one full backup of your macros takes 12MB, and you have 40 backups, your copied backups will now take 480MB of space, versus what's probably only some 40MB or 50MB using hard links.

So how do you copy your backups and keep the hard links intact? The Settings Manager included with MBU can handle moving (and verifying) your backups, and that's the recommended method of moving your backups. If you want to do it on your own, however, you should use Terminal and rsync to make sure the hard links transfer:

This will keep the hard links intact, and copy everything but the alias that points to the latest backup—don't worry, it'll get recreated on your next backup run. Make sure to run the Settings Manager in MBU to update your backup folder location if you haven't done so already. (But really, since you have to do that anyway, just let the Settings Manager copy the files for you.)

If you really don't want to use hard links, you can disable them either during setup or in the Settings Manager. Past backups won't be affected, but any future backups will be made with the original files left in place.

Each backup includes a detailed written summary of the changes from the prior backup. It's quite self-explanatory, and lays out exactly how things have changed from the prior backup. As explained in the intro above, MBU looks for all sorts of changes in your macros and groups, and then tries to report on those changes in a clear and readable way. Here's a bit of one such report:

If you elected to see the timing details in the report, you'll see a long section of task times at the bottom of the report. This probably isn't of any use, but it's geeky in a, well, geeky way. If you do happen to consistently notice one task taking a really long time, please let me know—it's quite possible there's an issue with that routine that I didn't find during testing.

Note: The analysis is the trickiest part of this macro, and there are probably things that are wrong. Some may be mistakes on my part, others may be limitations on the information available to the macro. One such example of the latter is this:

Duplicated macro groups and Renamed macro groups will show in the "Modified Groups" section of the report with every macro inside the group in a modified state. Both of these actions seem to make Keyboard Maestro change something in the every macro within the group.

As such, diff (the tool the macro uses to find out if a macro has changed or not) sees all those macros as modified. There's nothing I can do about this, as there's no way to know if the diff is different because of real changes or due to duplication or renaming. This also means those macros can't be made into hard links until the next backup is run, when diff will return valid results.

If you notice other issues in the analysis, though, please let me know—contact me via the Keyboard Maestro forums.

MBU's backups are simply folders Finder. You can treat them as you would any other folder, though as noted above, if you use hard links, copying them to new drives is a bit tricky—see the aside on hard links for details on how to do that.

MBU also (optionally, on by default) uses Finder labels to give a bit of info on what's changed in the most recent backup: Folders are labeled either gray, green, or yellow, as seen in the image at right.

• Blue labels are used to mark newly-activated macro groups.
• Gray labels indicate that this macro group is identical to the same group in the prior backup. By default, all macros within the folder will have been converted to space-saving hard links.
• Green labels indicate that there's at least one new macro within that group.
• Orange labels mark newly-deactivated macro groups.
• Purple labels indicate that the macro group was renamed since the prior backup.
• Yellow labels indicate that at least one macro within the folder has been modified.

You won't find any labels on individual macros, however. Why not? First, it's a pretty slow process, but there were ways around that. The bigger issue is that with hard links, if I set the label on one file, I set it on all the files. This means that all the labels on the old backups would be wrong.

Consider a new macro in a given backup, and it gets labeled green. You don't modify it, and run another backup. MBU compares new to old, finds no changes, so replaces the new with a hard link to the old. If labels were active, it would then label the macro in gray…which would instantly change the green label on the prior backup, as they're the same file.

Folders are never hard links, so their labels will remain intact. And to me, the most important part of MBU is backing up, the rest of it is eye candy. At least this way you have some visual clues as to what happened in the most recent backup.

Finally, a warning…

Please do not rename any of the files or folders in the backup folder; this would definitely cause some issues the next time you run MBU.

MBU uses the actual names of items for all sorts of things, and if they change in Finder, weirdness will ensue as they won't match the values in the database, and MBU will probably give up in disgust. So please, leave the names alone.

There is no "restore" functionality in this macro; it was not designed to help manage your interaction with the backups and Keyboard Maestro. You also can't directly import a macro group from Finder to Keyboard Maestro, because a macro group is just a folder in Finder. So how do you get a macro group back in?

Restoring a macro group

The most important step in restoring a macro group is the first one:

Before restoring a macro group, you must first rename that group in Keyboard Maestro if it still exists!

If you don't do that first, then when you import the old group or macro, those imported macros will wind up in the existing group, interspersed with your existing macros. (They import in a disabled state, so they're identifiable, but it's still a mess trying to get the imported ones out. Don't ask me how I know this.)

To restore an entire group (after renaming the existing group in Keyboard Maestro), in Finder open that same group's folder in the desired backup folder, select all the individual macros in that folder, and then double-click. Keyboard Maestro will create the group those macros were saved in (as long as it doesn't exist; see above!), and then import all the macros.

Restoring an individual macro

To restore any single macro, just double-click that macro. Or use the Import menu in Keyboard Maestro. It will import into its group in a disabled state—but unlike when restoring an entire group, you probably don't want to rename the existing group, as you're just trying to add one backed-up macro back into the group.

Make MBU run automatically

As delivered, MBU only runs when you tell it to. But given there's a way to stop it before it backs up (see "Interacting with MBU" in the "Using MBU" section), you can make MBU run automatic by adding a periodic trigger, as seen at right.

If you're busy and don't want the backup to run, just press Control and then Escape when you see the first dialog appear onscreen. With a periodic trigger, you'll never forget to run your backups!

Make MBU run automatically another way

If the thought of your Mac launching a backup task while you're in the middle of something makes you uneasy, you could instead use an idle trigger.

Doing it this way, the backup will only trigger when the Mac has been idle for the specified amount of time. And as most backups take only 10 to 20 seconds to run, you'll probably still be doing whatever else it was you were doing when the backup finishes.

Please run Settings Manager!

The Settings Manager controls how MBU works for you. Finder labels, hard links, backup quantity limits, countdown timer delay, and so much more all controlled in the Settings Manager. Give it a visit!