visitor@book.rymcg.tech:~/nixos-workstation/making-changes

Making changes going forward

Once the machine reboots, log in as your user. The installation is complete, but the more important habit starts now: your machine’s entire configuration lives in its own git repo in your home directory.

[bash]: Run this on your workstation:
cd ~/nixos

It contains:

  • flake.nix – depends on sway-home (pinned) and calls sway-home.lib.mkHost.
  • disko.nix – the declarative disk layout.
  • hardware.nix – detected hardware (no filesystems; disko owns those).
  • config.nix – your host-specific overrides (locale, packages, services, SSH keys).
  • Justfile – convenience recipes, run via the admin alias below.

Applying changes with admin

The repo’s recipes are driven by the admin alias, which runs just against ~/nixos/Justfile from any directory, with full recipe and argument tab completion. Run admin help to list the recipes. (It is set up by home-manager on both profiles, so it works the same whether you are on minimal or sway.)

Edit config.nix (or add modules) for changes specific to this machine, and edit sway-home itself for changes you want shared across all of your machines. After editing, git add and commit your changes (a flake only sees files git tracks – it reads edits to tracked files even when dirty, but a brand-new module file is invisible until you git add it), then apply them with admin upgrade, which pulls the latest shared config and rebuilds the system:

[bash]: Run this on your workstation:
git -C ~/nixos commit -am "describe your change"
admin upgrade
warning

git add any new files before admin upgrade. Nix warns when the git tree is dirty but still builds from your edits to tracked files; a file git has never seen, though, is silently left out of the flake – so a new module appears to “do nothing” until you add it. Committing as you go is the simplest way to never hit this.

tip

To try a config without making it permanent, use admin test. Test generations are temporary and are not added to the boot menu, so a reboot returns you to the last generation you applied permanently.

Back up your config to a git remote

Your per-host repo is the only complete, declarative record of how this machine is built. NixOS keeps its generations on the local disk, so you can roll back – but if that disk dies, the history of your configuration dies with it. The repo is the part you are responsible for preserving, so treat ~/nixos like any other source code you care about and push it somewhere off the machine.

Make it a private repository. It describes your machine in detail – its hardware, accounts, services, and authorized SSH keys – which is not something you want to publish, even though it holds no passwords. Add a remote (any Git host – GitHub, a self-hosted Forgejo, or a bare repo over SSH) and push the main branch that setup host created:

[bash]: Run this on your workstation:
git -C ~/nixos remote add origin git@github.com:youruser/nixos-<host>.git
git -C ~/nixos push -u origin main

After that, push whenever you commit a change:

[bash]: Run this on your workstation:
git -C ~/nixos push

With the repo safely pushed, you can rebuild this machine – or stand up a replacement – by cloning it back to ~/nixos and running admin upgrade.

// settings
theme:
fx: