docs(readme): add day-to-day upgrade section

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 <noreply@anthropic.com>
This commit is contained in:
2026-08-29 09:37:00 +02:00
co-authored by Claude Opus 4.8
parent 38556c8839
commit 61300bd9b9
+23
View File
@@ -101,6 +101,29 @@ this repo pins, not the reverse.
Your machine list, hostnames, and any private specifics stay in *your* flake — you pull Your machine list, hostnames, and any private specifics stay in *your* flake — you pull
only the generic modules from here. 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 ## Overriding the baseline
The public modules are a baseline you extend without forking. Three ways to shape them The public modules are a baseline you extend without forking. Three ways to shape them