Lesson 18 — Everyday nixproject Workflow¶

Practical reference for your own config at ~/nixproject/. All the commands here are specific to your setup — the exact files to edit, the exact commands to run.

The Basic Loop¶

Every change follows the same three steps:

1. Edit a .nix file in ~/nixproject/
2. (Optional) Build without switching to catch errors first
3. sudo nixos-rebuild switch --flake ~/nixproject#elitebook

That one switch command applies both the system config (NixOS) and your user environment (Home Manager) in one shot. No separate home-manager switch needed.

Where to Edit What¶

~/nixproject/
├── modules/home/
│   ├── apps.nix        ← GUI apps (Firefox, Joplin, Zoom, Jellyfin…)
│   ├── cli.nix         ← terminal tools (bat, eza, ripgrep, atuin, git…)
│   ├── selfhosted.nix  ← self-hosted clients (Nextcloud, Nheko, Bitwarden…)
│   ├── streaming.nix   ← audio/streaming (Mixxx, OBS, Audacity, EasyEffects…)
│   ├── editors.nix     ← neovim, helix
│   ├── shell.nix       ← zsh config, aliases, starship prompt
│   ├── sway.nix        ← Sway keybinds and layout
│   ├── terminal.nix    ← foot, tmux
│   └── theming.nix     ← Catppuccin Mocha
├── modules/nixos/
│   ├── common.nix      ← system services, users, networking, Tailscale
│   └── desktop.nix     ← SDDM, PipeWire, Sway/Plasma, fonts, keyring
└── hosts/elitebook/
    └── default.nix     ← EliteBook-only: Hyprland, fingerprint reader

Rule: personal apps and dotfiles go in modules/home/. Anything that needs root or a system service goes in modules/nixos/.

Adding a Package¶

GUI app or personal tool¶

Open ~/nixproject/modules/home/apps.nix (or cli.nix for terminal tools) and add to home.packages:

home.packages = with pkgs; [
  vlc          # ← add here
  firefox
  joplin-desktop
];

Then rebuild:

sudo nixos-rebuild switch --flake ~/nixproject#elitebook

System-wide tool (available to all users / needs root)¶

Open ~/nixproject/modules/nixos/common.nix and add to environment.systemPackages:

environment.systemPackages = with pkgs; [
  git wget curl
  htop          # ← add here
];

Using a `programs.*` module instead of a raw package¶

Many tools have Home Manager modules that also write config files for you. Check search.nixos.org/options or home-manager-options.extradomain.net first.

Example — git is already managed this way in cli.nix:

programs.git = {
  enable = true;
  userName = "Marcus";
  userEmail = "marcus@wilsoz.com";
  delta.enable = true;
};

That generates ~/.gitconfig for you — no manual dotfile needed.

Finding the right package name¶

# Search by keyword
nix search nixpkgs vlc

# Or browse https://search.nixos.org/packages

Trying a package before committing to it¶

# Opens a shell with the package available — gone when you exit
nix shell nixpkgs#vlc

# Run it once without installing at all
nix run nixpkgs#vlc

Enabling a System Service¶

System services go in modules/nixos/common.nix or desktop.nix. Example — enable SSH:

# common.nix
services.openssh.enable = true;

Or a service that needs a bit more config:

services.syncthing = {
  enable = true;
  user = "marcus";
  dataDir = "/home/marcus/Sync";
};

Then rebuild:

sudo nixos-rebuild switch --flake ~/nixproject#elitebook

Updating the System¶

Updating means moving flake.lock to newer commits, then rebuilding.

Update everything¶

cd ~/nixproject
nix flake update
sudo nixos-rebuild switch --flake ~/nixproject#elitebook --show-trace

Update one input only¶

nix flake update nixpkgs
nix flake update home-manager

What gets updated¶

flake.update pulls the latest commits from all your inputs — nixpkgs, home-manager, disko, sops-nix, nixos-hardware, catppuccin. It rewrites flake.lock. No packages are downloaded until you rebuild.

Build First, Switch Later¶

When you're not sure a change is correct, build without activating:

# Builds everything, reports errors, doesn't touch the running system
sudo nixos-rebuild build --flake ~/nixproject#elitebook --show-trace

If it succeeds, then switch:

sudo nixos-rebuild switch --flake ~/nixproject#elitebook

--show-trace gives you the full error stack when something fails. Always add it when debugging.

Rolling Back¶

Instant rollback (no reboot needed)¶

sudo nixos-rebuild switch --rollback

Reboot, pick the previous entry from the systemd-boot menu. Every nixos-rebuild switch adds an entry — the boot menu is your history.

List all generations¶

sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

Checking What Changed¶

# See what flake.lock updated since last commit
git -C ~/nixproject diff flake.lock

# Dry-run: show what would be built/downloaded without doing it
sudo nixos-rebuild dry-activate --flake ~/nixproject#elitebook

Garbage Collection¶

Old generations accumulate in /nix/store. Your config already runs GC automatically every week (deletes generations older than 21 days — see modules/nixos/common.nix). Run it manually when you need disk back now:

# Delete generations older than 21 days
sudo nix-collect-garbage --delete-older-than 21d

# Nuclear option — delete everything except the current generation
sudo nix-collect-garbage -d

Don't run -d if you want to be able to roll back. Keep a few generations around.

Working on the MacBook Air¶

Same commands, different host name:

sudo nixos-rebuild switch --flake ~/nixproject#macair

~/nixproject needs to exist on the Air too (copy it over or clone from git). The hosts/macair/hardware-configuration.nix is machine-specific — don't overwrite it with the EliteBook's version.

Quick Reference¶

# Add a package, then rebuild
# edit ~/nixproject/modules/home/apps.nix
sudo nixos-rebuild switch --flake ~/nixproject#elitebook

# Build without switching (test first)
sudo nixos-rebuild build --flake ~/nixproject#elitebook --show-trace

# Update all inputs then rebuild
cd ~/nixproject && nix flake update
sudo nixos-rebuild switch --flake ~/nixproject#elitebook --show-trace

# Roll back to previous generation
sudo nixos-rebuild switch --rollback

# Try a package without installing it
nix shell nixpkgs#packagename

# Search for packages
nix search nixpkgs keyword
# or: https://search.nixos.org/packages

# Free up disk space
sudo nix-collect-garbage --delete-older-than 21d

# List generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system