Atomic, immutable,
declarative.
These words get used interchangeably and they do not mean the same thing. Here is what each one actually means, in plain language, with the distinction almost everybody gets wrong explained at the end.
Atomic update
An update that either completes entirely or does not happen at all. There is no partially-updated state in between.
The new system is built alongside the one you are running, and the machine switches to it in a single step at the end. If the power fails halfway through, you still have the old system, intact and working — not a half-updated one that may not boot. This is the property that makes "an update broke my computer" structurally impossible rather than merely unlikely.
Generation
A complete, bootable snapshot of your system's configuration at one point in time.
On NixOS — and therefore on Golem Linux — every change you make produces a new generation, and the previous ones stay on disk and remain selectable at boot. Your machine's history is a list you can step back through. This is not a backup of your files; it is the system itself, preserved.
Rollback
Returning the computer to a previous known-good state.
The important distinction is how. Windows System Restore attempts to undo changes, which is a repair operation and sometimes fails. A rollback between generations is a switch back to a system that still exists in full — nothing is being reconstructed, so nothing can be reconstructed incorrectly. That is why it is reliable rather than best-effort.
Declarative configuration
Describing the state your system should be in, and letting it work out how to get there.
The opposite is imperative: a sequence of commands that change the system step by step, where the current state is the accumulated result of everything you have ever run — including the things you forgot. With declarative configuration the file is the truth, so the same file always produces the same system, and "what is installed on this machine" has an answer you can read.
Reproducible
A system that can be rebuilt to be identical from its description alone.
Same configuration plus same pinned inputs equals the same result, on any machine, at any time. In practice this means a setup that works can be moved rather than approximated — you do not reinstall and spend a week remembering how you had things.
Nix flake
A unit of Nix configuration with every dependency pinned to an exact version in a lock file.
Pinning is what turns "should build the same" into "does build the same". Golem is distributed as a flake, which is why two commands on your machine produce the same system the developers run.
Context engine
A component that observes what is happening on the computer and decides which affordances are relevant right now.
Open windows, media playback, battery level, connected devices. In
Golem this is options-engine, and it drives what the desktop offers —
so interface elements appear when they are useful and are absent when they are
not, instead of everything being present all the time and most of it being
noise. The philosophy behind it →
Wayland compositor
The program that draws windows and handles input on a modern Linux desktop.
It replaces the older X11 display server and combines the jobs of window manager and display server into one. Golem uses a customized Hyprland.
The one everybody gets wrong: immutable vs declarative
These get used as synonyms in almost every article comparing modern Linux distributions. They describe different properties, and the difference is the entire reason Golem is built on NixOS rather than on an image-based system.
| Immutable (image-based) | Declarative | |
|---|---|---|
| What it protects | A base someone else assembled and shipped as an image | The description of the entire machine, including your applications |
| How you change it | Layer packages on top of the read-only base | Edit the configuration and rebuild |
| Rebuild it elsewhere? | Same base image, but your layers are not part of it | Yes — the whole machine, identically |
| Rollback granularity | Back to a previous image | Back to any previous state of the whole system |
| Examples | Fedora Silverblue, Vanilla OS, openSUSE Aeon | NixOS, Guix, and Golem Linux |
The short version: immutability is a defence, declarativeness is a description. An immutable system stops the base from being damaged. A declarative system knows what the machine is supposed to be, which means it can rebuild it — base, applications, settings and all — anywhere, from a file.
Both give you atomic updates and both give you rollback, so for the everyday question "can an update break my computer?" they answer the same way: no. The difference shows up when you want to move to a new machine, when you want to know exactly what your system contains, or when you want your applications covered by the same guarantee as the base.
Vocabulary should clarify, not gatekeep. If something here is unclear or wrong, tell us.