Metadata-Version: 2.1
Name: macprefs
Version: 0.3.4
Summary: Command and library to export macOS preferences.
Home-page: https://github.com/Tatsh/macprefs
License: MIT
Keywords: command line,macos,preferences,utilities
Author: Andrew Udvare
Author-email: audvare@gmail.com
Requires-Python: >=3.10,<4
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: loguru (>=0.7.2,<0.8.0)
Project-URL: Documentation, https://macprefs.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/Tatsh/macprefs
Description-Content-Type: text/markdown

# macprefs

[![QA](https://github.com/Tatsh/macprefs/actions/workflows/qa.yml/badge.svg)](https://github.com/Tatsh/macprefs/actions/workflows/qa.yml)
[![Tests](https://github.com/Tatsh/macprefs/actions/workflows/tests.yml/badge.svg)](https://github.com/Tatsh/macprefs/actions/workflows/tests.yml)
[![Coverage Status](https://coveralls.io/repos/github/Tatsh/macprefs/badge.svg?branch=master)](https://coveralls.io/github/Tatsh/macprefs?branch=master)
[![Documentation Status](https://readthedocs.org/projects/macprefs/badge/?version=latest)](https://macprefs.readthedocs.io/en/latest/?badge=latest)
![PyPI - Version](https://img.shields.io/pypi/v/macprefs)
![GitHub tag (with filter)](https://img.shields.io/github/v/tag/Tatsh/macprefs)
![GitHub](https://img.shields.io/github/license/Tatsh/macprefs)
![GitHub commits since latest release (by SemVer including pre-releases)](https://img.shields.io/github/commits-since/Tatsh/macprefs/v0.3.4/master)

Export and keep track of changes to your preferences.

## How to use

```plain
Usage: prefs-export [OPTIONS]

  Export preferences.

Options:
  -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.
  --help                          Show this message and exit.
```

`prefs-export` is the main utility. You can export preferences, generate a
[`~/.macos`](https://github.com/mathiasbynens/dotfiles/blob/main/.macos)-like script, and store the
results in a Git repository.

My primary usage is like so:

```shell
prefs-export -o ~/.config/defaults -c
```

## 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 often changing and non-useful values 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`

```plain
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`.

