maintaining-macos-defaults

Use on demand to reconcile a Mac's GUI-changed settings into version control — when the user says "reconcile my mac defaults", "capture my macOS settings", or after they've changed System Settings and want the keepers tracked. Drives homedir-manager's `defaults` verb (capture/drift/apply) against a versioned desired-state file.

Jump to install

Repository: obra/homedir-manager
Last source activity: June 7, 2026 at 01:50
Detected SKILL.md language: English
Stars: 5
Forks: 0

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	maintaining-macos-defaults
description	Use on demand to reconcile a Mac's GUI-changed settings into version control — when the user says "reconcile my mac defaults", "capture my macOS settings", or after they've changed System Settings and want the keepers tracked. Drives homedir-manager's `defaults` verb (capture/drift/apply) against a versioned desired-state file.

Maintaining macOS defaults

Lets the user drive their Mac through the GUI like a normal person, then fold the settings worth keeping into a version-controlled file. The judgment — signal vs. noise — is your job; the tool just reads, diffs, and writes the macOS preferences (CFPreferences) system.

The data (in the user's dotfiles content repo, deployed to `~/.config/macos-defaults/`)

desired.tsv — the tracked settings: domain⇥key⇥type⇥value, sorted. Scalars only (bool/int/float/string). This is both what gets applied and the baseline drift diffs against.
watched-domains — one domain per line; the domains drift scans for new settings.
noise-deny — glob patterns (matched against key names) that drift and whole-domain capture ignore (window frames, recents, counters, timestamps).

The on-demand loop

When the user asks to reconcile (after they've changed settings in the GUI):

See what changed:
```
homedir-manager defaults drift ~/.config/macos-defaults/desired.tsv \
  --watched ~/.config/macos-defaults/watched-domains \
  --noise   ~/.config/macos-defaults/noise-deny
```
- DRIFT <domain> <key> current=… desired=… — a tracked setting whose live value changed.
- NEW <domain> <key> current=… — a setting they changed that isn't tracked yet.
Triage each line. Keep deliberate preferences; drop noise. A setting is signal if a person would knowingly choose it (com.apple.dock autohide, …finder ShowPathbar). It's noise if it's machine state: window positions, recent-item lists, counters, timestamps, last-opened paths, UUIDs. When unsure, lean toward not tracking it — and if a noise pattern would have caught it, add that pattern to noise-deny instead of rejecting it one-off.
Fold keepers into desired.tsv with correct types read live:
```
homedir-manager defaults capture com.apple.dock autohide >> ~/.config/macos-defaults/desired.tsv
```
Then keep the file sorted (sort -o). For a DRIFT (changed tracked value), update the existing line instead of appending a duplicate.
Commit the content repo. Other machines pick it up on git pull.

Applying on another Mac

apply writes the tracked settings into the live preferences and restarts Dock/Finder/SystemUIServer:

homedir-manager defaults apply ~/.config/macos-defaults/desired.tsv

Only run this when the user wants that machine to match the tracked state — it changes their live settings. Some settings need a logout to fully take effect.

Limits

Scalars only. Dictionary/array/date/data values are flagged (SKIP … on stderr), not written.
Covers the CFPreferences surface — most of "driving your Mac," but not settings that live in sandboxed containers, opaque databases, or need scutil/systemsetup.
macOS only.