# 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 ```sh git clone --recurse-submodules ~/.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//sbin/* /usr/local/bin/ # if that host has any ``` `install` picks its host layer from `hostname`, lowercased. If there is no `meta/hosts/.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/.conf.yaml` | links only that host gets | | `common/` | host-agnostic config and scripts | | `hosts//` | that machine's deltas | | `hosts//bin` | scripts only that machine needs; shadows `common/bin` on `PATH` | | `hosts//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 `@import`s `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//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-`, 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.