Keeping Mac Settings in Sync with Mackup

The settings you can’t script

My dotfiles get me most of the way to a working machine. Packages installed, shell configured, editors set up, all from a couple of commands. What they don't cover is the pile of preferences that live inside applications, buried in plist files and Application Support folders nobody wants to copy by hand.

That’s the gap Mackup fills. It knows where a few hundred applications keep their configuration, moves those files into a folder you control, and symlinks them back to where the app expects to find them. Put that folder somewhere that syncs and a second machine picks up the same settings.

I’ve mentioned it in passing in my post on dotfiles, where it handles the parts I never managed to turn into shell scripts. Here’s the actual setup.

Installing it

Nothing surprising. On both the old and the new machine:

brew install mackup

That’s the whole install. The interesting part is the configuration file, and Mackup does not create that for you. You write ~/.mackup.cfg yourself.

Telling it where to put things

Mine goes to iCloud, so a dead machine doesn’t take the backup down with it:

[storage]
engine = icloud
directory = Mackup

The [storage] header matters. Drop it and the two keys below are silently ignored, which is a fun half hour to spend. engine also takes dropbox, google_drive and file_system; the last one needs an extra path key and is what you’d reach for if you want the backup to land inside a folder your dotfiles already sync. directory is only the folder name inside that storage, and Mackup is the default anyway, so you can leave it out.

Two more sections are worth knowing about:

[applications_to_ignore]
ssh
gnupg

[applications_to_sync]
git
vim

They don’t stack the way you’d expect. applications_to_sync is an allowlist, and the moment you use it Mackup stops looking at anything else. I run the ignore list instead and let the default set do its thing, mostly because I’d rather forget to exclude something than forget to include it. The names come from mackup list, not from the app’s display name.

Backup, transfer, restore

1. On the old machine, run mackup backup. Your files move into the storage folder and symlinks take their place.
2. Wait for iCloud to genuinely finish uploading. Check the folder in Finder; Mackup has no idea what your sync client is up to.
3. On the new machine, install Mackup, put the same .mackup.cfg in your home directory, then run mackup restore.

mackup uninstall reverses everything: the real files get copied back out of storage and the symlinks are removed. Run it before you wipe a machine, otherwise you leave applications pointing at links that resolve to nothing.

Applications Mackup doesn’t know

The supported list is long but it will not have your niche thing. Create a ~/.mackup directory and add one .cfg file per application:

[application]
name = My personal synced files

[configuration_files]
.gitignore
.config/someapp/config.toml

Paths are relative to your home directory, and directories work as well as files. Run mackup list afterwards and your entry should show up alongside the built-in ones. If you name it after an application Mackup already supports, your file replaces theirs rather than adding to it.

The part that bites

Symlinks. The entire model rests on them, and macOS 14 stopped playing along. Symlinked .plist preference files get reset or quietly rewritten by the system, so an application you were sure was synced drifts back to its defaults, and you only notice weeks later when a keyboard shortcut is gone. There are open issues about this (#1924 and #1950) and nothing Mackup can do about it from its side.

So my rule now is dull but it holds: anything that keeps its settings in a plist goes into [applications_to_ignore], and Mackup gets the dotfile-shaped configs it was always good at. That’s a narrower job than the README suggests, and it’s still the job I needed doing.

Before you trust it

Run mackup backup once on a machine you can afford to break, then go and look at what actually moved. This is a tool that rearranges your home directory, and it’s worth knowing exactly which files it took before you find out the hard way at three in the morning on a fresh install 😅

‘Till next time!