From 61300bd9b9c85fe505e4021b415e45d817d9ea22 Mon Sep 17 00:00:00 2001 From: Daniel Fainberg Date: Sat, 29 Aug 2026 09:37:00 +0200 Subject: [PATCH] docs(readme): add day-to-day upgrade section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explain that a single `nix flake update` in the consumer's own flake bumps every package version — including packages this repo's modules install, since they build against the consumer's nixpkgs via `follows`. Cover per-input bumps and the release-jump caveat. Co-Authored-By: Claude Opus 4.8 --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index 6afaa52..69d3f8b 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,29 @@ this repo pins, not the reverse. Your machine list, hostnames, and any private specifics stay in *your* flake — you pull only the generic modules from here. +## Updating (day-to-day) + +**Every** package version comes from the `nixpkgs` **you** declare — including the packages +this repo's own modules install, since they build against your `nixpkgs` via `follows`, not +against anything this repo pins. So the whole upgrade happens in your flake; you never touch +this repo to move packages, even the ones it declares: + +```sh +nix flake update # bump every input to newest +sudo nixos-rebuild switch --flake .#myhost # build + activate +``` + +`nix flake update` advances `nixpkgs` to the newest commit on the branch you pinned (e.g. +`nixos-unstable` or `nixos-25.11`) — that is what upgrades your packages. `home-manager` and +`baseline` **follow** your `nixpkgs`, so they move in lockstep with no version skew. To move +one input at a time, name it: `nix flake update nixpkgs` bumps only packages; +`nix flake update baseline` pulls the latest **modules** from this repo (new features/fixes) +without changing any package version. These are independent knobs — routine upgrades need +only the `nixpkgs` bump. + +A **release jump** (e.g. `nixos-25.11` → `nixos-26.05`) is not a plain update: edit the +branch in the `nixpkgs` and `home-manager` URLs in your `flake.nix`, then update and rebuild. + ## Overriding the baseline The public modules are a baseline you extend without forking. Three ways to shape them