Felipe M.
2f58f33510
Adds docs/config/{metapac,git}.md and docs/dotfiles-command.md covering the
reasoning that is not recoverable from the files themselves: why every host
needs a baseline group and what happens without one, why signing is SSH rather
than GPG and why the block is gated on the signer binary existing, why `update`
only ever fast-forwards and `apply` never removes packages.
AGENTS.md records the rule these were written to. docs/ is for decisions and
traps, not inventories: if the reader could recover it from the tree or the file,
it does not belong. Worth persisting are the reasons a reasonable person would
have chosen otherwise, constraints that bite silently, formulas encoding a
judgement, requirements, and rarely-run procedures where the vendor's own
instructions are wrong for this setup. Not worth persisting are file listings,
restatements of self-describing keys, what is not managed, cosmetic detail, and
narration of readable code.
Rewrote docs/config/claude.md against that rule -- 123 lines to 52 -- and
trimmed the README's layout block to the paths that are not self-evident, which
was the same mistake one level up. Sections that moved into docs/ are gone from
the README rather than duplicated.
Verified every relative link resolves, and that docs/ and AGENTS.md sit outside
.chezmoiroot so they are never applied to $HOME.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1.2 KiB
The dotfiles command
dotfiles update |
fetch and fast-forward the repo |
dotfiles apply |
update, chezmoi apply, then metapac sync |
dotfiles chezmoi ... |
passthrough |
dotfiles metapac ... |
passthrough |
Deliberate constraints
apply refuses to run with uncommitted changes, and checks before touching
anything — so a half-applied state cannot come from a dirty tree.
update fast-forwards only. git merge --ff-only after an explicit fetch,
never a plain pull, so a diverged branch is reported rather than silently merged
or rebased into a state nobody asked for.
apply never removes packages. metapac sync installs what is missing;
clean uninstalls what is not declared, which is destructive enough to stay an
explicit dotfiles metapac clean. See config/metapac.md for
why that command deserves respect.
Why the script is wrapped in a brace group
dotfiles apply runs chezmoi apply, which can rewrite this very script while it
is executing. Bash reads scripts incrementally by byte offset, so a file that
changes size underneath it can resume parsing at garbage. The braces force a full
parse before anything runs.