David Heinemeier HanssonandClaude Opus 5
c7e327b05a
omarchy-migrate-notify.service is a Type=oneshot wanted by graphical-session.target, and systemd complements a target's Wants= with an implicit After=, so the target waited for the notifier to exit. The notifier does not exit quickly: it sends the notification through systemd-run --scope, which is synchronous, and omarchy-notification-send -a blocks until the user clicks. The target stayed in activating for as long as the toast was up. wayland-wm-app-daemon.service is After=graphical-session.target and nothing wants it, so uwsm-app starts it on demand. Clicking the notification runs omarchy-launch-floating-terminal-with-presentation, which execs uwsm-app, which blocks on a systemctl --user restart of that daemon -- a job queued behind the very target the clicked notifier was holding open. The terminal never opened; uwsm-app gave up on its own pipe timeout instead. Declaring After= on the wanted unit suppresses the implicit dependency rather than forming a cycle, so the target is reached without waiting and the notifier runs behind it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
158 lines
4.0 KiB
Markdown
158 lines
4.0 KiB
Markdown
# Omarchy migrations
|
|
|
|
Omarchy migrations are one-time repair scripts for existing installs. They are
|
|
used when a package update needs to change state that pacman cannot safely own by
|
|
itself.
|
|
|
|
## Migration model
|
|
|
|
Migrations live in:
|
|
|
|
```text
|
|
migrations/*.sh
|
|
```
|
|
|
|
They run as the current Omarchy user through `omarchy-migrate`, normally during
|
|
`omarchy update`. A migration may touch user/session state (`~/.config`,
|
|
`~/.local`, user systemd, browser/editor prefs, DBus/session state), and may also
|
|
perform machine-wide repairs when needed.
|
|
|
|
Completion state is per-user:
|
|
|
|
```text
|
|
~/.local/state/omarchy/migrations/<migration filename>
|
|
```
|
|
|
|
That means every user gets a chance to run every migration. Migrations run as the
|
|
user; privileged operations should invoke the appropriate helper or privilege
|
|
prompt themselves. Migrations must be idempotent: if one user already applied a
|
|
machine-wide repair, the same migration running for another user should detect
|
|
that and no-op.
|
|
|
|
## When migrations run
|
|
|
|
### During `omarchy update`
|
|
|
|
`omarchy update` is the normal update path. It runs package updates, then:
|
|
|
|
```bash
|
|
omarchy-migrate
|
|
omarchy-hook post-update
|
|
```
|
|
|
|
`omarchy-migrate` waits for any active pacman transaction to finish, then runs
|
|
all pending migrations for the current user in the visible update terminal.
|
|
|
|
### At login
|
|
|
|
Every graphical login starts `omarchy-migrate-notify.service` after
|
|
`graphical-session.target`. The notifier checks:
|
|
|
|
```bash
|
|
omarchy-migrate --pending
|
|
```
|
|
|
|
If that user has pending migrations, it shows a notification that opens a
|
|
terminal for:
|
|
|
|
```bash
|
|
omarchy-migrate
|
|
```
|
|
|
|
The notifier never runs migrations silently in the background.
|
|
|
|
This is what covers users who did not run the update themselves: someone who
|
|
bypassed the pacman guard with `sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman
|
|
-Syu`, and any second user on the machine, whose migration markers are per-user
|
|
and therefore still missing after another user updated.
|
|
|
|
Login is the only trigger on purpose. Watching the packaged migration directory
|
|
also fires during a normal `omarchy update`, which prompts for migrations that
|
|
`omarchy-migrate` is about to run in the visible update terminal.
|
|
|
|
### Manually
|
|
|
|
Users can safely run:
|
|
|
|
```bash
|
|
omarchy-migrate
|
|
```
|
|
|
|
at any time. Already-completed migrations are skipped.
|
|
|
|
## Inspecting pending migrations
|
|
|
|
Use:
|
|
|
|
```bash
|
|
omarchy-migrate --pending
|
|
```
|
|
|
|
Exit behavior:
|
|
|
|
- `0` — one or more migrations are pending
|
|
- non-zero — no migrations are pending
|
|
|
|
Output is one pending migration per line:
|
|
|
|
```text
|
|
1781158082.sh
|
|
```
|
|
|
|
## Creating a migration
|
|
|
|
Use the helper:
|
|
|
|
```bash
|
|
omarchy-dev-add-migration --no-edit
|
|
```
|
|
|
|
This creates:
|
|
|
|
```text
|
|
migrations/<unix timestamp>.sh
|
|
```
|
|
|
|
New migration format:
|
|
|
|
- File permissions must be `0644` (`-rw-r--r--`). Migration runners execute them
|
|
with `bash -euo pipefail`, not through executable bits.
|
|
- No shebang line.
|
|
- Start with an `echo` describing what the migration does.
|
|
- Use `$OMARCHY_PATH` to reference the Omarchy directory.
|
|
- Be idempotent. Check existing state before changing it.
|
|
- Use helper commands such as `omarchy-cmd-present`, `omarchy-cmd-missing`,
|
|
`omarchy-pkg-add`, `omarchy-pkg-drop`, `omarchy-pkg-present`, and
|
|
`omarchy-pkg-missing` when appropriate.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
echo "Relink Neovim theme to Omarchy current state"
|
|
|
|
theme_link="$HOME/.config/nvim/lua/plugins/theme.lua"
|
|
current_relative_target="../../../../.local/state/omarchy/current/theme/neovim.lua"
|
|
|
|
[[ -L $theme_link ]] || exit 0
|
|
ln -sfn "$current_relative_target" "$theme_link"
|
|
```
|
|
|
|
## Testing migrations
|
|
|
|
Run a migration against a temporary home when possible:
|
|
|
|
```bash
|
|
HOME=$(mktemp -d) bash -euo pipefail migrations/<timestamp>.sh
|
|
```
|
|
|
|
To rerun a migration locally, remove its marker and run the migrator:
|
|
|
|
```bash
|
|
rm ~/.local/state/omarchy/migrations/<migration>.sh
|
|
omarchy-migrate
|
|
```
|
|
|
|
Omarchy 4.0 is upgraded through `bin/omarchy-upgrade-to-quattro`, not through the
|
|
normal migration runner. Do not add compatibility migrations for old installer
|
|
layouts; put pre-4 package-layout transition work in the upgrade command instead.
|