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

2026-05-18 10:24:39 +02:00
parent 0af70f3e54
commit fd9e198335
8 changed files with 60 additions and 60 deletions
@@ -6,36 +6,36 @@ After `ssr sync`, the default layout under your cloud root is:

 ```text
 <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
-│           └── …
+|-- 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.
+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
+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`
+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

@@ -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.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.spaces` | Spaces / Mission Control |
 | `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`).
 - `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
 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).)
@@ -2,7 +2,7 @@

 ```text
 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 update [--dry-run]    Pull latest ssr code, refresh launchd if needed
 ssr schedule on|off       Enable/disable daily launchd job
@@ -11,7 +11,7 @@ If `SSR_CLOUD_PROVIDER=` appears more than once with **different** values, inter
 | Key | Default | Purpose |
 |-----|---------|---------|
 | `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_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 |
@@ -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_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_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_ASSUME_YES` | `false` | Auto-accept pref-snapshot conflicts on restore |
 | `SSR_DISABLE_GATEKEEPER` | `false` | Run `spctl --global-disable` during restore (security trade-off) |
 | `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_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_PREFIX` | `$HOME/.local/bin` | Symlink install prefix for `ssr` |
 | `SSR_STATE_DIR` | `$HOME/.local/state/ssr` | Internal state |
@@ -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.

-**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

@@ -19,9 +19,9 @@ Reproducible macOS setup: snapshot Homebrew + app configs to your cloud drive, r

 ## At a glance

- **Backup:** `ssr sync` — Brewfile + Mackup copy to cloud (no symlinks by default).
- **Restore:** `ssr restore` — Homebrew, Brewfile, Mackup, macOS defaults + pref snapshots.
- **Schedule:** `ssr schedule on` — daily `launchd` agent (configurable hour).
+- **Backup:** `ssr sync` - Brewfile + Mackup copy to cloud (no symlinks by default).
+- **Restore:** `ssr restore` - Homebrew, Brewfile, Mackup, macOS defaults + pref snapshots.
+- **Schedule:** `ssr schedule on` - daily `launchd` agent (configurable hour).
 - **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.
@@ -40,4 +40,4 @@ Restore on a **new** machine after clone + `./install.sh`:
 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).
@@ -2,34 +2,34 @@

 ```text
 .
-├── install.sh              # Wrapper → bin/ssr-install
-├── bin/
-│   ├── ssr                 # CLI dispatcher
-│   ├── ssr-install
-│   ├── ssr-update
-│   ├── ssr-sync
-│   ├── ssr-restore
-│   ├── ssr-schedule
-│   ├── ssr-config
-│   ├── ssr-completions
-│   └── ssr-status
-├── lib/
-│   ├── common.sh           # Logging, validation, config load
-│   ├── cloud.sh
-│   ├── brew.sh
-│   ├── mackup.sh
-│   ├── apps.sh             # Unmanaged .app detection
-│   ├── macos.sh
-│   └── macos-prefs.sh
-├── config/
-│   ├── ssr.conf.example
-│   └── macos-defaults.sh
-├── completions/            # _ssr, ssr.bash, ssr.fish
-├── launchd/
-│   └── de.surke.ssr.sync.plist
-├── VERSION
-├── LICENSE
-└── README.md
+|-- install.sh              # Wrapper -> bin/ssr-install
+|-- bin/
+|   |-- ssr                 # CLI dispatcher
+|   |-- ssr-install
+|   |-- ssr-update
+|   |-- ssr-sync
+|   |-- ssr-restore
+|   |-- ssr-schedule
+|   |-- ssr-config
+|   |-- ssr-completions
+|   +-- ssr-status
+|-- lib/
+|   |-- common.sh           # Logging, validation, config load
+|   |-- cloud.sh
+|   |-- brew.sh
+|   |-- mackup.sh
+|   |-- apps.sh             # Unmanaged .app detection
+|   |-- macos.sh
+|   +-- macos-prefs.sh
+|-- config/
+|   |-- ssr.conf.example
+|   +-- macos-defaults.sh
+|-- completions/            # _ssr, ssr.bash, ssr.fish
+|-- launchd/
+|   +-- de.surke.ssr.sync.plist
+|-- VERSION
+|-- LICENSE
+-- README.md
 ```

 Runtime needs: macOS and `curl` (Homebrew bootstrap). Logic lives in the repo; state on disk and cloud per your config.
@@ -41,7 +41,7 @@ ssr update --dry-run  # show what would change

 ### 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

@@ -6,7 +6,7 @@
 - Config is **validated** on load: only `#` comments and `KEY=VALUE`; foreign lines abort execution.
 - `chmod 600` on `ssr.conf` and the rendered launchd plist.
 - `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