Elliot's dot files

A Nix-centric dotfiles configuration that manages system packages and core configurations declaratively, while maintaining flexibility for custom shell functions and scripts.

Structure

The dotfiles are organized around Nix as the primary configuration system, with custom shell scripts for flexibility:

• flake.nix: Flake inputs and outputs for macOS, Debian, and NixOS
• hosts/: Configuration for each machine or deployment target
• modules/: Reusable Home Manager, NixOS, and nix-darwin modules
• shell/: Custom shell functions and completions that extend the base configuration
• bin/: Executable scripts available in PATH

Core Philosophy

This setup uses Nix where it excels (declarative package and configuration management) while keeping shell functions and scripts flexible for rapid iteration and customization.

What's Inside

Nix Configuration

• flake.nix: Main flake configuration for macOS, Debian, and NixOS
• hosts/: Machine-specific system and Home Manager configurations
• modules/home/: Reusable Home Manager configuration for user programs
• modules/nixos/: Reusable NixOS system configuration
• modules/darwin/: Reusable nix-darwin system configuration

Shell Extensions

• shell/functions/: Custom shell functions (git helpers, prompt, window management)
• shell/completions/: Custom zsh completions
• bin/: Utility scripts and git helpers

How It Works

Nix Management

Nix handles:

• Package installation and management
• Core program configuration (git, zsh, tmux, etc.)
• Environment variables and shell aliases
• System-level settings

Shell Function Loading

The zsh configuration automatically loads:

• All *.zsh files from shell/functions/ as shell functions
• All *.zsh files from shell/completions/ as completions (after compinit)
• Scripts from bin/ are automatically added to $PATH

Adding New Functionality

• Declarative user config: Add to the appropriate module in modules/home/
• NixOS system config: Add to the appropriate host or reusable module in modules/nixos/
• macOS system config: Add to the appropriate host or reusable module in modules/darwin/
• Shell functions: Create new .zsh files in shell/functions/
• Completions: Add completion scripts to shell/completions/
• Executables: Add scripts to bin/

NixOS usage

NixOS support is new and experimental in this repository. It is not yet a first-class or established part of the setup in the same way as the existing macOS and Debian configurations. The NixOS hosts are currently being used to learn NixOS and explore how much configuration can be shared safely.

The workstation uses Home Manager as a NixOS module. nixos-rebuild therefore applies both the system configuration and Elliot's Home Manager configuration as a single operation. The user configuration imports the same modules from modules/home/ that are used by the standalone Debian and nix-darwin configurations.

The agent VM is intentionally a minimal NixOS system and does not currently use Home Manager. Its configuration focuses on the isolated agent environment and system-level packages.

Installation

Bootstrapping

The macOS machines use Lix, nix-darwin, and integrated Home Manager. Debian uses Lix with standalone Home Manager, while the experimental NixOS machines use the Home Manager integration defined by this flake where needed. See the bootstrap guide for installation instructions.

Setup

# For macos personal machine
sudo darwin-rebuild build --flake .#elliot@macos-personal
sudo darwin-rebuild switch --flake .#elliot@macos-personal

# For macos work machine
sudo darwin-rebuild build --flake .#elliotblackburn@macos-work
sudo darwin-rebuild switch --flake .#elliotblackburn@macos-work

# For the Debian desktop
home-manager switch --flake .#elliot@desktop

# For the NixOS workstation
sudo nixos-rebuild build --flake .#workstation
sudo nixos-rebuild switch --flake .#workstation

# For the agent VM
sudo nixos-rebuild build --flake .#agent-vm
sudo nixos-rebuild switch --flake .#agent-vm

Customization

• Edit reusable user configurations in modules/home/
• Edit machine-specific configurations in hosts/
• Add shell functions to shell/functions/
• Modify the flake.nix for system-level changes
• Use ~/.localrc and ~/.localaliases for machine-specific overrides

Garbage collection

Nix retains old profile generations so that previous configurations can be rolled back. Remove generations that are no longer needed, then run garbage collection to delete store paths that are no longer reachable.

# Keep the five most recent system generations.
sudo nix-env --delete-generations +5 --profile /nix/var/nix/profiles/system

# Remove standalone Home Manager generations older than 30 days.
home-manager expire-generations "-30 days"

# Reclaim the disk space used by unreachable store paths.
sudo nix store gc

Removing generations also removes the ability to roll back to them. Garbage collection only reclaims paths that are no longer referenced by a remaining generation or another garbage-collection root.

Notes

• asdf is accounted for via shims and functions in the zsh/bash scripts, but it's not encouraged. Most systems managed by these dotfiles don't use them but it's there to support other systems.