macprefs

Command and library to export macOS preferences.

Installation

Pip

pip install macprefs

Usage

Usage: prefs-export [OPTIONS]

  Export preferences.

Options:
  -C, --config FILE               Path to the configuration file.
  -K, --deploy-key FILE           Key for pushing to Git repository.
  -c, --commit                    Commit the changes with Git.
  -d, --debug                     Enable debug logging.
  -o, --output-directory DIRECTORY
                                  Where to store the exported data.
  -h, --help                      Show this message and exit.

prefs-export is the main utility. You can export preferences, generate a ~/.macos-like script, and store the results in a Git repository.

My primary usage is like so:

prefs-export --output-directory ~/.config/defaults --commit

The default output directory is ~/Library/Application Support/macprefs.

Colours can be disabled by setting the environment variable NO_COLOR to a non-empty value.

Configuration

The configuration file is a TOML file. By default prefs-export checks for the path ~/Library/Application Support/macprefs/config.toml. Example file:

# The extend-* options extend the default values used by macprefs.
[tool.macprefs]
extend-ignore-keys = {'domain_name': ['key-to-ignore1', 're:^key-to-ignore']}
extend-ignore-domain-prefixes = ['org.gimp.gimp-']
extend-ignore-domains = ['domain1', 'domain2']
extend-ignore-key-regexes = ['QuickLookPreview_[A-Z0-9-\\.]+']
# Only set these if you want to override the default values used by macprefs.
# ignore-domain-prefixes = []
# ignore-domains = []
# ignore-key-regexes = []
# ignore-keys = {}

deploy-key = '/path/to/deploy-key'

In extend-ignore-keys and ignore-keys, a string value to ignore can be prefixed with re: to indicate it is a regular expression.

About the generated shell script

A shell script named exec-defaults.sh will exist in the output directory. It may be executed, but is primarily for copying defaults commands for use in your actual ~/.macos file.

Filtered domains and keys

Certain domains are filtered because they generally do not have anything useful to preserve, such as com.apple.EmojiCache which only has a cache of Emoji usage data.

Some keys are filtered, as they contain values that change often and are not useful, such as session IDs and UI state (e.g. QtUi.MainWin(Geometry|State|Pos|Size), NSStatusItem Preferred Position).

Automated usage

A command macprefs-install-job is included which will install a daily launchd job. The job name is sh.tat.macprefs.

Usage: macprefs-install-job [OPTIONS]

  Job installer.

Options:
  -K, --deploy-key FILE           Key for pushing to Git repository.
  -o, --output-directory DIRECTORY
                                  Where to store the exported data.
  --help                          Show this message and exit.

If the output directory has a .git directory, a commit will be automatically made. Be aware that files will be added and removed automatically.

To stop this job permanently, run launchctl unload -w ~/Library/LaunchAgents/sh.tat.macprefs.plist.

To uninstall this job, after stopping permanently, delete ~/Library/LaunchAgents/sh.tat.macprefs.plist.