Better chezmoi
Reference evidence: official chezmoi docs and release v2.74.0 (releases, published 2026-11-01), checked 2026-11-10; the bundled docs snapshot was refreshed the same day. Command surface exercised on chezmoi v2.74.0 (Linux, 2026-11-10) and earlier on v2.70.2 (macOS). The installed binary owns executable syntax: run chezmoi --version and chezmoi <command> --help before using a flag that may be newer than the binary.
Authority
A request to add, edit, apply, update, merge or remove a named target authorizes that scoped effect only. It does not authorize applying every target, enabling git.autoPush, pushing, rewriting remote history, exposing secrets, or destroying source and target state. Scope commands to the named targets, and preview before any target write unless the user asked for immediate application.
On Windows, give PowerShell-native forms; do not offer POSIX arrays, $(...) or mktemp.
Default loop
Capture the version and chezmoi source-path, then edit source state (chezmoi edit), preview, apply, verify:
chezmoi diff --exclude=scripts --no-pager [target...]
chezmoi apply --dry-run --verbose --exclude=scripts [target...]
chezmoi apply --exclude=scripts [target...]
chezmoi verify --exclude=scripts [target...]
--exclude=scripts keeps scripts out of the preview; account for them separately. Report the version, scope, commands run, and any remaining drift.
What the previews do not guarantee
--dry-runonly guarantees the destination is untouched.initcan still create source Git state, hooks run even in dry-run, and templates or externals can reach the network or a password manager.edit --applyandedit --watchapply on every save; use them only when the user wants that.diffexits 0 even when it shows differences, and its--outputdid not redirect on v2.70.2 or v2.74.0.verifyexits 0 on match and 1 on mismatch; use it for drift checks.statushas two columns: actual vs last-written state, and actual vs desired state (whatapplywould do);A D M Rare add, delete, modify, run.--error-on-conflict(fail closed instead of prompting) andinit --revision/--tagarrived in v2.71.0, and docs use-wfor--working-treewhere the v2.70.2 and v2.74.0 binaries show-W. On an older binary, stop or upgrade; never substitute--forcefor conflict handling.
Gotchas
updatepulls and applies; it is not a preview. For review first:chezmoi update --apply=false, orchezmoi git pull -- --autostash --rebasethendiff. Either changes the local source repository and uses the network.re-adddoes not update templated sources. For a template, edit it or usemerge.- Source wins: scoped
apply. Destination wins (non-template):re-add. Both have changes:merge TARGETormerge-all. --source-pathreinterprets target arguments as source paths, and relative ones resolve from the current directory; pass absolute paths.managed --format=jsoncan still emit newline-separated paths; v2.70.2 and v2.74.0 needed--path-style=allfor the keyed structure.- A template that renders empty removes its target unless the source has the
empty_attribute. chezmoi cdopens a child shell. Usecd "$(chezmoi source-path)"to move the caller.initwith--applyis a bootstrap. One-shot mode removes chezmoi's own source and config afterward; say so before using it.
Templates and machine differences
Source files ending .tmpl (or under .chezmoitemplates/) are templates. Data merges in order: built-in .chezmoi, .chezmoidata files, then config data, later overriding earlier. Keep portable defaults in source data and machine-specific values (email, role) in the local config. Prefer .chezmoi.os/.chezmoi.arch or named config data over hostname tests. Select targets per machine with a templated .chezmoiignore, checked with chezmoi ignored and chezmoi diff.
Test with chezmoi data --format=yaml, chezmoi execute-template '{{ .chezmoi.os }}', then chezmoi cat TARGET; preview each machine class affected. add --autotemplate substitutes greedily, so treat it as a draft.
Secrets
Plaintext secrets never go into source history or output. Use chezmoi add --secrets=error TARGET when capturing files, then route the value to a password-manager template function, encrypted source (add --encrypt, only after recipient keys and recovery are verified), or untracked local config. chezmoi edit decrypts transparently; keep its temporary plaintext out of logs.
Scripts and locks
run_runs every apply;run_onchange_when rendered content changes;run_once_once per unique content;before_/after_set the phase, alphabetical within it. Keep scripts idempotent. A template script's#!must be at byte zero. A failedrun_once_/run_onchange_can run again.- Never call chezmoi from a
run_script: persistent-state locks make the nested call time out. - Write-lock commands: add, apply, edit, forget, import, init, state, unmanage, update. diff, status and verify take read locks. On a lock timeout, find the other chezmoi process or nested call and wait for or stop that owner. Delete the persistent-state database only with official guidance and a backup.
Removal
forget/unmanage stop managing a target and leave it on disk. destroy deletes source and target permanently; purge removes chezmoi config, state and source. Never infer destroy from "stop managing"; use it only with exact targets, an independent backup and explicit confirmation. For .chezmoiremove patterns, dry-run verbosely and inspect each match.
Official docs
references/official-docs/ is a searchable snapshot of selected chezmoi.io pages (index in manifest.json):
python3 scripts/official_docs.py search "persistent state lock" --limit 20
python3 scripts/official_docs.py refresh
refresh fetches and compares without replacing the snapshot and reports added, changed, removed and unchanged pages. refresh --write replaces the snapshot with a validated copy; run it only when the user has authorized updating the corpus, then python3 scripts/official_docs.py check. For an ad hoc refresh elsewhere, use --output with a scratch directory and search it with --docs. A network failure is not evidence the snapshot is current. The DOCUMENT_SOURCES tuple in the script owns the page list; add a page only when a real task needs it.
