Plan the dots feature for preserving and syncing user configs
A whitelisted bare git repo over $HOME driven only by constrained omarchy dots commands: local snapshot history at batch boundaries plus squash-published state sync across machines. Design survived adversarial review; rejected alternatives and rationale recorded in the plan. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
David Heinemeier Hansson
co-authored by
Claude Fable 5
Claude Fable 5
parent
f4189398bc
commit
022f6993ba
+206
@@ -0,0 +1,206 @@
|
|||||||
|
# Plan: Dots — preserve and sync user configs out of the box
|
||||||
|
|
||||||
|
Revision 3. Rev 2 incorporated adversarial review by codex (xhigh) and grok;
|
||||||
|
rev 3 names the feature **dots** (`omarchy dots ...`) and adds the
|
||||||
|
multi-machine sync design.
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
Omarchy declares `~/.config` "your files" but does little to preserve them:
|
||||||
|
|
||||||
|
- `omarchy-refresh-config` litters `*.bak.<timestamp>` files next to originals.
|
||||||
|
- `omarchy-reinstall-configs` clobbers everything back to `/etc/skel` defaults.
|
||||||
|
- Snapper only snapshots the `root` config; recovering one config file from a
|
||||||
|
root snapshot is not a workflow, and `/home` may not be covered at all.
|
||||||
|
- The manual punts to a YouTube video about Stow.
|
||||||
|
|
||||||
|
There is no way to answer "what did the last update change about my configs?",
|
||||||
|
"restore my bindings from last week," or "make my new laptop feel like my
|
||||||
|
desktop."
|
||||||
|
|
||||||
|
## Rejected approaches
|
||||||
|
|
||||||
|
- **`git init ~/.config`**: dumping ground — Chromium profile, fcitx5 state,
|
||||||
|
app tokens, machine churn. A `.git` there gets discovered by editors and
|
||||||
|
prompts. Can't cover `~/.bashrc` or `~/.XCompose`.
|
||||||
|
- **`~/.config/omarchy` only**: too narrow; misses hypr, terminals, `.bashrc`.
|
||||||
|
- **Stow**: inverted model requiring file migration; organization, not history.
|
||||||
|
- **chezmoi / yadm**: third-party DSLs we'd be wrapping; overkill.
|
||||||
|
- **Raw git passthrough / lazygit over `$HOME`** (rejected in review):
|
||||||
|
`git clean -fd`, `reset --hard`, or "stage all" against a `$HOME` work tree
|
||||||
|
is a home-directory-eraser; `git add -A` can ingest `~/.ssh` and the object
|
||||||
|
store into itself (`status.showUntrackedFiles no` only affects `status`);
|
||||||
|
`remote add` + `push` silently defeats local-only. Experts can construct the
|
||||||
|
raw invocation themselves; Omarchy will not bless it.
|
||||||
|
- **Distributed git across machines**: two machines auto-committing timer and
|
||||||
|
update snapshots into a shared branch conflict constantly. History and sync
|
||||||
|
are different products (see Sync below).
|
||||||
|
|
||||||
|
## Chosen design: bare repo over `$HOME`, driven only by constrained commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git init --bare ~/.local/share/omarchy/dots.git # mode 0700
|
||||||
|
```
|
||||||
|
|
||||||
|
No `.git` in any directory tools walk; files stay plain files in place. All
|
||||||
|
access goes through one internal helper that runs git **hermetically**:
|
||||||
|
|
||||||
|
- Repo-local config only: synthetic identity (`Omarchy <omarchy@localhost>`),
|
||||||
|
`commit.gpgsign=false`, `core.hooksPath` disabled, `--no-verify`,
|
||||||
|
`GIT_CONFIG_GLOBAL=/dev/null` so user signing/hooks/templates/excludes and a
|
||||||
|
`$HOME/.gitignore` can never break or intercept an automatic commit.
|
||||||
|
- Never export `GIT_DIR`/`GIT_WORK_TREE` (would leak into `omarchy-plugin-*`,
|
||||||
|
`omarchy-theme-update`, `omarchy-update-dev`, user hooks).
|
||||||
|
- Serialized via a lock; concurrent refresh/update/manual snapshots queue.
|
||||||
|
- **Best-effort everywhere**: a failed snapshot warns and continues. History
|
||||||
|
is optional; updates are not. Never on the failure path of
|
||||||
|
`omarchy-update`/`omarchy-migrate` (`set -e` there must not see git errors).
|
||||||
|
|
||||||
|
### Audited manifest, not a derived whitelist
|
||||||
|
|
||||||
|
Tracking is `git add -f --pathspec-from-file=<manifest>` only. The manifest is
|
||||||
|
a hand-audited file shipped with Omarchy — explicitly **not** derived from
|
||||||
|
`$OMARCHY_PATH/config` (which ships Chromium Preferences, fcitx5,
|
||||||
|
`opencode/opencode.json` where users put API keys, etc.):
|
||||||
|
|
||||||
|
- Include: `.config/hypr/*.{lua,conf}`, `.config/omarchy/shell.json`,
|
||||||
|
`.config/omarchy/extensions/**`, `.config/omarchy/hooks/**`,
|
||||||
|
terminal configs (alacritty/foot/ghostty/kitty), `.config/btop/btop.conf`,
|
||||||
|
`.config/starship.toml`, `.bashrc`, `.XCompose`.
|
||||||
|
- Exclude (deliberately): `.config/omarchy/plugins/**` and
|
||||||
|
`.config/omarchy/themes/**` (nested git clones managed by
|
||||||
|
`omarchy-plugin-*` / `omarchy-theme-update`), backgrounds (multi-MB
|
||||||
|
binaries), `.config/btop/themes/` (symlink into `~/.local/state`), anything
|
||||||
|
Chromium/fcitx5/opencode/xournalpp.
|
||||||
|
- **Two tiers**: every manifest path is history-tracked, but some are marked
|
||||||
|
`local` — machine-specific files that sync must never touch. At minimum
|
||||||
|
`monitors.lua`; likely hardware quirks like `dell-haptic.conf`. This is the
|
||||||
|
lightweight answer to chezmoi's hostname templates: exclude, no DSL.
|
||||||
|
- Once committed, a secret lives in the object store forever; "no remote" is
|
||||||
|
not a secrets story. The manifest is the deny line — nothing outside it is
|
||||||
|
ever staged, and there is no command that stages more.
|
||||||
|
|
||||||
|
### Dotfile-manager detection: stand down, don't fight
|
||||||
|
|
||||||
|
`manual/31-dotfiles.md` sends users to Stow today, and migrations deliberately
|
||||||
|
write *through* symlinks. For those users git records an unchanged symlink, so
|
||||||
|
snapshots would be silent no-ops — and `restore` could stomp a symlink with a
|
||||||
|
regular file. Therefore:
|
||||||
|
|
||||||
|
- At seed time and before each snapshot: if manifest paths are symlinks or a
|
||||||
|
known manager (yadm, chezmoi, existing bare-repo alias, `~/.git`) is
|
||||||
|
detected, mark the repo dormant and say so in `omarchy dots status`.
|
||||||
|
- `restore` refuses type changes (symlink↔file) and paths outside the
|
||||||
|
manifest.
|
||||||
|
- These users keep `.bak` behavior, which genuinely works for them (copies
|
||||||
|
content, not links).
|
||||||
|
|
||||||
|
### Snapshot points: batch boundaries, before *and* after
|
||||||
|
|
||||||
|
The unit is a labeled snapshot pair around each *batch* mutation, via an
|
||||||
|
internal `omarchy-dots-snapshot "<label>"`:
|
||||||
|
|
||||||
|
1. **`omarchy-provision-user`**: seed repo + initial commit, after `git.sh`
|
||||||
|
and `.XCompose` are in place. Idempotent; `--force` must not re-init.
|
||||||
|
2. **`omarchy-migrate`**: before/after pair labeled with version. Covers both
|
||||||
|
`omarchy-update` *and* the login-time migration path, and separates
|
||||||
|
migration changes from prior user dirt — the "before" commit captures user
|
||||||
|
edits, the "after" commit is purely what migrations did.
|
||||||
|
3. **Batch refresh commands** (`omarchy-refresh-hyprland` etc.): one pair per
|
||||||
|
command, not one commit per `omarchy-refresh-config` call (hyprland calls
|
||||||
|
it seven times).
|
||||||
|
4. **`omarchy-reinstall-configs`**: a "before" snapshot — honestly labeled.
|
||||||
|
This operation replays all of `/etc/skel`; a manifest repo does **not**
|
||||||
|
make it reversible and we don't claim it does.
|
||||||
|
5. **Timer**: an hourly-ish systemd user timer committing only if dirty, so
|
||||||
|
hand edits are captured — without it, "restore my bindings from last week"
|
||||||
|
fails for any edit not followed by an Omarchy operation.
|
||||||
|
|
||||||
|
`.bak` files **stay** in v1. They serve symlink users, they're documented
|
||||||
|
(manual, agent skill, `refresh-config-test.sh` asserts them), and git history
|
||||||
|
is invisible until the menu surface exists. Removal is a later, separate
|
||||||
|
decision once restore is on *Update > Config* and proven.
|
||||||
|
|
||||||
|
## Sync across machines: publish/pull of state, not history
|
||||||
|
|
||||||
|
The local snapshot history is machine-generated noise (timer commits,
|
||||||
|
before/after pairs) and stays private. Sync happens on a shared `sync` branch
|
||||||
|
in the same repo that only two operations touch:
|
||||||
|
|
||||||
|
- **`omarchy dots push`** — *squash-publishes* the current manifest state
|
||||||
|
(minus `local`-tier files) as one commit: "Published from <hostname>". Only
|
||||||
|
present-state files leave the machine — a token the timer captured last
|
||||||
|
month and you since deleted is not in any published commit.
|
||||||
|
- **`omarchy dots pull [url]`** — fetches `sync`, takes a local pre-pull
|
||||||
|
snapshot (so pull is undoable via `restore`), then applies the files.
|
||||||
|
Never touches `local`-tier files. With a URL argument on a fresh machine,
|
||||||
|
it configures the remote first — the second-machine straight shot is one
|
||||||
|
command.
|
||||||
|
|
||||||
|
Conflict story stays simple because publishes are whole-state: push refuses
|
||||||
|
when the remote moved since your last pull ("pull first"); pull attempts a
|
||||||
|
per-file three-way merge and falls back to taking remote — your version is
|
||||||
|
one `omarchy dots restore` away.
|
||||||
|
|
||||||
|
Remote setup UX:
|
||||||
|
|
||||||
|
- `omarchy dots push` with no remote runs setup inline: paste a git URL, or
|
||||||
|
create a **private** GitHub repo via `gh` when authenticated. Verify the
|
||||||
|
repo is private; warn loudly if not.
|
||||||
|
- Manual by default. Push is an intentional "my setup is good" moment — no
|
||||||
|
auto-push ever (publishing half-finished experiments is an anti-feature).
|
||||||
|
Opt-in *pull on login* later for people with one canonical machine; safe
|
||||||
|
because every pull is snapshot-guarded.
|
||||||
|
- Dormant mode (dotfile-manager users) disables sync too — they have their
|
||||||
|
own.
|
||||||
|
- v2 candidate: `omarchy-provision-first-run` asks "Got a dots repo?" so a
|
||||||
|
new machine is yours before first login completes. Held back from v1 —
|
||||||
|
drags SSH/auth bootstrapping into first-run.
|
||||||
|
|
||||||
|
## User-facing surface (v1)
|
||||||
|
|
||||||
|
Constrained commands only — a new `dots` group in `GROUP_DESCRIPTIONS`,
|
||||||
|
invoked as `omarchy dots <verb>`:
|
||||||
|
|
||||||
|
- `omarchy dots snapshot [label]` — take a snapshot now
|
||||||
|
- `omarchy dots log` — history with labels
|
||||||
|
- `omarchy dots diff [ref]` — default range: the last before/after pair
|
||||||
|
- `omarchy dots restore <file> [--at <ref>]` — accepts `~/.config/...`,
|
||||||
|
`.config/...`, or manifest-relative paths; takes a pre-restore snapshot
|
||||||
|
first so restore is itself undoable; refuses untracked paths and type
|
||||||
|
changes; confirms over dirty files
|
||||||
|
- `omarchy dots push` / `omarchy dots pull [url]` — sync (above)
|
||||||
|
- `omarchy dots status` — repo state, dormant/active, remote, last
|
||||||
|
snapshot/publish
|
||||||
|
|
||||||
|
No raw git surface. No lazygit integration.
|
||||||
|
|
||||||
|
## Rollout
|
||||||
|
|
||||||
|
- New users: seeded by `omarchy-provision-user`.
|
||||||
|
- Existing users: migration inits the repo + initial commit — **skippable and
|
||||||
|
bounded**: no-op if repo path exists, another manager is detected, or
|
||||||
|
identity can't be synthesized; never adds beyond the manifest; never fails
|
||||||
|
`omarchy update`.
|
||||||
|
- Docs/tests alignment: manual `31-dotfiles.md` gets the built-in story
|
||||||
|
(honest framing: local event history + sync of published states, *not* a
|
||||||
|
backup — the local repo dies with the disk); a `docs/dots.md` reference doc
|
||||||
|
per the documentation layout; `default/agents/skills/omarchy/SKILL.md`
|
||||||
|
updated; CLI routing/metadata tests extended; new tests for identity-less
|
||||||
|
commit, batch snapshot pairing, restore round-trip, dormant-mode detection,
|
||||||
|
push/pull round-trip against a local bare remote, `local`-tier exclusion,
|
||||||
|
and "git failure must not fail update".
|
||||||
|
|
||||||
|
## Open questions
|
||||||
|
|
||||||
|
1. Manifest location: `default/omarchy/dots-manifest` vs alongside the
|
||||||
|
helper; and whether users may extend it via
|
||||||
|
`~/.config/omarchy/dots-manifest.d/`.
|
||||||
|
2. Whether `.config/omarchy/hooks/**` belongs in the manifest at all (small
|
||||||
|
scripts, but the likeliest place for a pasted token).
|
||||||
|
3. Harden `omarchy-refresh-config` against `..` path escape (documented today
|
||||||
|
in AGENTS.md) as part of this work or separately.
|
||||||
|
4. Timer cadence (hourly vs daily) and whether the dirty-check should debounce
|
||||||
|
against an active editing session.
|
||||||
|
5. Whether `input.lua` is `local`-tier (keyboard layouts travel, trackpad
|
||||||
|
quirks don't).
|
||||||
Reference in New Issue
Block a user