chezmoi
chezmoi copies the dotfiles/ directory of the repository into ~, renaming files by convention and rendering the few that are templates.
Where things are
Section titled “Where things are”| Path | Purpose |
|---|---|
~/.local/share/chezmoi | the git clone; .chezmoiroot points chezmoi at dotfiles/ |
~/.config/chezmoi/chezmoi.yaml | rendered from .chezmoi.yaml.tmpl; age settings and editor |
~/.config/chezmoi/key.txt | the age identity, decrypted once per machine |
Naming
Section titled “Naming”| Prefix or suffix | Effect |
|---|---|
dot_ | leading dot in the target name |
private_ | mode 600 for files, 700 for directories |
executable_ | mode +x |
empty_ | create the file even when it is empty |
.tmpl | render as a Go template before writing |
.age | decrypt with the age identity |
Templates
Section titled “Templates”Templates use two values: .chezmoi.homeDir and .isWork, which is true when the hostname matches ^L\d+-. Work machines get extra encrypted files and a reduced Brewfile; there is no OS branching.
encryption: ageage: identity: ~/.config/chezmoi/key.txt recipient: "age1…" suffix: .agediff: exclude: [scripts]edit: command: code args: ["--wait"]Template functions that call a password manager (onepasswordRead and friends) are banned. They run on every chezmoi status and chezmoi diff, which turns a read-only command into an approval prompt.
Scripts
Section titled “Scripts”| Script | When | Does |
|---|---|---|
run_once_before_decrypt-age-key | first apply on a machine | decrypts key.txt.age with a passphrase prompt |
run_onchange_after_brew-bundle | whenever the Brewfile’s hash changes | installs Homebrew if needed, then brew bundle install |
run_onchange_after_link-skills | gh sign-in, the skills checkout, or its skill list changes | clones kiliantyler/skills if missing, links its skills into ~/.claude/skills, ~/.codex/skills, ~/.agents/skills |
run_once_after_set-login-shell | first apply, after bash exists | adds Homebrew bash to /etc/shells, chsh, launchctl setenv SHELL |
Removed targets
Section titled “Removed targets”To retire a managed file, delete its source and list the target path in dotfiles/.chezmoiremove; chezmoi deletes it on the next apply. Once every machine has applied, delete the entry, and the file when it is empty. That is how the fish, zsh, starship, and Karabiner configs left.
Day to day
Section titled “Day to day”chezmoi status # what differs between repo and ~chezmoi diff # the actual diffchezmoi apply # write ~ from the repochezmoi re-add <file> # pull a changed ~ file back into the repochezmoi cd # shell in the clone to commitAgents commit the clone directly. Nothing auto-commits or auto-pushes.