os-mnemo/System-Sync-Restore
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor documentation for consistency and clarity, including formatting adjustments and minor text corrections across multiple files.

Oliver Surke
2026-05-18 10:24:39 +02:00
parent 0af70f3e54
commit fd9e198335
8 changed files with 60 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Backup-structure-and-sync.md
+20 -20
@@ -6,36 +6,36 @@ After `ssr sync`, the default layout under your cloud root is:
```text ```text
<cloud root>/ <cloud root>/
├── BACKUP/ # default SSR_BACKUP_SUBDIR |-- BACKUP/ # default SSR_BACKUP_SUBDIR
│ ├── mackup/ # Mackup copy destination (~/.mackup.cfg directory=mackup) | |-- mackup/ # Mackup copy destination (~/.mackup.cfg directory=mackup)
│ └── <hostname> - <hardware-uuid>/ | +-- <hostname> - <hardware-uuid>/
│ ├── Brewfile | |-- Brewfile
│ ├── Brewfile.bak | |-- Brewfile.bak
│ ├── unmanaged-apps.md # apps not from brew / MAS | |-- unmanaged-apps.md # apps not from brew / MAS
│ └── macos-prefs/ | +-- macos-prefs/
│ ├── com.apple.dock.plist | |-- com.apple.dock.plist
│ ├── com.apple.finder.plist | |-- com.apple.finder.plist
│ └── … | +-- ...
``` ```
### Mackup path change (upgrades) ### 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. 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 ## Unmanaged applications
During each sync, SSR compares every `.app` in `/Applications` and `~/Applications` (configurable via `SSR_APP_DIRS`) against: 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` 1. **Mac App Store** - bundle contains `Contents/_MASReceipt/receipt`
2. **Homebrew Cask** — bundle filename matches a cask’s `.app` artifact 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`. 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: **Link selection order** for each app:
1. **Sparkle feed** — `SUFeedURL` in `Info.plist` → vendor homepage 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, …) 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` 3. **Web search** - DuckDuckGo: `<App name> macOS download`
## macOS preferences snapshot ## macOS preferences snapshot
@@ -47,7 +47,7 @@ Unmatched apps are written to `unmanaged-apps.md` (Markdown table: version, bund
|--------|------------------| |--------|------------------|
| `com.apple.dock` | Dock position, apps, hot corners | | `com.apple.dock` | Dock position, apps, hot corners |
| `com.apple.finder` | View options, sidebar, path bar | | `com.apple.finder` | View options, sidebar, path bar |
| `com.apple.symbolichotkeys` | Global shortcuts (Spotlight, Mission Control, screenshots, …) | | `com.apple.symbolichotkeys` | Global shortcuts (Spotlight, Mission Control, screenshots, ...) |
| `com.apple.HIToolbox` | Input sources / keyboard layouts | | `com.apple.HIToolbox` | Input sources / keyboard layouts |
| `com.apple.spaces` | Spaces / Mission Control | | `com.apple.spaces` | Spaces / Mission Control |
| `com.apple.menuextra.clock` | Menu bar clock | | `com.apple.menuextra.clock` | Menu bar clock |
@@ -80,12 +80,12 @@ Domain `com.apple.dock`:
- Non-interactive (launchd, CI): `SSR_PREFS_CONFLICT_DEFAULT` (`accept` or `reject`). - Non-interactive (launchd, CI): `SSR_PREFS_CONFLICT_DEFAULT` (`accept` or `reject`).
- `SSR_ASSUME_YES=true`: skip all such prompts. - `SSR_ASSUME_YES=true`: skip all such prompts.
**Mackup overlap:** if Mackup also syncs `com.apple.dock` (or similar), two mechanisms compete — pick one. **Mackup overlap:** if Mackup also syncs `com.apple.dock` (or similar), two mechanisms compete - pick one.
### Restore from another machine’s Brewfile ### Restore from another machine's Brewfile
```bash ```bash
ssr restore "$HOME/Library/Mobile Documents/com~apple~CloudDocs/BACKUP/oldhost - ABCD-1234/Brewfile" ssr restore "$HOME/Library/Mobile Documents/com~apple~CloudDocs/BACKUP/oldhost - ABCD-1234/Brewfile"
``` ```
(Adjust path for your cloud provider — see [Configuration-reference](https://git.surke.de/os-mnemo/System-Sync-Restore/wiki/Configuration-reference).) (Adjust path for your cloud provider - see [Configuration-reference](https://git.surke.de/os-mnemo/System-Sync-Restore/wiki/Configuration-reference).)
Commands.md
+1 -1
@@ -2,7 +2,7 @@
```text ```text
ssr install First-time install: link binary, seed config, schedule sync ssr install First-time install: link binary, seed config, schedule sync
ssr sync One-shot backup → cloud ssr sync One-shot backup -> cloud
ssr restore [Brewfile] Restore machine; Brewfile defaults to cloud copy ssr restore [Brewfile] Restore machine; Brewfile defaults to cloud copy
ssr update [--dry-run] Pull latest ssr code, refresh launchd if needed ssr update [--dry-run] Pull latest ssr code, refresh launchd if needed
ssr schedule on|off Enable/disable daily launchd job ssr schedule on|off Enable/disable daily launchd job
Configuration-reference.md
+3 -3
@@ -11,7 +11,7 @@ If `SSR_CLOUD_PROVIDER=` appears more than once with **different** values, inter
| Key | Default | Purpose | | Key | Default | Purpose |
|-----|---------|---------| |-----|---------|---------|
| `SSR_CLOUD_PROVIDER` | `icloud` | `icloud` \| `dropbox` \| `googledrive` \| `onedrive` \| `custom` | | `SSR_CLOUD_PROVIDER` | `icloud` | `icloud` \| `dropbox` \| `googledrive` \| `onedrive` \| `custom` |
| `SSR_CLOUD_PATH` | — | Absolute path; only when provider is `custom` | | `SSR_CLOUD_PATH` | - | Absolute path; only when provider is `custom` |
| `SSR_BACKUP_SUBDIR` | `BACKUP` | Cloud subfolder for per-host backups and Mackup `path=` (`directory=` in `~/.mackup.cfg` names the `mackup/` subfolder) | | `SSR_BACKUP_SUBDIR` | `BACKUP` | Cloud subfolder for per-host backups and Mackup `path=` (`directory=` in `~/.mackup.cfg` names the `mackup/` subfolder) |
| `SSR_ALLOW_CONF_OVERWRITE` | _(unset)_ | `yes` to apply a changed `~/.mackup.cfg` without a TTY (after reviewing logged diff); needed for launchd when cloud path changes | | `SSR_ALLOW_CONF_OVERWRITE` | _(unset)_ | `yes` to apply a changed `~/.mackup.cfg` without a TTY (after reviewing logged diff); needed for launchd when cloud path changes |
| `SSR_BREW_UPGRADE` | `true` | Run `brew upgrade` during sync | | `SSR_BREW_UPGRADE` | `true` | Run `brew upgrade` during sync |
@@ -20,14 +20,14 @@ If `SSR_CLOUD_PROVIDER=` appears more than once with **different** values, inter
| `SSR_APP_DIRS` | `/Applications:~/Applications` | Colon-separated dirs for unmanaged scan | | `SSR_APP_DIRS` | `/Applications:~/Applications` | Colon-separated dirs for unmanaged scan |
| `SSR_SNAPSHOT_MACOS_PREFS` | `true` | Snapshot macOS pref domains during sync | | `SSR_SNAPSHOT_MACOS_PREFS` | `true` | Snapshot macOS pref domains during sync |
| `SSR_MACOS_PREF_DOMAINS` | _(built-in set)_ | Full override of snapshotted domains (space-separated) | | `SSR_MACOS_PREF_DOMAINS` | _(built-in set)_ | Full override of snapshotted domains (space-separated) |
| `SSR_MACOS_PREF_DOMAINS_EXTRA` | — | Extra domains appended to defaults | | `SSR_MACOS_PREF_DOMAINS_EXTRA` | - | Extra domains appended to defaults |
| `SSR_PREFS_CONFLICT_DEFAULT` | `accept` | Non-TTY pref conflict: `accept` or `reject` | | `SSR_PREFS_CONFLICT_DEFAULT` | `accept` | Non-TTY pref conflict: `accept` or `reject` |
| `SSR_ASSUME_YES` | `false` | Auto-accept pref-snapshot conflicts on restore | | `SSR_ASSUME_YES` | `false` | Auto-accept pref-snapshot conflicts on restore |
| `SSR_DISABLE_GATEKEEPER` | `false` | Run `spctl --global-disable` during restore (security trade-off) | | `SSR_DISABLE_GATEKEEPER` | `false` | Run `spctl --global-disable` during restore (security trade-off) |
| `SSR_OPEN_CASKS` | `false` | Open each installed cask after restore | | `SSR_OPEN_CASKS` | `false` | Open each installed cask after restore |
| `SSR_MACOS_DEFAULTS` | repo `config/macos-defaults.sh` | Path to your own defaults script | | `SSR_MACOS_DEFAULTS` | repo `config/macos-defaults.sh` | Path to your own defaults script |
| `SSR_LAUNCHD_LABEL` | `de.surke.ssr.sync` | launchd job label | | `SSR_LAUNCHD_LABEL` | `de.surke.ssr.sync` | launchd job label |
| `SSR_SCHEDULE_HOUR` | `9` | Daily hour (0–23, local) | | `SSR_SCHEDULE_HOUR` | `9` | Daily hour (0-23, local) |
| `SSR_SCHEDULE_MINUTE` | `0` | Daily minute | | `SSR_SCHEDULE_MINUTE` | `0` | Daily minute |
| `SSR_PREFIX` | `$HOME/.local/bin` | Symlink install prefix for `ssr` | | `SSR_PREFIX` | `$HOME/.local/bin` | Symlink install prefix for `ssr` |
| `SSR_STATE_DIR` | `$HOME/.local/state/ssr` | Internal state | | `SSR_STATE_DIR` | `$HOME/.local/state/ssr` | Internal state |
Home.md
+5 -5
@@ -1,8 +1,8 @@
# System Sync & Restore (ssr) — Wiki # System Sync & Restore (ssr) - Wiki
Reproducible macOS setup: snapshot Homebrew + app configs to your cloud drive, restore on a new machine with one workflow. Reproducible macOS setup: snapshot Homebrew + app configs to your cloud drive, restore on a new machine with one workflow.
**Repository:** [System-Sync-Restore](https://git.surke.de/os-mnemo/System-Sync-Restore) · **Issues & PRs:** use the main repo, not this wiki clone. **Repository:** [System-Sync-Restore](https://git.surke.de/os-mnemo/System-Sync-Restore) | **Issues & PRs:** use the main repo, not this wiki clone.
## Documentation map ## Documentation map
@@ -19,9 +19,9 @@ Reproducible macOS setup: snapshot Homebrew + app configs to your cloud drive, r
## At a glance ## At a glance
- **Backup:** `ssr sync` — Brewfile + Mackup copy to cloud (no symlinks by default). - **Backup:** `ssr sync` - Brewfile + Mackup copy to cloud (no symlinks by default).
- **Restore:** `ssr restore` — Homebrew, Brewfile, Mackup, macOS defaults + pref snapshots. - **Restore:** `ssr restore` - Homebrew, Brewfile, Mackup, macOS defaults + pref snapshots.
- **Schedule:** `ssr schedule on` — daily `launchd` agent (configurable hour). - **Schedule:** `ssr schedule on` - daily `launchd` agent (configurable hour).
- **No secrets in git:** state lives on your cloud drive; repo is code + templates only. - **No secrets in git:** state lives on your cloud drive; repo is code + templates only.
Successor to `system_sync.sh` / `system_restore.sh`: same intent, modular and idempotent tooling. Successor to `system_sync.sh` / `system_restore.sh`: same intent, modular and idempotent tooling.
Quick-start.md
+1 -1
@@ -40,4 +40,4 @@ Restore on a **new** machine after clone + `./install.sh`:
ssr restore ssr restore
``` ```
Default Brewfile location: `<cloud>/BACKUP/<hostname> - <hardware-uuid>/Brewfile`. To use another host’s snapshot, pass the Brewfile path — see [Backup-structure-and-sync](https://git.surke.de/os-mnemo/System-Sync-Restore/wiki/Backup-structure-and-sync). Default Brewfile location: `<cloud>/BACKUP/<hostname> - <hardware-uuid>/Brewfile`. To use another host's snapshot, pass the Brewfile path - see [Backup-structure-and-sync](https://git.surke.de/os-mnemo/System-Sync-Restore/wiki/Backup-structure-and-sync).
Repository-layout.md
+28 -28
@@ -2,34 +2,34 @@
```text ```text
. .
├── install.sh # Wrapper → bin/ssr-install |-- install.sh # Wrapper -> bin/ssr-install
├── bin/ |-- bin/
│ ├── ssr # CLI dispatcher | |-- ssr # CLI dispatcher
│ ├── ssr-install | |-- ssr-install
│ ├── ssr-update | |-- ssr-update
│ ├── ssr-sync | |-- ssr-sync
│ ├── ssr-restore | |-- ssr-restore
│ ├── ssr-schedule | |-- ssr-schedule
│ ├── ssr-config | |-- ssr-config
│ ├── ssr-completions | |-- ssr-completions
│ └── ssr-status | +-- ssr-status
├── lib/ |-- lib/
│ ├── common.sh # Logging, validation, config load | |-- common.sh # Logging, validation, config load
│ ├── cloud.sh | |-- cloud.sh
│ ├── brew.sh | |-- brew.sh
│ ├── mackup.sh | |-- mackup.sh
│ ├── apps.sh # Unmanaged .app detection | |-- apps.sh # Unmanaged .app detection
│ ├── macos.sh | |-- macos.sh
│ └── macos-prefs.sh | +-- macos-prefs.sh
├── config/ |-- config/
│ ├── ssr.conf.example | |-- ssr.conf.example
│ └── macos-defaults.sh | +-- macos-defaults.sh
├── completions/ # _ssr, ssr.bash, ssr.fish |-- completions/ # _ssr, ssr.bash, ssr.fish
├── launchd/ |-- launchd/
│ └── de.surke.ssr.sync.plist | +-- de.surke.ssr.sync.plist
├── VERSION |-- VERSION
├── LICENSE |-- LICENSE
└── README.md +-- README.md
``` ```
Runtime needs: macOS and `curl` (Homebrew bootstrap). Logic lives in the repo; state on disk and cloud per your config. Runtime needs: macOS and `curl` (Homebrew bootstrap). Logic lives in the repo; state on disk and cloud per your config.
Scheduling-logging-and-updates.md
+1 -1
@@ -41,7 +41,7 @@ ssr update --dry-run # show what would change
### 2. Backup data (cloud) ### 2. Backup data (cloud)
Refreshed by scheduled `ssr sync`. Previous Brewfile kept as `Brewfile.bak`; deeper history = your cloud provider’s versioning. Refreshed by scheduled `ssr sync`. Previous Brewfile kept as `Brewfile.bak`; deeper history = your cloud provider's versioning.
### 3. Homebrew / Mackup ### 3. Homebrew / Mackup
Security-Uninstall-and-Migration.md
+1 -1
@@ -6,7 +6,7 @@
- Config is **validated** on load: only `#` comments and `KEY=VALUE`; foreign lines abort execution. - Config is **validated** on load: only `#` comments and `KEY=VALUE`; foreign lines abort execution.
- `chmod 600` on `ssr.conf` and the rendered launchd plist. - `chmod 600` on `ssr.conf` and the rendered launchd plist.
- `SSR_DISABLE_GATEKEEPER=true` is opt-in; default is off. - `SSR_DISABLE_GATEKEEPER=true` is opt-in; default is off.
- No `curl … | bash` except Homebrew’s own bootstrap during install. - No `curl ... | bash` except Homebrew's own bootstrap during install.
## Uninstall ## Uninstall