197 lines
12 KiB
Markdown
197 lines
12 KiB
Markdown
# dots
|
|
|
|
Unified dotfiles for all machines: one shared base + per-host overlays, deployed with
|
|
[GNU Stow](https://www.gnu.org/software/stow/).
|
|
|
|
## Layout
|
|
|
|
Every top-level directory is a Stow *package* (they all share one stow dir, which `--override`
|
|
requires). `bin/` holds repo tooling and is **not** a package (never stowed):
|
|
|
|
```
|
|
common/ # shared everywhere (mirrors $HOME): fish, nvim, bat, btop, tmux, pi, claude, presenterm, ...
|
|
gui/ # GUI configs shared by graphical hosts: hypr, waybar, kitty, alacritty, mpv, zellij
|
|
wm/ # desktop: 4K monitors, NVIDIA, cloud LLM (duskadiy), work aliases
|
|
lw/ # laptop: no NVIDIA, roaming VPNs, network/LLM tools
|
|
fl/ # KDE Plasma box: a few Hyprland overrides + llamacpp, evremap
|
|
bin/ # tooling (not a stow package): install.sh companions
|
|
install.sh
|
|
```
|
|
|
|
A **headless** (terminal-only) machine has no overlay package — it runs `common` only. Mark any box
|
|
headless with `touch ~/.config/dots-headless` (a machine-local, hostname-independent marker); it then
|
|
skips `gui` too, so the same terminal-only setup replicates across any number of machines. In other
|
|
words `common` *is* the headless baseline; `gui` and the host packages layer graphical machines on top.
|
|
|
|
### How it deploys
|
|
|
|
Deploy order is `common → gui → <host>`; later layers win (the host package is stowed last with
|
|
`--override`, so a host file replaces the common/gui file at the same path). Stow runs with
|
|
`--no-folding`, so each *file* is symlinked individually (directories stay real) — this is what lets
|
|
a host override a single file in a shared dir without shadowing the rest.
|
|
|
|
**Editing a config edits the repo copy directly** (it's a symlink) — no deploy step. You only re-run
|
|
`install.sh` when files are **added or removed** (to create/prune symlinks). See **Syncing** below.
|
|
|
|
The repo must be cloned to **`~/.dots`** (the relative `../.dots` symlink convention). A host's
|
|
package name must match `hostname -s` (or pass the host explicitly, e.g. `./install.sh lw`).
|
|
|
|
## Install (new machine)
|
|
|
|
```fish
|
|
sudo pacman -S stow
|
|
git clone <remote> ~/.dots
|
|
cd ~/.dots
|
|
./install.sh # auto-detects host via `hostname -s`
|
|
```
|
|
|
|
`./install.sh -h` lists all options: `-n` dry-run, `-a` adopt (first run), `-D` unstow (revert),
|
|
`-h` help. GUI hosts also need **HyDE installed** first — see *HyDE dependency* below.
|
|
|
|
Once per machine afterwards: `bat cache --build` (registers the repo's custom bat themes —
|
|
without it every `bat` run warns `Unknown theme 'onedark'`), and `:Lazy restore` inside nvim
|
|
(`restore` obeys the shared `lazy-lock.json` pins; `sync`/`update` would rewrite them).
|
|
nvim's treesitter (`main` branch) builds parsers via the `tree-sitter` CLI — `pacman -S
|
|
tree-sitter-cli` first, or `:TSInstallAll` fails with `ENOENT ... 'tree-sitter'`.
|
|
|
|
### First run on a machine that still has real config files
|
|
|
|
Stow **aborts the whole package on the first conflict** (one real file blocks *everything* in
|
|
`common`), and refuses to clobber real files without `--adopt` — you'll see
|
|
`cannot stow … since neither a link nor a directory`. Adopt them, review, then keep the repo's
|
|
versions:
|
|
|
|
```fish
|
|
cd ~/.dots
|
|
git status # make sure the repo is clean first (see the restore caveat)
|
|
./install.sh -a <host> # --adopt: pull existing files into the repo, symlink them back
|
|
git diff --stat # what this machine had vs the repo (review the drift!)
|
|
git restore . # discard adopted content, keep the repo versions
|
|
```
|
|
|
|
`--adopt` overwrites the repo copies with the machine's files, so `git restore .` is what keeps the
|
|
repo versions. Cautions: adopted changes can land under `common/`/`gui/` even when host-specific, and
|
|
`git restore .` drops **all** uncommitted edits — so commit/stash anything you want first. To keep a
|
|
genuine machine change (e.g. custom pyradio `stations.csv`), hand-copy it into the right package
|
|
instead of restoring that path.
|
|
|
|
## Syncing (day-to-day)
|
|
|
|
Because configs are symlinks into the repo, **you almost never run `install.sh` to sync**:
|
|
|
|
- **Pull/propagate edits:** `cd ~/.dots && git pull` — changes are live in place instantly. No
|
|
re-stow, so **no symlink churn and no app reloads** (kitty etc. keep runtime state).
|
|
- **`bin/dotsync`** does this safely: `git pull`, then re-link via `install.sh` **only if** the pull
|
|
added/removed/renamed files (pure edits skip the re-stow). `dotsync -n` previews incoming changes.
|
|
- **`install.sh` is a (re)deploy tool, not a sync tool** — its `stow -R` deletes+recreates every
|
|
symlink, which is what makes apps reload. Only needed for the initial link or when files are
|
|
added/removed.
|
|
- **Never `stow` the repo root** (`stow .dots`, `stow */`) — it folds package dirs into `~` as stray
|
|
`~/common`, `~/gui`, … symlinks. `install.sh` only ever links package *contents*.
|
|
- **New host:** create a top-level `<name>/` package (at least a `host.fish`), commit, then
|
|
`./install.sh`. If it's terminal-only, skip the package and just `touch ~/.config/dots-headless`
|
|
(it runs `common` only).
|
|
|
|
## Tooling (`bin/`)
|
|
|
|
| Command | What it does |
|
|
|---|---|
|
|
| `./install.sh [host]` | Deploy `common → gui → <host>`. Flags: `-n` dry-run, `-a` adopt (first run), `-D`/`--unstow` revert (remove this host's symlinks; repo + real files kept), `-h` help. Self-heals: headless hosts get any stray `gui` unstowed; fails loudly (exit 1) if a package couldn't stow. |
|
|
| `./bin/dotsync [-n]` | Sync with least churn: `git pull`, re-stow only if files were added/removed. |
|
|
| `./bin/reconcile-hyde.sh [-i\|--relink] [host]` | After a HyDE update overwrote `~/.config/hypr`, reconcile HyDE's new files against your dots versions (report / `-i` keep·take·merge each / `--relink` re-symlink). |
|
|
|
|
## How per-host differences are expressed
|
|
|
|
| Difference | Mechanism |
|
|
|---|---|
|
|
| Monitors | `<h>/.config/hypr/monitors.conf` (sourced by the shared `hyprland.conf`) |
|
|
| NVIDIA | `wm/.config/hypr/nvidia.conf`, pulled in by wm's `host.conf` (fl/lw have no NVIDIA) |
|
|
| Shell aliases | shared `config.fish` sources `~/.config/fish/host.fish` (per host) |
|
|
| Bash extras | shared `.bashrc` sources `~/.bashrc.host` (optional, per host) |
|
|
| fl's Hyprland | overrides ~9 hypr files (`hyprland.conf`, keybinds, windowrules, theme colors, monitors); inherits the rest from `gui` |
|
|
| Unique apps | in the owning host overlay (fl: llamacpp/evremap; lw: xremap) |
|
|
|
|
`aichat`, `pi`, and `opencode` are **single shared configs** in `common` (LAN-first, with the cloud
|
|
provider also listed so any host can switch) — no per-host overrides.
|
|
|
|
## HyDE dependency (important for GUI hosts)
|
|
|
|
The Hyprland config is [HyDE](https://github.com/HyDE-Project/HyDE)-based. `gui/.config/hypr/*` is
|
|
your customization layer, but it **sources HyDE's framework**:
|
|
`source = ~/.local/share/hyde/hyprland.conf` — which defines `$mainMod` and other variables and is
|
|
**not tracked by dots** (HyDE generates it). So a GUI host must have **HyDE installed**, or Hyprland
|
|
fails to start (`source globbing error` + `invalid mod $mainMod`).
|
|
|
|
- Install/update HyDE with its own installer (`~/HyDE/Scripts/install.sh`); it also pulls the
|
|
required apps (`xdg-desktop-portal-hyprland`, `xdg-desktop-portal-gtk`, `hyprpolkitagent`).
|
|
- HyDE's `-r`/restore overwrites `~/.config/hypr` — use **`bin/reconcile-hyde.sh`** afterward to fold
|
|
its new defaults back against your dots configs.
|
|
- **Wallpapers and generated themes are HyDE-owned, never in dots** (`**/hyde/themes/` and
|
|
`**/wallpapers/` are gitignored — they once bloated a source repo to 255 MB). A fresh machine gets
|
|
them from HyDE, not from this repo.
|
|
|
|
## Waybar (two worlds: HyDE-generated vs the standalone rig)
|
|
|
|
**HyDE owns `~/.config/waybar/config.jsonc` AND `style.css`** — its `waybar.py` *writes* both on
|
|
any `--set`/`--update`, **through the stow symlinks, i.e. into this repo's checkout**. So dots
|
|
track neither. HyDE-managed customization goes via:
|
|
|
|
- `gui/.config/waybar/layouts/*.jsonc` — dots-tracked layouts; switch with `hyde-shell waybar --set <name>`.
|
|
- `gui/.config/waybar/modules/*.jsonc` — module defs, globbed into the generated config.
|
|
|
|
**The custom cava rig is NOT HyDE-managed**: `layouts/custom.jsonc` + `layouts/custom.css` form a
|
|
self-contained two-bar config launched raw (`waybar -c …custom.jsonc -s …custom.css` — exec-once,
|
|
the Ctrl+Alt+W / Super+Shift+R binds, and the `wbar` abbr). **Never route it through
|
|
`hyde-shell waybar --set`** — waybar.py would clobber the repo's files as above. HyDE only reads
|
|
from `layouts/`, which is what makes them safe to track. On a rig host, HyDE's own bar (systemd
|
|
user unit `hyde-<XDG_SESSION_DESKTOP>-bar.service`, auto-restarting) must be disabled once:
|
|
`systemctl --user stop <unit>; systemctl --user mask <unit>`.
|
|
|
|
Note: the Arch `waybar` build has **no native `cava`** module — the rig uses the script module
|
|
`custom/cava` running `cava-waybar.sh` (self-contained, no HyDE dependency).
|
|
|
|
## Secrets
|
|
|
|
Never committed. Put `DUSKADIY_API_KEY` etc. in `~/.config/fish/conf.d/secrets.fish` (gitignored).
|
|
`pi`'s `auth.json` is **not** tracked — it only ever holds `$VAR` references, but pi's `/login`
|
|
rewrites it with the literal key, so one stray `/login` would commit a real token. A new host
|
|
bootstraps it with `cp common/.pi/agent/auth.json.example common/.pi/agent/auth.json`, then
|
|
`./install.sh`. Also gitignored: `fish_variables`,
|
|
`greet.txt`, pi agent runtime/state, `tmux/plugins/`, `.claude/` (Claude Code project dir/worktrees),
|
|
`*.bak`/`*.log`.
|
|
|
|
## Merge notes (history — the one-time unification)
|
|
|
|
The four former per-machine repos had drifted; the merge made some judgment calls:
|
|
|
|
- **`config.fish` / `.bashrc`** were hand-reconciled into a neutral shared base + per-host
|
|
`host.fish` / `.bashrc.host` (removed a committed `fnm_multishells` runtime PATH, stray
|
|
absolute home-dir paths, duplicate git aliases).
|
|
- **`pi` lives at `~/.pi`** (repo `.pi/`); **`tmux` at `~/.config/tmux/`** (delete a legacy
|
|
`~/.tmux.conf` if present after migrating).
|
|
- **Appearance drift was unified to one canonical** (mostly wm): bat, btop, cava, fastfetch, lazygit,
|
|
mpv, pyradio, waybar, zellij, most of nvim.
|
|
- **nvim** is shared entirely (no host overrides); plugin set / `lazy-lock.json` are shared — run
|
|
`:Lazy restore` per machine once (obeys the lockfile pins — `:Lazy update` on one machine +
|
|
commit is how versions move forward; other machines converge with `restore`).
|
|
- **`zellij`** is one shared config with **vim keybinds** (h/j/k/l) + the `guvbox-dark` theme.
|
|
- **`misc/{clis,tuis}.txt`** launcher inventories use wm's lists in `common`; a machine needing its
|
|
own can override in its overlay.
|
|
|
|
## Third-party content and licensing
|
|
|
|
The repo is GPL-3.0 (`LICENSE`). What that does and doesn't cover:
|
|
|
|
- **`hypr/`, `waybar/` and the other desktop configs are derived from
|
|
[HyDE](https://github.com/HyDE-Project/HyDE)** (and, further back, legacy Hyprdots). HyDE is
|
|
itself GPL-3.0, so the derivation and this repo's licence agree — no conflict, and the
|
|
Hyprdots-era ASCII banners in those files are left in place as attribution.
|
|
- **`common/.config/aichat/dark.tmTheme`** is *One Half Dark* by Son A. Pham, **MIT**. The
|
|
licence header at the top of that file is the attribution — don't strip it.
|
|
- **`common/.config/fastfetch/pngs/`** holds project and distro marks (Arch, the Open Source
|
|
Initiative and Open Source Hardware logos, …). Trademarks aren't relicensable, so GPL-3 does
|
|
not extend to them; they are bundled as nominative use, the way most dotfiles repos do.
|
|
- **`gui/.config/hypr/hyprlock/assets/`** — the lock screen background and logo. EXIF is
|
|
stripped, so the files carry no provenance; confirm these are yours to redistribute before
|
|
publishing, or swap them for something you know the origin of.
|