| name | dotfiles |
| description | Conventions for working with the user's personal dotfiles repo at ~/.dotfiles. Use when modifying tracked config files (anything mapped in ~/.dotfiles/dotfiles.json) or when the user mentions "dotfiles". |
Dotfiles
Personal dotfiles repo at ~/.dotfiles, managed by the dotfiles-cli tool (dotfiles on $PATH).
For commands and flags, run dotfiles --help (and dotfiles <command> --help) — it's self-describing. Add --json to any command for machine-readable output.
Mapping
~/.dotfiles/dotfiles.json maps source paths in $HOME to mirrored paths under ~/.dotfiles/config/<tool>/. Entries are files or directories (trailing / = directory, tracked recursively). Adding a file inside an already-mapped directory needs no manifest change — just save.
Workflow when editing a tracked file
- Edit the live file in
$HOME (not the copy under ~/.dotfiles/config/).
dotfiles status — confirm drift.dotfiles save — local → repo. Prefer scoping with --tool / --file (see dotfiles save --help) to avoid touching unrelated drift.- In
~/.dotfiles, branch and make an atomic commit.
The reverse direction (repo → live) is dotfiles install.
Conventions (not in --help)
- Atomic commits, never
git add -A. An unscoped save syncs every drifted tracked file, so git status may surface unrelated changes the user made earlier. Stage only the files for the current logical change — one change per commit.
- If
install vs save direction is ambiguous (unexpected drift, possible data loss), ask the user which side is authoritative.
- No commit attribution. No
Co-authored-by, no agent signatures.
