connor
e6644d0616
Replaces the previous repo, which had split into two histories that never met (mainframe on a dead GitLab remote, the laptops on Gitea) with 146 dirty files across three machines and the NAS never enrolled at all. Branch-per-machine is gone. One main, with host differences expressed as small files under hosts/<hostname>/ rather than as branches, so there is nothing to merge. The reconciled zsh layer reduces 15-33 line forks to 1-7 effective lines per host; distro differences (oh-my-zsh prefix, syntax-highlighting path, fd vs fdfind) are probed in common/ instead. Fresh history: the old one carried six plaintext credentials, 45 MB of mail caches, browser caches and vendored binaries. 5,096 tracked files and 144 MB become 462 files and 2.6 MB. The .gitignore is now an allowlist, which is what keeps that true. Root cause of the rot: ~/.local/bin was a symlink to scripts/ with GOPATH inside it, so every go install wrote into version control (2.2 GB on the work laptop). PATH now points at the repo instead of the reverse. Also: Hyprland replaces sway and is sourced in two halves so $browser is defined before use; singleton automations carry ConditionHost= alongside host-layer-only placement; ddns moves from cron to a guarded timer; package manifests and pkg-snapshot/pkg-restore replace the X11-era install_scripts/; networkmanager-dmenu added to system76 (the binding always existed, the package never did).
107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# 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 <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 `@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/<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.
|