From c9dd7575bf9a3101e69370964fa42518e31b15f2 Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Wed, 15 Jul 2026 12:00:17 +0100 Subject: [PATCH] docs: explain automatic generation prune for users (#128) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RECOVERY §4 documents the 14-day / keep-≥3-past policy for system and Home Manager gens, with dry-run and timer commands. README and REQUIREMENTS point here so install and day-2 hygiene match the product. --- README.md | 7 +++++++ agent/JOURNAL.md | 8 ++++++++ docs/RECOVERY.md | 46 +++++++++++++++++++++++++++++++++++++------- docs/REQUIREMENTS.md | 10 +++++++--- 4 files changed, 61 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index e1e0a35..75bda63 100644 --- a/README.md +++ b/README.md @@ -380,6 +380,13 @@ fonts. No runtime patching means no partial states, and `home-manager generations` is also your theme history. Waybar even restyles in place: it re-reads `style.css` when the symlink flips. +**Cleanup is automatic.** A weekly timer (`nomarchy-gen-prune`) removes +**system** and **Home Manager** generations that are older than **14 days** +*and* beyond the **three most recent past** gens — so you always keep the +current generation plus at least three rollbacks, even on a rarely rebuilt +machine. Manual: `sudo nomarchy-gen-prune --dry-run`. Full story: +[docs/RECOVERY.md §4](docs/RECOVERY.md#4-how-generations-are-kept-and-cleaned-up). + The **wallpaper** is the one runtime piece (awww — nixpkgs' swww — is imperative; nothing in Nix consumes the path): applied at session start, after every switch via a tiny activation hook, and again when a monitor is diff --git a/agent/JOURNAL.md b/agent/JOURNAL.md index 797e179..6721b70 100644 --- a/agent/JOURNAL.md +++ b/agent/JOURNAL.md @@ -19,6 +19,14 @@ Template: --- +## 2026-07-15 — Document generation prune for users (#128 docs) +- **Task:** User-facing docs for the 14d / keep-≥3-past policy. +- **Did:** RECOVERY §4 (how gens are kept); README generation section + + alias note; REQUIREMENTS hygiene points at the automatic prune. +- **Verified:** V0 (docs only). +- **Pending:** none. +- **Next suggestion:** hardware V3 or human #115/#120. + ## 2026-07-15 — #128 generation prune (14d + keep ≥3 past, system+HM) - **Task:** Implement auto-prune for system and Home Manager generations. - **Did:** `pkgs/nomarchy-gen-prune` + `modules/nixos/gen-prune.nix` weekly diff --git a/docs/RECOVERY.md b/docs/RECOVERY.md index c96fb7c..b841bd6 100644 --- a/docs/RECOVERY.md +++ b/docs/RECOVERY.md @@ -57,20 +57,52 @@ journalctl --user -b # Hyprland + the user services ## 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. +(hold a key during firmware handoff if the menu doesn't linger). 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`. -**Automatic prune (#128):** a weekly timer (`nomarchy-gen-prune`) removes -system *and* Home Manager generations that are **older than 14 days** and -**beyond the three most recent past gens** (current + ≥3 past always kept). -Manual: `sudo nomarchy-gen-prune` (or `--dry-run`). +How long generations stick around (and how cleanup works) is §4 below. -## 4. Files went missing or wrong — snapshots (BTRFS installs) +## 4. How generations are kept (and cleaned up) + +Every `nomarchy-rebuild` and `nomarchy-home` (and every theme switch) leaves +a **generation** — a full previous system or desktop you can roll back to +(§1 and §3, and **System › Recovery**). Those take disk space until they +are removed. + +Nomarchy prunes them **automatically once a week** with a policy designed +not to strand you without rollback: + +| Rule | Meaning | +|------|---------| +| **Age** | Generations older than **14 days** are eligible for removal. | +| **Safety floor** | Always keep the **current** generation and at least **3 past** ones — even if those three are older than 14 days. | +| **Both halves** | The same rule applies independently to the **system** (boot menu) and to **Home Manager** (desktop) profiles. | + +So a busy machine that rebuilds often can still free old junk after two +weeks, while a rarely rebuilt laptop never drops below four usable +system gens (current + three past) or four desktop gens. + +**What you do not need to do:** run aggressive `nix-collect-garbage -d` +day to day — that can delete *all* old generations and wipe the floor. +The weekly timer already reclaims store paths after a careful prune. + +**Manual control:** + +```sh +sudo nomarchy-gen-prune --dry-run # list what would be deleted +sudo nomarchy-gen-prune # prune now (same rules as the timer) +systemctl status nomarchy-gen-prune.timer +``` + +After a system prune the boot menu is refreshed so removed generations +no longer appear as boot entries. + +## 5. 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 diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index e7c0f0b..8d0b583 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -116,9 +116,13 @@ swapfile, leaving room for store + snapshots. is a download/USB cost, not permanent free space on the installed machine after install (the installed system has its own store). -**Hygiene (user-facing, later doc links):** delete old generations, run GC, -tune snapper retention — see [RECOVERY.md](RECOVERY.md) and the System › -Recovery menu. This requirements page only states why the disk fills up. +**Hygiene (automatic on Nomarchy):** a weekly `nomarchy-gen-prune` removes +system and Home Manager generations that are **older than 14 days** and +**beyond the three most recent past gens** (current + ≥3 past always kept), +then reclaims the store. Details and manual commands: +[RECOVERY.md §4](RECOVERY.md#4-how-generations-are-kept-and-cleaned-up). +Also tune snapper retention for BTRFS file history (System › Recovery › +Files). This requirements page only states why the disk fills up. ---