maintaining-macos-defaults

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):

1. 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.

2. 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.

3. 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.

4. 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.