diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 62 |
1 files changed, 62 insertions, 0 deletions
@@ -34,3 +34,65 @@ launches `create-efi`. chezmoi init --source ~/dotfiles chezmoi apply -v ``` + +## Layout + +Everything is driven by [just](https://just.systems/) recipes against four parallel models: + +| Directory | Managed by | Purpose | +| ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `dot_*`, `private_dot_*` | chezmoi | Dotfiles deployed to `$HOME`. Prefixes: `dot_` → `.`, `private_` → `0600`, `executable_` → `+x`. | +| `meta/*.txt` | `just install`, `just pkg-drift` | Plain-text package lists (one per line, `#` comments). Groups: `base`, `dev`, `wayland`, etc. | +| `systemd-units/*.txt` | `just services-enable`, `just services-drift` | Units to enable, paired by name with a `meta/` group (`base.txt` ↔ `base.txt`). | +| `etc/` | `run_onchange_after_deploy-etc.sh.tmpl` | System-level configs deployed to `/etc/` via a chezmoi onchange hook. | +| `firefox/` | `run_onchange_after_deploy-firefox.sh.tmpl` | LibreWolf `user-overrides.js` + `userChrome.css` (kept under the familiar `firefox/` name). | + +## Recipes at a glance + +Run `just` or `just --list` for the full menu. Main recipes: + +| Category | Recipe | Effect | +| ------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| Setup | `just init` | First-time machine setup: chezmoi init, git hooks, apply, base group, services | +| Day-to-day | `just sync` | `apply` + `fix` (deploy dotfiles + top up partially-installed groups) | +| | `just apply` | `chezmoi apply` | +| | `just readd` | Pull live changes back into the repo (chezmoi re-add + `etc-readd`) | +| Packages | `just install GROUP [GROUP...]` | Install the listed `meta/*.txt` groups | +| | `just install-all` | Install every group | +| | `just add GROUP PKG`, `just remove GROUP PKG` | Edit a group list and install/remove | +| Services | `just services-enable` | Enable every unit in the enabled-group `systemd-units/*.txt` lists | +| /etc | `just etc-diff`, `just etc-readd`, `just etc-restore`, `just etc-untrack` | See /etc workflow below | +| Inspection | `just status` | Combined dotfile + package + /etc + service drift | +| | `just doctor` | Verify tooling for `just check` is installed | +| Quality gates | `just fmt [PATH]`, `just check-fmt [PATH]` | Format / check formatting (all languages below) | +| | `just lint [PATH]` | Run linters (selene, shellcheck, ruff, taplo) | +| | `just check [PATH]` | `check-fmt` + `lint` (the pre-commit hook and CI both run this) | + +`fmt` / `check-fmt` / `lint` cover: Lua (stylua, selene), shell (shfmt, shellcheck), Python (ruff), TOML (taplo), justfile (`just --fmt`), plus Markdown/JSON/YAML/CSS (prettier). Each accepts either no argument (whole repo) or a single file path. + +## Drift workflow + +Four sources of drift are tracked independently and combined by `just status`: + +- **Dotfiles** (`chezmoi status`): live `$HOME` files differ from the repo. Resolve with `just apply` (repo → home), `just readd` (home → repo), `just diff`, or `just merge PATH`. +- **Packages** (`just pkg-drift`): installed but undeclared, or declared but missing. Resolve by adding to a `meta/` group (`just add GROUP PKG`) or by uninstalling. +- **/etc** (`just etc` / `just etc-diff`): installed package configs or user-created files in `/etc` that aren't in the repo. Resolve with `just etc-readd PATH` (track), `just etc-restore PATH` (revert to package default), or `just etc-untrack PATH`. +- **Services** (`just services-drift`): enabled units not in any `systemd-units/*.txt`, or declared units that aren't enabled. + +## Git hooks + +Activated by `just init` via `git config core.hooksPath .githooks`: + +- `pre-commit` → `just check`. Blocks commits that fail formatting or linting. Bypass with `git commit --no-verify`. +- `post-commit` → `chezmoi apply`. Keeps `$HOME` in sync whenever a tracked file changes in the repo. + +## Disaster recovery + +The repo is enough to rebuild a machine's tooling and configuration, but not its **state** — back these up externally: + +- GPG master key and subkeys (`gpg --export-secret-keys`, `gpg --export-ownertrust`). The agent also handles SSH auth, so this restores both. +- `~/.password-store/` — the `pass` store that feeds API keys/tokens into the shell at login. +- SSH private keys under `~/.ssh/id_*` (only `.pub` / config is in the repo). +- LibreWolf profile data (bookmarks, history, extension state) — only the hardening policy lives in `firefox/`. + +Recovery on a fresh install: run `bootstrap.sh`, then `gpg --import` + `pass init <KEYID>`, restore `~/.password-store/`, drop SSH private keys into `~/.ssh/`, and restore the LibreWolf profile. |