Improve update and migration flow
This commit is contained in:
Ryan Hughes
+50
-8
@@ -54,12 +54,16 @@ bin/omarchy-debug,
|
||||
bin/omarchy-debug-idle,
|
||||
bin/omarchy-upload-log ──► omarchy-settings /usr/bin/ (needed before omarchy is installed)
|
||||
|
||||
default/libalpm/hooks/00-omarchy-update-guard.hook
|
||||
──► omarchy /usr/share/libalpm/hooks/00-omarchy-update-guard.hook
|
||||
|
||||
install/** ──► omarchy /usr/share/omarchy/install/
|
||||
migrations/** ──► omarchy /usr/share/omarchy/migrations/
|
||||
migrations/system/** ──► omarchy /usr/share/omarchy/migrations/system/
|
||||
migrations/user/** ──► omarchy /usr/share/omarchy/migrations/user/
|
||||
themes/** ──► omarchy /usr/share/omarchy/themes/
|
||||
shell/** ──► omarchy /usr/share/omarchy/shell/
|
||||
version ──► omarchy /usr/share/omarchy/version
|
||||
+ /etc/skel/.local/state/omarchy/migrations/*
|
||||
+ /etc/skel/.local/state/omarchy/migrations/user/*
|
||||
|
||||
config/** ──► omarchy-settings /etc/skel/.config/** (seeds new users)
|
||||
/usr/share/omarchy/config/** (resync source)
|
||||
@@ -95,7 +99,7 @@ default/** ──► omarchy-settings /usr/share/omarchy
|
||||
│ + symlink /etc/fonts/conf.d/30-omarchy.conf
|
||||
├─ xdg-terminal-exec/*.list /usr/share/xdg-terminal-exec/
|
||||
├─ applications/mimeapps.list /usr/share/applications/mimeapps.list
|
||||
├─ systemd/user/*.service /usr/lib/systemd/user/
|
||||
├─ systemd/user/*.{service,path} /usr/lib/systemd/user/
|
||||
├─ systemd/system-sleep/unmount-fuse /usr/lib/systemd/system-sleep/
|
||||
├─ fonts/omarchy/omarchy.ttf /usr/share/fonts/omarchy/
|
||||
├─ sddm/omarchy/ /usr/share/sddm/themes/omarchy/
|
||||
@@ -164,7 +168,7 @@ It only does the things `/etc/skel` can't:
|
||||
- `omarchy-refresh-applications` (composes generated `.desktop` launchers).
|
||||
- Sources `install/user/all.sh` — theme, git, mise, keyring, per-user
|
||||
hardware quirks (asus mic/mixer, framework f13 audio, …).
|
||||
- On `--first-install`, marks every shipped migration as already applied
|
||||
- On `--first-install`, marks every shipped user migration as already applied
|
||||
for the freshly-created user.
|
||||
|
||||
Idempotency marker: `~/.local/state/omarchy/finalize-user.done`.
|
||||
@@ -173,6 +177,43 @@ The ISO calls it as `omarchy-finalize-user --force --first-install` in the
|
||||
target chroot as the install user, after `omarchy-setup-system` has finished
|
||||
the root-side work.
|
||||
|
||||
## Migrations (`omarchy-migrate`)
|
||||
|
||||
See [`migrations.md`](migrations.md) for the full migration model, authoring
|
||||
guidelines, and troubleshooting notes.
|
||||
|
||||
Omarchy migrations are split by scope:
|
||||
|
||||
- `migrations/system/*.sh` — root, noninteractive, safe to run from pacman.
|
||||
The `omarchy` package `post_upgrade()` runs `omarchy-migrate-system` after an
|
||||
`omarchy` package upgrade, so even explicit direct-pacman bypasses still get
|
||||
system migrations applied. Completion state lives in
|
||||
`/var/lib/omarchy/migrations/system/`.
|
||||
- `migrations/user/*.sh` — current user/session, may be interactive, and may
|
||||
touch `~/.config`, `~/.local`, user systemd, DBus, browser prefs, etc.
|
||||
Completion state lives in `~/.local/state/omarchy/migrations/user/`.
|
||||
|
||||
Package upgrades happen as root, but user migrations must run as each user and
|
||||
may be interactive. There is no root-owned "user migration required" marker. A
|
||||
user migration is pending only when a script exists in `migrations/user/` and
|
||||
that user's matching state file is missing.
|
||||
|
||||
Each graphical user has `omarchy-update-user-notify.path` watching the packaged
|
||||
user migration directory. When that directory changes, or when the path unit is
|
||||
started on login, `omarchy-update-user-notify.service` runs
|
||||
`omarchy-migrate-notify` as that user. The notifier checks
|
||||
`omarchy-migrate --pending user`. If this user has missing migration state, it
|
||||
shows a notification that opens a terminal for `omarchy-migrate`. The notifier
|
||||
never runs user migrations in the background.
|
||||
|
||||
`omarchy-migrate` waits for any active pacman transaction to finish, runs
|
||||
pending system migrations, then runs pending user migrations. It does not need
|
||||
`--force`; migrations happen when state files are missing. For watchers and
|
||||
diagnostics, `omarchy-migrate --pending [all|system|user]` prints
|
||||
scope-prefixed pending migration filenames and exits `0` when any are pending.
|
||||
`omarchy update` runs `omarchy-migrate` after the package transaction in the
|
||||
already-visible update terminal, then runs `omarchy-hook post-update`.
|
||||
|
||||
## First-run (`omarchy-first-run`)
|
||||
|
||||
Runs once on first interactive login, after the user manager is live. Used
|
||||
@@ -183,9 +224,9 @@ systemd instance:
|
||||
Voxtype post-update hook.
|
||||
- `install/user/first-run/enable-user-units.sh` — `systemctl --user enable`
|
||||
the shipped user units (`bt-agent`, `omarchy-sleep-lock`,
|
||||
`omarchy-recover-internal-monitor`). Done here, not at finalize, because
|
||||
`omarchy-recover-internal-monitor`, `omarchy-update-user-notify.path`). Done here, not at finalize, because
|
||||
the user manager isn't reachable from the ISO chroot; `ConditionPath*`
|
||||
in the unit files keeps them inert on hardware they don't apply to.
|
||||
in the unit files keeps services inert when they don't apply.
|
||||
- `install/user/first-run/gnome-theme.sh`,
|
||||
`install/user/first-run/gtk-primary-paste.sh` — GNOME/GTK settings that
|
||||
need the dconf daemon.
|
||||
@@ -236,10 +277,11 @@ without backup.
|
||||
| Default file at `~/.config/foo/` | `config/foo/` |
|
||||
| `/etc/` drop-in we own outright | `etc/` |
|
||||
| `/etc/` file owned by an upstream package | `default/`, then add to `etc-overrides` in `omarchy-settings` PKGBUILD + scriptlet |
|
||||
| Package-owned system file (e.g. systemd user service in `/usr/lib`) | `default/`, document the mapping in `default/package-defaults.tsv`, then add the `install -Dm644` line in `omarchy-settings` PKGBUILD |
|
||||
| Package-owned system file (e.g. systemd user service/path in `/usr/lib`) | `default/`, document the mapping in `default/package-defaults.tsv`, then add the `install -Dm644` line in `omarchy-settings` PKGBUILD |
|
||||
| Per-user file that's static but lives outside `~/.config` | `default/`, then add `install -Dm644 ... $pkgdir/etc/skel/...` in `omarchy-settings` PKGBUILD |
|
||||
| Runtime tweak that needs `$HOME` or live system state | extend `omarchy-finalize-user`, or add a per-user leaf under `install/user/` and wire into `install/user/all.sh` |
|
||||
| One-time root-side setup step | `install/config/*.sh` or `install/hardware/*.sh`, wire into `omarchy-setup-system` or `install/hardware/all.sh` |
|
||||
| Noninteractive root fix for existing installs | `migrations/system/<unix-timestamp>.sh` |
|
||||
| User/session fix for existing installs | `migrations/user/<unix-timestamp>.sh` |
|
||||
| User-facing `omarchy-*` command | `bin/omarchy-<group>-<verb>` — see `GROUP_DESCRIPTIONS` in `bin/omarchy` |
|
||||
| New theme | `themes/<name>/` (+ matching templates under `default/themed/` if they need theme colors) |
|
||||
| One-shot fix for installed systems | `migrations/<unix-timestamp>.sh` (use `omarchy-dev-add-migration --no-edit`) |
|
||||
|
||||
@@ -0,0 +1,307 @@
|
||||
# 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.
|
||||
|
||||
They are for both humans and agents:
|
||||
|
||||
- Users should know when migrations run, where state is stored, and how to retry
|
||||
or inspect pending work.
|
||||
- Agents should know which migration scope to use, how to write safe migration
|
||||
scripts, and what should **not** be a migration.
|
||||
|
||||
## The two migration scopes
|
||||
|
||||
Omarchy migrations are split by execution context:
|
||||
|
||||
```text
|
||||
migrations/system/*.sh
|
||||
migrations/user/*.sh
|
||||
```
|
||||
|
||||
### System migrations
|
||||
|
||||
System migrations run as root and must be noninteractive.
|
||||
|
||||
Use system migrations for machine-wide state, for example:
|
||||
|
||||
- `/etc` drop-ins or legacy config cleanup
|
||||
- `/boot` / bootloader cleanup
|
||||
- systemd system units or service state
|
||||
- hardware quirks
|
||||
- package-owned layout transitions
|
||||
|
||||
State lives in:
|
||||
|
||||
```text
|
||||
/var/lib/omarchy/migrations/system/<migration filename>
|
||||
```
|
||||
|
||||
### User migrations
|
||||
|
||||
User migrations run as the current graphical/login user and may be interactive.
|
||||
|
||||
Use user migrations for per-user or session-aware state, for example:
|
||||
|
||||
- `~/.config` changes
|
||||
- `~/.local` state
|
||||
- user systemd units
|
||||
- browser/editor preferences
|
||||
- DBus/session-dependent updates
|
||||
- prompts that need to happen in a visible terminal
|
||||
|
||||
State lives in:
|
||||
|
||||
```text
|
||||
~/.local/state/omarchy/migrations/user/<migration filename>
|
||||
```
|
||||
|
||||
A user migration is pending for a given user only when the script exists under
|
||||
`/usr/share/omarchy/migrations/user/` and that user's matching state file is
|
||||
missing.
|
||||
|
||||
There is no global root-owned “user migrations required” queue.
|
||||
|
||||
## 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`:
|
||||
|
||||
1. waits for any active pacman transaction to finish
|
||||
2. runs pending system migrations
|
||||
3. runs pending user migrations for the current user
|
||||
|
||||
System migrations usually already ran during the pacman transaction via the
|
||||
`omarchy` package `post_upgrade()`, but the second check is intentional and
|
||||
idempotent.
|
||||
|
||||
### During direct pacman updates
|
||||
|
||||
Raw `sudo pacman -Syu` is guarded. Users should normally run:
|
||||
|
||||
```bash
|
||||
omarchy update
|
||||
```
|
||||
|
||||
If a user explicitly bypasses the guard, the `omarchy` package still runs system
|
||||
migrations from `post_upgrade()`:
|
||||
|
||||
```bash
|
||||
omarchy-migrate-system
|
||||
```
|
||||
|
||||
User migrations are never run by pacman. Instead, the user session watches the
|
||||
packaged user migration directory and runs a notifier. The notifier checks:
|
||||
|
||||
```bash
|
||||
omarchy-migrate --pending user
|
||||
```
|
||||
|
||||
If that user has pending user migrations, it shows a notification that opens a
|
||||
terminal for:
|
||||
|
||||
```bash
|
||||
omarchy-migrate
|
||||
```
|
||||
|
||||
The notifier never runs user migrations silently in the background.
|
||||
|
||||
### Manually
|
||||
|
||||
Users can safely run:
|
||||
|
||||
```bash
|
||||
omarchy-migrate
|
||||
```
|
||||
|
||||
at any time. Already-completed migrations are skipped.
|
||||
|
||||
## Inspecting pending migrations
|
||||
|
||||
Use:
|
||||
|
||||
```bash
|
||||
omarchy-migrate --pending
|
||||
omarchy-migrate --pending system
|
||||
omarchy-migrate --pending user
|
||||
```
|
||||
|
||||
Exit behavior:
|
||||
|
||||
- `0` — one or more matching migrations are pending
|
||||
- non-zero — no matching migrations are pending
|
||||
|
||||
Output is scope-prefixed:
|
||||
|
||||
```text
|
||||
system/100-system.sh
|
||||
user/200-user.sh
|
||||
```
|
||||
|
||||
The lower-level runners also support `--pending` and print filenames without the
|
||||
scope prefix:
|
||||
|
||||
```bash
|
||||
omarchy-migrate-system --pending
|
||||
omarchy-migrate-user --pending
|
||||
```
|
||||
|
||||
Prefer `omarchy-migrate --pending ...` in user-facing tools and watchers.
|
||||
|
||||
## Writing migrations
|
||||
|
||||
Create a migration with:
|
||||
|
||||
```bash
|
||||
omarchy-dev-add-migration system --no-edit
|
||||
omarchy-dev-add-migration user --no-edit
|
||||
```
|
||||
|
||||
Choose the scope based on the state being changed, not on convenience.
|
||||
|
||||
### File format
|
||||
|
||||
Migrations are plain shell files:
|
||||
|
||||
- filename: unix timestamp, generated by `omarchy-dev-add-migration`
|
||||
- mode: `0644`
|
||||
- no shebang
|
||||
- start with an `echo` describing the migration
|
||||
- use `$OMARCHY_PATH` for Omarchy-owned files
|
||||
|
||||
Example system migration:
|
||||
|
||||
```bash
|
||||
echo "Remove legacy Limine config"
|
||||
|
||||
rm -f /boot/EFI/limine/limine.conf
|
||||
```
|
||||
|
||||
Example user migration:
|
||||
|
||||
```bash
|
||||
echo "Refresh user app launchers"
|
||||
|
||||
omarchy-refresh-applications
|
||||
```
|
||||
|
||||
### Execution model
|
||||
|
||||
Migration runners execute scripts with strict shell settings:
|
||||
|
||||
```bash
|
||||
bash -euo pipefail <migration>
|
||||
```
|
||||
|
||||
`$OMARCHY_PATH` is exported into the migration process.
|
||||
|
||||
A migration is marked complete only after the script exits successfully. If it
|
||||
fails, the marker is not written and the migration will be retried later.
|
||||
|
||||
Because failed migrations can be retried after doing partial work, migrations
|
||||
must be idempotent. Prefer operations that are safe to run more than once:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/example
|
||||
rm -f ~/.config/example/legacy.conf
|
||||
install -Dm644 "$OMARCHY_PATH/default/example.conf" ~/.config/example/example.conf
|
||||
systemctl --user enable --now some-unit.service || true
|
||||
```
|
||||
|
||||
Use `|| true` only when a failure is genuinely acceptable.
|
||||
|
||||
## What belongs in a migration?
|
||||
|
||||
Good migration uses:
|
||||
|
||||
- deleting or moving legacy files that block the packaged layout
|
||||
- marking or enabling new service state
|
||||
- migrating old config paths to new config paths
|
||||
- repairing known bad state from an earlier Omarchy release
|
||||
- one-time compatibility for existing installs
|
||||
|
||||
Bad migration uses:
|
||||
|
||||
- fresh-install setup that belongs in `install/` or `/etc/skel`
|
||||
- package installation that belongs in package dependencies or package lists
|
||||
- recurring maintenance
|
||||
- arbitrary cleanup that should be a user command
|
||||
- pre-4 upgrade work that belongs in `omarchy-upgrade-to-4`
|
||||
- hidden user/session work from pacman
|
||||
|
||||
## Fresh installs and new users
|
||||
|
||||
Fresh users created from the packaged layout should not have to run historical
|
||||
user migrations. The package seeds user migration markers into `/etc/skel` so
|
||||
new users start with shipped user migrations marked complete.
|
||||
|
||||
The ISO/finalization path also marks shipped user migrations complete for the
|
||||
freshly-created install user when running:
|
||||
|
||||
```bash
|
||||
omarchy-finalize-user --first-install
|
||||
```
|
||||
|
||||
Existing users keep their own migration state and run only migrations whose
|
||||
state files are missing.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### See what is pending
|
||||
|
||||
```bash
|
||||
omarchy-migrate --pending
|
||||
```
|
||||
|
||||
### Retry failed migrations
|
||||
|
||||
Fix the underlying problem, then run:
|
||||
|
||||
```bash
|
||||
omarchy-migrate
|
||||
```
|
||||
|
||||
A failed migration is not marked complete, so it will retry.
|
||||
|
||||
### Re-run a completed migration manually
|
||||
|
||||
Remove its marker, then run the migration command again:
|
||||
|
||||
```bash
|
||||
rm ~/.local/state/omarchy/migrations/user/<migration>.sh
|
||||
omarchy-migrate
|
||||
```
|
||||
|
||||
For system migrations:
|
||||
|
||||
```bash
|
||||
sudo rm /var/lib/omarchy/migrations/system/<migration>.sh
|
||||
omarchy-migrate
|
||||
```
|
||||
|
||||
Be careful: migrations should be idempotent, but manually removing markers is an
|
||||
advanced troubleshooting step.
|
||||
|
||||
## Agent checklist
|
||||
|
||||
Before adding a migration:
|
||||
|
||||
1. Is this a one-time repair for existing installs?
|
||||
2. Is it system state or user/session state?
|
||||
3. Can it run safely more than once?
|
||||
4. Will it fail loudly if the important work fails?
|
||||
5. Does it avoid hidden interactive work from pacman?
|
||||
6. Does it belong in `omarchy-upgrade-to-4` instead?
|
||||
7. Did you add or update tests if behavior changed?
|
||||
|
||||
If the answer to any of these is unclear, stop and ask before adding the
|
||||
migration.
|
||||
@@ -0,0 +1,318 @@
|
||||
# Omarchy update process
|
||||
|
||||
This document describes the intended update behavior now that Omarchy is
|
||||
package-backed. It covers the blessed update path plus what happens when a user attempts to
|
||||
bypass it:
|
||||
|
||||
1. `omarchy update` — the blessed interactive Omarchy update flow.
|
||||
2. `sudo pacman -Syu` — guarded by Omarchy and aborted with instructions unless
|
||||
the user explicitly bypasses the guard.
|
||||
|
||||
The design goal is:
|
||||
|
||||
- System/root migrations should run automatically from package transactions when
|
||||
safe.
|
||||
- User/session migrations should never run invisibly from pacman because they may
|
||||
need `$HOME`, DBus/session state, a graphical session, or user interaction.
|
||||
- Users who bypass `omarchy update` should still get system migrations from
|
||||
pacman and should be notified only when their own user migration state is
|
||||
missing a shipped user migration.
|
||||
|
||||
## State and coordination files
|
||||
|
||||
| Path | Owner | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `${XDG_RUNTIME_DIR:-/tmp}/omarchy-update.lock` | user | Prevent overlapping update runs. Owned by `omarchy-update`; compatibility wrappers inherit/respect it. |
|
||||
| `/tmp/omarchy-update.log` | user | Transcript of `omarchy update`, used by `omarchy-update-analyze-logs`. |
|
||||
| `~/.local/state/omarchy/updates/` | user | Update-check state for the shell widget (`packages`, `aur`, `available`, `checked-at`, `error`). |
|
||||
| `/var/lib/omarchy/migrations/system/` | root | System migration markers. |
|
||||
| `~/.local/state/omarchy/migrations/user/` | user | User migration markers. |
|
||||
| `~/.local/state/omarchy/reboot-required` | user | Optional reboot marker checked by `omarchy-update-restart`. |
|
||||
| `~/.local/state/omarchy/restart-*-required` | user | Optional service/app restart markers checked by `omarchy-update-restart`. |
|
||||
|
||||
## Migration layout
|
||||
|
||||
See [`migrations.md`](migrations.md) for the full migration model, authoring
|
||||
guidelines, and troubleshooting notes.
|
||||
|
||||
Migrations are scoped by directory:
|
||||
|
||||
```text
|
||||
migrations/system/*.sh
|
||||
migrations/user/*.sh
|
||||
```
|
||||
|
||||
### System migrations
|
||||
|
||||
System migrations are root-owned, noninteractive fixes for existing installs.
|
||||
They may touch `/etc`, `/usr`, `/boot`, system services, hardware configuration,
|
||||
and other machine-wide state.
|
||||
|
||||
Runner:
|
||||
|
||||
```bash
|
||||
omarchy-migrate-system
|
||||
```
|
||||
|
||||
Completion state:
|
||||
|
||||
```text
|
||||
/var/lib/omarchy/migrations/system/<migration filename>
|
||||
```
|
||||
|
||||
Pacman integration:
|
||||
|
||||
```text
|
||||
pkgbuilds/omarchy/omarchy.install post_upgrade()
|
||||
```
|
||||
|
||||
The `omarchy` package calls `omarchy-migrate-system` from `post_upgrade()`.
|
||||
The runner is idempotent, so repeated calls only check the state files.
|
||||
|
||||
### User migrations
|
||||
|
||||
User migrations are current-user/session fixes. They may touch `~/.config`,
|
||||
`~/.local`, user systemd units, browser/editor preferences, DBus/session state,
|
||||
or ask questions.
|
||||
|
||||
Runner:
|
||||
|
||||
```bash
|
||||
omarchy-migrate-user
|
||||
```
|
||||
|
||||
Public command:
|
||||
|
||||
```bash
|
||||
omarchy-migrate
|
||||
```
|
||||
|
||||
Completion state:
|
||||
|
||||
```text
|
||||
~/.local/state/omarchy/migrations/user/<migration filename>
|
||||
```
|
||||
|
||||
A user migration is pending only when a script exists in `migrations/user/` and
|
||||
that user's matching state file is missing. There is no global root-owned queue
|
||||
for user migrations.
|
||||
|
||||
`omarchy-migrate` is the public command. It waits for any active pacman
|
||||
transaction to finish, runs pending system migrations, then runs pending user
|
||||
migrations. It does not need `--force`; migrations should happen when they are
|
||||
pending.
|
||||
|
||||
For watchers and diagnostics, `omarchy-migrate --pending [all|system|user]`
|
||||
prints pending migration names and exits `0` when any are pending. Output is
|
||||
scope-prefixed, for example:
|
||||
|
||||
```text
|
||||
system/100-system.sh
|
||||
user/200-user.sh
|
||||
```
|
||||
|
||||
When no matching migrations are pending, it prints nothing and exits non-zero.
|
||||
|
||||
## Raw pacman guard
|
||||
|
||||
The `omarchy` package installs an ALPM pre-transaction hook alongside its guard
|
||||
binary:
|
||||
|
||||
```text
|
||||
/usr/share/libalpm/hooks/00-omarchy-update-guard.hook
|
||||
/usr/bin/omarchy-update-pacman-guard
|
||||
```
|
||||
|
||||
It triggers on package upgrades and runs:
|
||||
|
||||
```bash
|
||||
omarchy-update-pacman-guard
|
||||
```
|
||||
|
||||
The guard detects direct pacman system-upgrade commands like `pacman -Syu` or
|
||||
`pacman --sync --refresh --sysupgrade`. If the upgrade was not launched by an
|
||||
Omarchy update command, the hook exits non-zero with `AbortOnFail`, which stops
|
||||
the transaction before packages are changed.
|
||||
|
||||
`omarchy-update-system-pkgs`, `omarchy-refresh-pacman`, `omarchy-reinstall-pkgs`,
|
||||
and the v4 upgrader run pacman through:
|
||||
|
||||
```bash
|
||||
env OMARCHY_UPDATE_PACMAN=1 pacman ...
|
||||
```
|
||||
|
||||
so the guard allows Omarchy-owned update flows. A user can intentionally bypass
|
||||
the guard with:
|
||||
|
||||
```bash
|
||||
sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu
|
||||
```
|
||||
|
||||
The guard does not start `omarchy update` itself because pacman is already in a
|
||||
transaction setup path; it only aborts with instructions.
|
||||
|
||||
## Path 1: `omarchy update`
|
||||
|
||||
High-level flow:
|
||||
|
||||
```text
|
||||
omarchy-update
|
||||
├─ ensure transcript logging through script(1) → /tmp/omarchy-update.log
|
||||
├─ acquire update lock
|
||||
├─ confirm unless -y
|
||||
├─ create snapper snapshot, if snapper is installed
|
||||
└─ run update pipeline
|
||||
├─ block system sleep and temporarily enable shell stay-awake mode
|
||||
├─ omarchy-update-keyring
|
||||
├─ omarchy-update-system-pkgs
|
||||
├─ omarchy-migrate
|
||||
├─ omarchy-hook post-update
|
||||
├─ omarchy-update-aur-pkgs
|
||||
├─ omarchy-update-mise
|
||||
├─ omarchy-update-orphan-pkgs
|
||||
├─ omarchy-update-analyze-logs
|
||||
├─ omarchy-update-available, then refresh/clear shell indicator
|
||||
├─ omarchy-update-restart
|
||||
└─ release sleep inhibitor and restore shell idle state, if changed
|
||||
```
|
||||
|
||||
Important behavior:
|
||||
|
||||
- `omarchy update` checks/runs system and user migrations in the same visible
|
||||
terminal via `omarchy-migrate`.
|
||||
- `omarchy update` still benefits from pacman-triggered system migrations
|
||||
because the system migration hook runs as part of the pacman transaction.
|
||||
- A failure should leave enough output in `/tmp/omarchy-update.log` and the
|
||||
terminal transcript to debug.
|
||||
|
||||
## Path 2: direct `sudo pacman -Syu` attempt
|
||||
|
||||
High-level flow:
|
||||
|
||||
```text
|
||||
sudo pacman -Syu
|
||||
├─ pre-transaction guard aborts and tells the user to run omarchy update
|
||||
└─ if explicitly bypassed, upgrades omarchy and related packages
|
||||
├─ omarchy post_upgrade runs omarchy-migrate-system as root
|
||||
└─ user session notices migration directory changes
|
||||
├─ omarchy-update-user-notify.path triggers, if enabled
|
||||
├─ omarchy-migrate-notify checks omarchy-migrate --pending user
|
||||
├─ if this user has missing migration state, show notification
|
||||
└─ click opens terminal: omarchy-migrate
|
||||
```
|
||||
|
||||
Fallbacks:
|
||||
|
||||
- `omarchy-first-run` enables the user notification path unit.
|
||||
- `omarchy-first-run` also invokes `omarchy-migrate-notify` on graphical
|
||||
startup, so users who updated before the path unit existed still get prompted
|
||||
if they have missing user migration state.
|
||||
- The notifier is only a prompt. It does not run user migrations in the
|
||||
background.
|
||||
- Direct pacman updates do not run `omarchy-hook post-update` unless the user
|
||||
explicitly runs that hook; without a package-update marker, the only user-side
|
||||
pending state we can derive is missing user migration markers.
|
||||
|
||||
## Shell update indicator
|
||||
|
||||
The bar widget `omarchy.system-update` runs:
|
||||
|
||||
```bash
|
||||
omarchy-update-available
|
||||
```
|
||||
|
||||
`omarchy-update-available` uses `checkupdates` with a temporary database when
|
||||
available, plus `yay -Qua` for AUR updates when foreign packages are installed.
|
||||
It stores the result in:
|
||||
|
||||
```text
|
||||
~/.local/state/omarchy/updates/packages
|
||||
~/.local/state/omarchy/updates/aur
|
||||
~/.local/state/omarchy/updates/available
|
||||
~/.local/state/omarchy/updates/checked-at
|
||||
~/.local/state/omarchy/updates/error
|
||||
```
|
||||
|
||||
Exit codes:
|
||||
|
||||
- `0` — updates are available; stdout is the update list.
|
||||
- non-zero — no updates are available; stdout says the system is up to date.
|
||||
|
||||
The widget uses the line count to show/hide itself. It also watches the
|
||||
`available` state file, so manually running `omarchy-update-available` updates
|
||||
the widget as soon as the file changes. Hovering the update icon opens a panel
|
||||
that lists Omarchy packages first, then all other package updates.
|
||||
|
||||
## Update-related binaries
|
||||
|
||||
This inventory is intentionally opinionated. Some commands are useful as stable
|
||||
leaf commands; others exist mostly because the old update flow accreted small
|
||||
scripts.
|
||||
|
||||
| Binary | Current purpose | Keep? / Question |
|
||||
| --- | --- | --- |
|
||||
| `omarchy-update` | Public user command. Adds transcript logging, lock, confirmation, snapshot, sleep/idle inhibitors, package updates, migrations, hooks, update-state refresh, and restart checks. | **Keep.** This is the blessed entry point and owns the update pipeline. |
|
||||
| `omarchy-update-perform` | Hidden compatibility wrapper for `omarchy-update -y`. | **Temporary.** Keep only for old callers; new code should call `omarchy-update` directly. |
|
||||
| `omarchy-update-confirm` | Gum confirmation copy for `omarchy update`. | **Question.** Could be inlined into `omarchy-update`; separate file only helps keep copy isolated. |
|
||||
| `omarchy-update-keyring` | Ensures Omarchy keyring and Arch keyring are current before the main transaction. | **Keep, but review.** It uses targeted `pacman -Sy` for keyring bootstrapping; acceptable for this special case but should remain tightly scoped. |
|
||||
| `omarchy-update-system-pkgs` | Runs `sudo env OMARCHY_UPDATE_PACMAN=1 pacman -Syu --noconfirm` with targeted transition `--overwrite` entries so the ALPM guard allows the transaction and early package-layout conflicts are handled. | **Keep for now.** Small leaf command, clear/testable. |
|
||||
| `omarchy-migrate-system` | Runs root/system migrations from `migrations/system`. Called by `omarchy` package `post_upgrade()` and by `omarchy-migrate` when system migration state is missing. | **Keep.** This is the important direct-`pacman -Syu` integration. |
|
||||
| `omarchy-migrate-user` | Checks `migrations/user` against this user's state and runs only missing user migrations. Supports `--pending` and prints pending filenames. | **Keep internal.** Public users should generally run `omarchy-migrate`. |
|
||||
| `omarchy-migrate` | Public migration command. Waits for pacman, then runs pending system and user migrations. Supports `--pending [all|system|user]` and prints scope-prefixed pending filenames. | **Keep.** This replaces the discarded `omarchy-update-user-finalize` name and no longer needs `--force`. |
|
||||
| `omarchy-update-pacman-guard` | ALPM pre-transaction guard that aborts direct `pacman -Syu` style upgrades unless Omarchy set `OMARCHY_UPDATE_PACMAN=1` or the user explicitly set `OMARCHY_ALLOW_DIRECT_PACMAN=1`. | **Keep internal/hidden.** This is what nudges users back to `omarchy update`. |
|
||||
| `omarchy-migrate-notify` | Internal notification helper for direct pacman updates. Uses `omarchy-migrate --pending user` and shows notification only when this user has pending migrations. | **Keep internal/hidden.** Clear name now that the public command is `omarchy-migrate`. |
|
||||
| `omarchy-update-user-notify` | Hidden compatibility wrapper for `omarchy-migrate-notify`. | **Temporary.** Keep only for old callers. |
|
||||
| `omarchy-update-available` | Update checker for shell widget and post-update refresh. Writes update state. | **Keep.** Could eventually be renamed `omarchy-update-check`, but current name matches widget semantics. |
|
||||
| `omarchy-update-aur-pkgs` | Updates AUR packages with `yay -Sua` if foreign packages exist and AUR is reachable. | **Question.** Omarchy is package-backed now, but users may still install AUR packages. Keep for now. |
|
||||
| `omarchy-update-mise` | Runs `mise up` for mise-managed tools. | **Keep.** Mise-managed tools are intentionally part of the blessed update path. |
|
||||
| `omarchy-update-orphan-pkgs` | Lists orphans and prompts before removal; noninteractive mode never removes. | **Keep for now.** Safe because it is prompt-only. |
|
||||
| `omarchy-update-analyze-logs` | Scans `/tmp/omarchy-update.log` for known failure patterns, currently initramfs generation. | **Keep/expand.** Useful safety net; should grow only for high-signal checks. |
|
||||
| `omarchy-update-restart` | Prompts for reboot after kernel/Hyprland updates and restarts components with `restart-*-required` markers. | **Keep.** Important final step; may eventually include service-restart checks. |
|
||||
| `omarchy-update-firmware` | Manual firmware update command using fwupd. Not part of the normal update pipeline. | **Keep separate.** Firmware is not a routine system update step. |
|
||||
| `omarchy-update-time` | Restarts `systemd-timesyncd`. | **Question.** Not really an update command. Consider renaming/moving under system/time maintenance. |
|
||||
|
||||
## Closed decisions
|
||||
|
||||
1. **System migrations run from the `omarchy` package**
|
||||
- `omarchy.install post_upgrade()` calls `omarchy-migrate-system`.
|
||||
- We do not need a separate system-migration ALPM hook from
|
||||
`omarchy-settings`.
|
||||
|
||||
2. **Root vs user migrations stay separate**
|
||||
- Do not use `su {user}` from pacman to run user migrations.
|
||||
- User migrations need the user's real session and should be visible.
|
||||
- Pending user work is determined only by comparing `migrations/user/*.sh`
|
||||
against `~/.local/state/omarchy/migrations/user/`.
|
||||
|
||||
3. **Migration notification naming**
|
||||
- The real helper is `omarchy-migrate-notify`.
|
||||
- `omarchy-update-user-notify` remains only as a hidden compatibility wrapper.
|
||||
|
||||
4. **Update pipeline ownership**
|
||||
- `omarchy-update` owns the full update pipeline now.
|
||||
- `omarchy-update-perform` is only a hidden compatibility wrapper for
|
||||
`omarchy-update -y`.
|
||||
|
||||
5. **Mise remains in the blessed update path**
|
||||
- `omarchy-update-mise` intentionally runs as part of `omarchy update`.
|
||||
|
||||
6. **Orphan cleanup stays in the update path for now**
|
||||
- It is prompt-only and never removes packages noninteractively.
|
||||
|
||||
7. **Direct pacman user follow-up is based on actual migration state**
|
||||
- Direct `sudo pacman -Syu` no longer uses a fake user-update marker.
|
||||
- User notifications are shown only when `omarchy-migrate --pending user`
|
||||
finds missing per-user migration state.
|
||||
|
||||
## Remaining concerns
|
||||
|
||||
1. **Pacman guard scope**
|
||||
- The guard detects direct pacman sysupgrade invocations and allows Omarchy
|
||||
commands that set `OMARCHY_UPDATE_PACMAN=1`.
|
||||
- We may regret blocking some legitimate package-manager frontends or
|
||||
maintenance flows. Keep an eye on what should be allowed versus redirected
|
||||
to `omarchy update`.
|
||||
|
||||
2. **Pacnew/pacsave handling is still missing**
|
||||
- Package-backed Omarchy should warn about or help process `.pacnew` and
|
||||
`.pacsave` files after updates.
|
||||
Reference in New Issue
Block a user