Dotfiles#

Personal cross-platform dotfiles managed with Nix.

macOS uses nix-darwin plus Home Manager.
Linux uses standalone Home Manager.

Bootstrap#

Install Nix.
Clone this repo to ~/.dot.
Apply the configuration for the current host.

Automatic upgrades use a separate deploy clone at ~/.dot-deploy by default. That clone is bootstrapped from the origin remote of ~/.dot the first time the scheduled macOS upgrade job runs, then updated independently from its own origin/main afterward.

macOS:

nix run github:nix-darwin/nix-darwin/master#darwin-rebuild -- switch --flake ~/.dot#<hostname>

Linux:

nix run github:nix-community/home-manager -- switch --flake ~/.dot#<hostname>

If flakes are not enabled yet, add --extra-experimental-features 'nix-command flakes' to the command.

The <hostname> value must match the key used in hosts.nix.

Daily Use#

Command	Effect
`just build`	Build the configuration for the current machine
`just check`	Evaluate the flake and build the current machine configuration
`just switch`	Apply the configuration for the current machine
`just hm-build <host>`	Build a specific Linux Home Manager target
`just hm-switch <host>`	Apply a specific Linux Home Manager target

Managing App Configs#

Put the app files under config/<app>/.
Add the app to configs.nix.
Omit paths to link the whole directory to ~/.config/<app>.
Use paths when an app needs file-level links or non-standard destinations such as .aerospace.toml.

Adding A Machine#

Find the machine's real short hostname:
- macOS: scutil --get LocalHostName
- Linux: hostname -s
Add an entry to hosts.nix using that hostname as the attribute name.
Set system to the target platform string, for example aarch64-darwin, x86_64-linux, or aarch64-linux.
Set username to the local account that Home Manager should manage.
Override homeDirectory, flakeDirectory, or deployDirectory only when the machine uses a non-standard path.

You can get the system value on the target machine with:

nix eval --impure --raw --expr builtins.currentSystem

Repository Layout#

.github/workflows/ # remote lock-file maintenance on GitHub
darwin/            # nix-darwin system-level modules for macOS
  default.nix      # main macOS settings, users, Homebrew
  auto-upgrade.nix # sync deploy clone, run darwin-rebuild, and garbage collect
home/              # Home Manager user-level modules shared across platforms
  default.nix      # shared user configuration entry point
  packages/
    shared.nix     # packages installed everywhere
    darwin.nix     # extra packages installed only on macOS
flake.nix          # flake inputs, host normalization, exported outputs
hosts.nix          # machine inventory keyed by real hostname
justfile           # convenience commands for build and switch flows

Notes#

flake.nix exports Darwin hosts as darwinConfigurations and non-Darwin hosts as homeConfigurations.
On macOS, Home Manager is embedded inside nix-darwin, so user configuration still lives under home/.
Daily macOS upgrades rebuild from ~/.dot-deploy, keeping ~/.dot free for branch work and local edits.
The deploy clone is updated with git fetch origin main followed by git merge --ff-only FETCH_HEAD before each scheduled rebuild.
A scheduled GitHub Actions workflow opens a PR that refreshes flake.lock for nixpkgs and neovim-nightly-overlay.
Automatic upgrade logs live at /var/log/darwin-auto-upgrade.log.
The automatic darwin-rebuild job runs daily at 02:00.
Nix garbage collection runs weekly on Sunday at 03:15 and deletes generations older than 30 days.

Configure Feed