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>
29 lines
1.2 KiB
Markdown
29 lines
1.2 KiB
Markdown
# 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](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.
|