Skip to content

chezmoi

chezmoi copies the dotfiles/ directory of the repository into ~, renaming files by convention and rendering the few that are templates.

PathPurpose
~/.local/share/chezmoithe git clone; .chezmoiroot points chezmoi at dotfiles/
~/.config/chezmoi/chezmoi.yamlrendered from .chezmoi.yaml.tmpl; age settings and editor
~/.config/chezmoi/key.txtthe age identity, decrypted once per machine
Prefix or suffixEffect
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
.tmplrender as a Go template before writing
.agedecrypt with the age identity

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: age
age:
identity: ~/.config/chezmoi/key.txt
recipient: "age1…"
suffix: .age
diff:
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.

ScriptWhenDoes
run_once_before_decrypt-age-keyfirst apply on a machinedecrypts key.txt.age with a passphrase prompt
run_onchange_after_brew-bundlewhenever the Brewfile’s hash changesinstalls Homebrew if needed, then brew bundle install
run_onchange_after_link-skillsgh sign-in, the skills checkout, or its skill list changesclones kiliantyler/skills if missing, links its skills into ~/.claude/skills, ~/.codex/skills, ~/.agents/skills
run_once_after_set-login-shellfirst apply, after bash existsadds Homebrew bash to /etc/shells, chsh, launchctl setenv SHELL

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.

Terminal window
chezmoi status # what differs between repo and ~
chezmoi diff # the actual diff
chezmoi apply # write ~ from the repo
chezmoi re-add <file> # pull a changed ~ file back into the repo
chezmoi cd # shell in the clone to commit

Agents commit the clone directly. Nothing auto-commits or auto-pushes.