dotfiles

Everything that makes a machine mine. One branch, four hosts, no per-machine branches — see Why not a branch per machine below.

Bootstrap a bare machine

git clone --recurse-submodules <remote> ~/.dotfiles
cd ~/.dotfiles && ./install
cp common/zsh/secrets.zsh.example ~/.secrets.zsh && chmod 600 ~/.secrets.zsh   # then fill it in
common/bin/pkg-restore                                                         # install the packages
sudo install -m755 hosts/<host>/sbin/* /usr/local/bin/                         # if that host has any

install picks its host layer from hostname, lowercased. If there is no meta/hosts/<hostname>.conf.yaml it stops rather than silently applying only the base config — a half-configured machine that reports success is worse than a clear failure. For a new machine, copy the closest host config and edit.

Layout

Path	What lives here
meta/base.conf.yaml	links every host gets
meta/hosts/<host>.conf.yaml	links only that host gets
common/	host-agnostic config and scripts
hosts/<host>/	that machine's deltas
hosts/<host>/bin	scripts only that machine needs; shadows common/bin on PATH
hosts/<host>/sbin	scripts needing root at /usr/local/bin; not installed by ./install
packages/	what is installed, per host

Where host-specific things go

The rule is that a file is shared unless the machines genuinely disagree, and when they do the disagreement is expressed as a small file rather than a fork.

• zsh — common/zsh/{zshenv,zshrc} source hosts/$DOTFILES_HOST/zsh/*.zsh (interactive) and *.zshenv (all shells). Host fragments are 1–7 lines each. Things that vary by distro rather than by machine — the oh-my-zsh prefix, the zsh-syntax-highlighting path, fd vs fdfind — are probed in common/ instead, so they need no host file at all.
• hyprland — common/hypr/hyprland.conf sources the host layer twice: local-env.conf near the top for anything used later in the file ($browser, env, monitor), and local.conf at the bottom for gaps, binds and overrides. Hyprland resolves variables in file order, so a single source at the end would leave $browser undefined at its first use.
• waybar — one shared config and style.css; the latter @imports local.css for per-screen padding. colors.css is pywal output, regenerated by update_colors.sh.
• git — shared settings in common/git/config, identity via an include of hosts/<host>/git/identity.

Singleton automations

inbox-tidy, movie-recs, rent-utilities and ddns must run on mainframe and nowhere else. They mutate a live mailbox, send notifications, send bills, and update live DNS records. Two independent guards:

1. The units live only in hosts/mainframe/systemd/, never common/, so no other host's config can reference them.
2. Each .service carries ConditionHost=mainframe. If one is ever enabled on the wrong machine, systemd logs a condition failure instead of running it.

The scripts themselves are in hosts/mainframe/bin. hypr_refresh on system76 is not a singleton — it is per-machine and correctly unguarded.

Verify after any change: systemctl --user list-timers --all.

~/.local/bin is not this repo

It used to be a symlink to scripts/, with GOPATH pointing inside it. Every go install and pipx install therefore wrote into version control — 2.2 GB on the work laptop, 426 MB on the personal one. git status was permanently unusable, which is why nothing was committed for a year.

Now ~/.local/bin is an ordinary directory owned by package managers, GOPATH is ~/.local/share/go, and this repo's common/bin and hosts/$HOST/bin go on PATH directly. Do not link a directory that other tools write into.

Secrets

Never in the repo. ~/.secrets.zsh, mode 600, sourced at the end of zshenv so non-interactive shells get it too — deliberately not rbw, which would add a vault round-trip to every script and every ssh host cmd. rbw stays for lazy, interactive use, as in common/zsh/opencode.zsh.

Back up edits by hand as ~/.secrets.zsh.pre-<thing>, matching the convention used across ~/config.

Keeping it honest

dots reports uncommitted files, ahead/behind, and whether the package manifest has gone stale. zshrc calls dots --nag at login, which prints nothing when everything is clean.

After installing something worth keeping: pkg-snapshot, then commit the diff.

Why not a branch per machine

That was the previous design. A shared change had to be cherry-picked into four branches by hand, so it got made locally and never committed; the next change landed on top of an uncommitted one, and the cost of untangling grew until nobody committed at all. By September 2026 there were 146 dirty files across three machines, two histories that had never met, and a NAS that had never been enrolled. Host layers cost a few small files and remove the merge entirely.