Bernardo Magri
9e37e11915
Some checks failed
Check / eval (push) Failing after 3m11s
With settings.autoCommit on, only menu/theme mutations were committed (theme-sync pathspec-limits to theme-state.json by design), so hand edits to system.nix/home.nix and lock bumps stayed forever-dirty. New internal nomarchy-autocommit (nomarchy-lifecycle): live-reads the same flag, commits everything dirty as "nomarchy: auto-commit before <pull|rebuild|home switch>" with the swept file list in the body, fallback identity, never fatal (|| true at call sites). Called at the top of all three lifecycle commands; before the ff-only pull it also un-dirties the tree. Exposed via passthru.autocommit + package export; guarded by checks.lifecycle-autocommit (sandbox repos: sweep, no-op on clean/off/non-repo). Sync sweep: README, RECOVERY, ROADMAP, rofi toggle, control-center prompt, theme-sync docstring, JOURNAL. Verified: V1+ — flake check --no-build green; the new check builds; end-to-end run of the built nomarchy-rebuild (stubbed sudo/rebuild) against a copy of a real dirty ~/.nomarchy: 4 files → one commit, clean tree. No VM boot — no session-visible surface. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
95 lines
4.0 KiB
Markdown
95 lines
4.0 KiB
Markdown
# Recovery runbook — when something breaks
|
||
|
||
Ordered from "the desktop looks wrong" to "the machine won't boot".
|
||
Everything here already ships on an installed machine — you don't need a
|
||
live USB until the last resort. The theme is always the same: **nothing
|
||
in Nomarchy is destroyed by a bad change** — every rebuild is a NixOS /
|
||
Home Manager generation you can step back to, and (on BTRFS installs)
|
||
snapper keeps file-level history on top.
|
||
|
||
If the graphical session is unusable, a text console is one keystroke
|
||
away: **Ctrl+Alt+F2** gives a TTY login (the session itself runs on
|
||
tty1); log in with your normal user.
|
||
|
||
## 1. A theme or desktop change broke the session
|
||
|
||
Theme applies and `home-update` are Home Manager switches — one
|
||
generation each, so the previous desktop is still on disk:
|
||
|
||
```sh
|
||
home-manager generations # newest first, one per theme/HM change
|
||
/nix/store/…-home-manager-generation/activate # run the one you want
|
||
```
|
||
|
||
The same picker lives in the menu: **System › Rollback** lists the
|
||
recent desktop generations — pick one and it activates.
|
||
|
||
Or simply apply a theme you know is good: `nomarchy-theme-sync apply
|
||
boreal` (or any preset). If a switch failed halfway, the state file is written
|
||
*before* the rebuild — fix the cause and re-run
|
||
`home-manager switch --flake ~/.nomarchy` (or `nomarchy-home`).
|
||
|
||
Your flake checkout is a git repo, and with auto-commit enabled every
|
||
apply is a commit — and every `nomarchy-pull`/`-rebuild`/`-home` first
|
||
sweeps pending hand edits into one, so history mirrors your generations:
|
||
`git -C ~/.nomarchy log` to see what changed, `git revert` the culprit,
|
||
then `nomarchy-home`.
|
||
|
||
## 2. The desktop won't start at all
|
||
|
||
Greeter loops, black screen after the password, session exits straight
|
||
back to tuigreet — from the Ctrl+Alt+F2 TTY:
|
||
|
||
```sh
|
||
journalctl -b -u greetd # did the session command launch?
|
||
journalctl --user -b # Hyprland + the user services
|
||
```
|
||
|
||
- Rolling back the *desktop* half is §1 (works from the TTY).
|
||
- If greetd/tuigreet itself is broken, that's system-side → §3.
|
||
- In a **VM**, a black screen is almost always missing guest OpenGL,
|
||
not your config — see docs/TESTING.md §5.
|
||
- First boot after an install came up *unthemed*: read
|
||
`/var/log/nomarchy-hm-preactivate.log` on the installed system.
|
||
|
||
## 3. A system change broke it — boot an older generation
|
||
|
||
Reboot and pick an older **NixOS generation** in the systemd-boot menu
|
||
(hold a key during firmware handoff if the menu doesn't linger; the
|
||
last 10 generations are kept). That boots yesterday's system unchanged.
|
||
|
||
Booting an old generation is temporary — the default entry is still the
|
||
broken one. Make the fix stick from the working boot: revert the change
|
||
in `~/.nomarchy` (`git -C ~/.nomarchy revert …` or edit `system.nix`
|
||
back), then `nomarchy-rebuild`.
|
||
|
||
## 4. Files went missing or wrong — snapshots (BTRFS installs)
|
||
|
||
With `nomarchy.system.snapper.enable` (the installer's default on
|
||
BTRFS), the root filesystem has hourly/daily history, and
|
||
`nixos-rebuild-snap` leaves a snapshot right before a rebuild:
|
||
|
||
- **GUI:** menu › System › Snapshots (btrfs-assistant; expects a polkit
|
||
password prompt).
|
||
- **Terminal/SSH:** `sudo nomarchy-snapshots` — browse a snapshot's
|
||
diff, **restore changed files** (snapper `undochange`), or **roll the
|
||
whole root back** to a snapshot and reboot. Both destructive actions
|
||
sit behind a typed-`yes` confirmation.
|
||
|
||
Snapshots are the undo for *data on disk*; the Nix config model is
|
||
undone by generations (§1/§3) — use each for its half.
|
||
|
||
## 5. Last resort — from the outside
|
||
|
||
Boot the Nomarchy ISO (any NixOS ISO works), then:
|
||
|
||
```sh
|
||
sudo mount /dev/<root> /mnt # + /mnt/boot; LUKS: cryptsetup open first
|
||
sudo nixos-enter --root /mnt # chroot with nix available
|
||
```
|
||
|
||
From there you have the full toolbox: `nixos-rebuild boot --flake
|
||
/home/<you>/.nomarchy#default` after fixing the flake, or snapper from
|
||
§4. If you get this far with something Nomarchy shipped broken, please
|
||
file it.
|