3

Backup structure and sync

Oliver Surke edited this page 2026-05-18 10:24:39 +02:00

Table of Contents

• Backup structure and sync behavior
• Cloud directory layout
• Mackup path change (upgrades)
• Unmanaged applications
• macOS preferences snapshot
• Default domains
• Extend domains
• Conflict resolution on restore
• Restore from another machine's Brewfile

Backup structure and sync behavior

Cloud directory layout

After ssr sync, the default layout under your cloud root is:

<cloud root>/
|-- BACKUP/                         # default SSR_BACKUP_SUBDIR
|   |-- mackup/                     # Mackup copy destination (~/.mackup.cfg directory=mackup)
|   +-- <hostname> - <hardware-uuid>/
|       |-- Brewfile
|       |-- Brewfile.bak
|       |-- unmanaged-apps.md       # apps not from brew / MAS
|       +-- macos-prefs/
|           |-- com.apple.dock.plist
|           |-- com.apple.finder.plist
|           +-- ...

Mackup path change (upgrades)

Older releases used a separate Mackup/ folder under the cloud root. Current SSR keeps Mackup under the same SSR_BACKUP_SUBDIR tree (.../mackup/). After upgrading, run ssr sync to repopulate the new location, or move your existing mackup/ tree manually if you need history without a full re-upload.

Unmanaged applications

During each sync, SSR compares every .app in /Applications and ~/Applications (configurable via SSR_APP_DIRS) against:

1. Mac App Store - bundle contains Contents/_MASReceipt/receipt
2. Homebrew Cask - bundle filename matches a cask's .app artifact

Unmatched apps are written to unmanaged-apps.md (Markdown table: version, bundle id, best-effort installer link) and logged as warnings. Disable with SSR_SCAN_UNMANAGED_APPS=false.

Link selection order for each app:

1. Sparkle feed - SUFeedURL in Info.plist -> vendor homepage
2. Known vendor map - bundle-id prefix -> official download (Adobe, Microsoft, Docker, Cursor, Anthropic, JetBrains, GitKraken, Signal, Zoom, ...)
3. Web search - DuckDuckGo: <App name> macOS download

macOS preferences snapshot

ssr sync snapshots a curated set of preference domains to <backup_dir>/macos-prefs/ (one plist per domain). On ssr restore, these are replayed after config/macos-defaults.sh, so the snapshot is the last writer.

Default domains

Domain	What it covers
com.apple.dock	Dock position, apps, hot corners
com.apple.finder	View options, sidebar, path bar
com.apple.symbolichotkeys	Global shortcuts (Spotlight, Mission Control, screenshots, ...)
com.apple.HIToolbox	Input sources / keyboard layouts
com.apple.spaces	Spaces / Mission Control
com.apple.menuextra.clock	Menu bar clock
NSGlobalDomain	Global UI, key repeat, sound, language

Extend domains

In ~/.config/ssr/ssr.conf:

SSR_MACOS_PREF_DOMAINS_EXTRA="com.apple.universalaccess com.apple.Spotlight"

Conflict resolution on restore

When a snapshot domain overlaps domains that config/macos-defaults.sh also sets, ssr restore warns and prompts:

[WARN] Pref-snapshot overlaps with declarative defaults for 2 domain(s):
       com.apple.dock, com.apple.finder

Domain `com.apple.dock`:
  Snapshot from last sync (2026-05-11T17:30:00+0200) will OVERRIDE values
  set by macos-defaults.sh.
  [A]ccept snapshot / [r]eject (keep declarative)? [A/r]:

• Default: Accept (Enter).
• r: keep declarative values for that domain.
• Non-interactive (launchd, CI): SSR_PREFS_CONFLICT_DEFAULT (accept or reject).
• SSR_ASSUME_YES=true: skip all such prompts.

Mackup overlap: if Mackup also syncs com.apple.dock (or similar), two mechanisms compete - pick one.

Restore from another machine's Brewfile

ssr restore "$HOME/Library/Mobile Documents/com~apple~CloudDocs/BACKUP/oldhost - ABCD-1234/Brewfile"

(Adjust path for your cloud provider - see Configuration-reference.)