Your home directory,
declared once.

1 · Mental model: a compiler for your home directory

chezmoi is not a smarter symlink farm. It is a build system whose input is a versioned source directory, whose build step merges templates with machine-specific data, and whose output is real files in your home directory. Once you see apply as compilation, every command falls into place.

Three states exist at all times, and every chezmoi command is a movement between them:

• The source state — what your dotfiles repo declares. Lives in ~/.local/share/chezmoi as a git repository.
• The target state — the desired result, computed by rendering templates with your machine's data. It exists only in memory.
• The destination state — what is actually sitting in ~ right now.

The wrong question: "which dotfiles manager is best?"

The right question is what problem you actually have. If your dotfiles are identical everywhere and contain no secrets, a bare git repo works. The moment you have two machines that differ, or one secret, the comparison changes:

Recommendation: you already track machine-specific differences (a Mac and, sooner or later, a Linux box), and you want KeePassXC-backed secrets. That is exactly chezmoi's home territory. Commit to it fully — a half-adopted chezmoi (your current state) gives you the concept overhead with none of the payoff.

Sources: chezmoi design FAQ · why use chezmoi

2 · Prerequisite floor

chezmoi leans on three things you mostly have already. Check yourself honestly — gaps here surface later as mysterious template errors and git confusion, not as clear failures.

Self-assessment

• Can you explain what git status vs git diff shows? (If not: any git primer before §8.)
• Do you know why ~/.netrc should be mode 600 while ~/.zshrc need not be?
• Can you predict what ls -l shows for a symlink?
• Have you used mktemp -d? (Labs use it constantly to stay disposable.)

Three or more boxes checked: proceed. Fewer: still proceed — the labs are sandboxed so mistakes are free — but expect to look things up.

3 · Install, verify, and build a safe sandbox

One habit carries this entire guide: chezmoi accepts --source and --destination flags, so you can run a complete, fully isolated chezmoi playground in a throwaway directory. Your real dotfiles never enter the picture until you decide they should.

brew install chezmoi
chezmoi --version
chezmoi version v2.72.0, commit Homebrew, built at 2026-08-02T18:45:49Z, built by Homebrew

On a machine without Homebrew, the official one-liner installs the latest binary (and §8 shows the variant that bootstraps your whole setup in the same breath):

sh -c "$(curl -fsLS https://get.chezmoi.io)"

LAB=$(mktemp -d /tmp/chezmoi-lab.XXXX)
mkdir -p $LAB/src $LAB/home $LAB/cfg
cat > $LAB/cz <<EOF
#!/bin/sh
exec chezmoi --source $LAB/src --destination $LAB/home --config $LAB/cfg/chezmoi.toml "\$@"
EOF
chmod +x $LAB/cz
$LAB/cz init
ls -la $LAB/src
drwxr-xr-x  .git        # init created an empty git repo — that IS the source state

Sources: install · command-line flags

4 · State-flow simulator

Before touching more commands, internalize the loop. This simulator models two files across the source and destination states. Click commands; watch versions converge and diverge. Simplified on purpose: real chezmoi tracks a third record — the last state it wrote — which is how status tells "you edited the source" ( M) from "someone edited the real file too" (MM). The simulator models that as well.

• Press edit then status:  M .zshrc — source moved ahead, destination stale.
• Press apply: versions converge, status goes clean.
• Press vim by hand then status: MM would appear only after the source also moves — try edit too, then decide: apply (source wins) or re-add (your hand edit wins). That decision is the whole daily discipline.

5 · Adopt your dotfiles: the daily loop

Four commands are the whole daily workflow: add to bring a file under management, edit to change it, diff to preview, apply to converge. Everything else is refinement.

Your CLI instincts, translated

# A fake dotfile in the sandbox "home"
printf 'export EDITOR=vim\nalias ll="ls -la"\n' > $LAB/home/.zshrc
$LAB/cz add $LAB/home/.zshrc
ls $LAB/src
dot_zshrc                # leading dot became the dot_ prefix
$LAB/cz managed
.zshrc

printf 'export EDITOR=nvim\nalias ll="ls -la"\n' > $LAB/src/dot_zshrc
$LAB/cz status
 M .zshrc
$LAB/cz diff
--- a/.zshrc
+++ b/.zshrc
@@ -1,2 +1,2 @@
-export EDITOR=vim
+export EDITOR=nvim
 alias ll="ls -la"
$LAB/cz apply -v
cat $LAB/home/.zshrc
export EDITOR=nvim
alias ll="ls -la"

The edit ergonomics you will actually use

• chezmoi edit ~/.zshrc — edit the source copy; apply separately.
• chezmoi edit --apply ~/.zshrc — apply automatically when you quit the editor. Recommended default.
• chezmoi edit --watch ~/.zshrc — apply on every save. Closest to editing the live file.
• chezmoi cd — open a subshell in the source directory for git work or bulk edits. Exit returns you home.
• chezmoi forget ~/.hushlogin — stop managing a file (source entry removed, real file left in place). chezmoi destroy deletes both — almost never what you want.

Sources: daily operations · command overview

6 · The attribute grammar: filenames as declarations

chezmoi stores metadata where git can version it: in the filename. private_dot_netrc is not a naming convention — it is a small declarative language. Read the prefixes off and you know the target path, permissions, and type without opening the file.

Change attributes with chezmoi chattr rather than renaming by hand — it renames the source file for you and understands stacking order:

$LAB/cz chattr private $LAB/home/.zshrc     # dot_zshrc → private_dot_zshrc
$LAB/cz chattr noprivate $LAB/home/.zshrc   # and back
$LAB/cz chattr +template $LAB/home/.gitconfig  # append .tmpl

printf 'secret-ish config\n' > $LAB/src/private_dot_netrc
$LAB/cz apply -v
diff --git a/.netrc b/.netrc
new file mode 100600          # ← private_ became 600 before your eyes
ls -l $LAB/home/.netrc
-rw-------  .netrc

# A create_ file: applied once, then hands off
printf 'default content\n' > $LAB/src/create_dot_hushlogin
$LAB/cz apply
echo "edited-by-user" > $LAB/home/.hushlogin
$LAB/cz apply && cat $LAB/home/.hushlogin
edited-by-user                # create_ never clobbers an existing file

Sources: source state attributes · chattr

7 · Templates & machine differences

Templates are why chezmoi beats copying files around: one source file, many rendered results. The engine is Go's text/template; the data is a merged dictionary you can inspect at any time with chezmoi data.

Where data comes from (all merged)

• Built-ins — .chezmoi.os ("darwin"/"linux"), .chezmoi.arch, .chezmoi.hostname, .chezmoi.homeDir, and friends.
• Your config file — ~/.config/chezmoi/chezmoi.toml, [data] section. Per-machine, not in the repo. This is the escape hatch for anything machine-specific.
• .chezmoidata.toml (or .yaml/.json) in the source root — shared data, versioned in the repo.
• Secret functions — keepassxc and friends fetch at render time (§10).

# dot_gitconfig.tmpl — one file, correct on every machine
[user]
    email = {{ .email }}
[core]
    editor = {{ if eq .chezmoi.os "darwin" }}nvim{{ else }}vim{{ end }}

cat > $LAB/cfg/chezmoi.toml <<'EOF'
[data]
  email = "you@example.com"
  machine = "sandbox"
EOF
cat > $LAB/src/.chezmoidata.toml <<'EOF'
[colors]
  theme = "cobalt"
EOF
# write dot_gitconfig.tmpl as above, plus one line using .machine and .colors.theme
$LAB/cz data --format json | head    # the merged dictionary, truthfully
$LAB/cz cat $LAB/home/.gitconfig       # render target state WITHOUT applying
[user]
    email = you@example.com
[core]
    editor = nvim
$LAB/cz execute-template '{{ .chezmoi.os }}/{{ .chezmoi.arch }}'
darwin/amd64

cat > $LAB/src/.chezmoiignore <<'EOF'
{{ if ne .chezmoi.os "linux" }}
.config/systemd
{{ end }}
EOF
mkdir -p $LAB/src/dot_config/systemd
printf 'linux only\n' > $LAB/src/dot_config/systemd/unit.conf
$LAB/cz apply
ls $LAB/home/.config
                              # empty on darwin — systemd/ was ignored

Patterns that scale

• Small differences → inline {{ if }} blocks in one template.
• Whole-file differences → {{ if eq .chezmoi.os "darwin" }}{{ include ".zshrc_darwin" }}{{ end }}, or ignore the file entirely per machine in .chezmoiignore.
• Shared blocks → put fragments in .chezmoitemplates/ and pull them in with {{ template "fragment" . }}.
• Machine identity → prefer a work = true/false flag in each machine's config [data] over hostname string-matching; hostnames change, roles don't.

Sources: machine-to-machine differences · templating · template variables

8 · The git layer and multi-machine sync

chezmoi does not reinvent sync. The source directory is a git repo; GitHub (or any remote) is the transport; chezmoi update is git pull --autostash --rebase followed by apply. If you can push and pull, you can sync machines.

Publishing (machine A, once)

chezmoi cd                       # subshell inside the source repo
git remote add origin git@github.com:$GITHUB_USERNAME/dotfiles.git
git push -u origin main
exit

Dotfiles with secrets-via-KeePassXC contain no secret material (§10), but a private repo is still the sane default — your shell history habits, hostnames, and internal paths are nobody's business.

Bootstrapping (machine B, any time)

# chezmoi already installed:
chezmoi init --apply $GITHUB_USERNAME          # expands to your dotfiles repo

# bare metal — install AND converge in one line:
sh -c "$(curl -fsLS https://get.chezmoi.io)" -- init --apply $GITHUB_USERNAME

Ask once per machine: .chezmoi.toml.tmpl

A file named .chezmoi.toml.tmpl in the source root is special: chezmoi init renders it to create the machine's config file. Prompt functions make bootstrap interactive exactly once:

# .chezmoi.toml.tmpl (in the repo)
{{ $email := promptString "email" -}}
{{ $work := promptBool "is this a work machine" -}}
[data]
  email = {{ $email | quote }}
  work = {{ $work }}

# Publish machine A (your Lab 1-4 sandbox)
cd $LAB/src
git add -A && git commit -m "dotfiles v1"
git init --bare $LAB/origin.git
git remote add origin $LAB/origin.git && git push origin HEAD:main

# "Machine B": fresh source + home + config
mkdir -p $LAB/home2 $LAB/cfg2
chezmoi --source $LAB/src2 --destination $LAB/home2 \
        --config $LAB/cfg2/chezmoi.toml init $LAB/origin.git
Cloning into '…/src2'... done.
# give machine B its own data, then converge
printf '[data]\n  email = "you@example.com"\n  machine = "machine2"\n' > $LAB/cfg2/chezmoi.toml
chezmoi --source $LAB/src2 --destination $LAB/home2 --config $LAB/cfg2/chezmoi.toml apply
[script] installing packages (runs once)     # scripts fire fresh per machine (§9)
ls -A $LAB/home2
.config .gitconfig .local .netrc .theme.conf .zshrc

# A: change, commit, push
printf 'alias reload="exec zsh"\n' >> $LAB/src/dot_zshrc
cd $LAB/src && git commit -am "add reload alias" && git push origin HEAD:main

# B: one command pulls AND applies
chezmoi --source $LAB/src2 --destination $LAB/home2 --config $LAB/cfg2/chezmoi.toml update -v
Fast-forward  dot_zshrc | 1 +
+alias reload="exec zsh"

Frictionless commits

If committing every tweak feels like ceremony, let chezmoi do it:

# in your config file
[git]
    autoCommit = true     # commit after each source change
    autoPush = true       # …and push (implies autoCommit)

Recommendation: autoCommit yes, autoPush no. Auto-generated commit messages are a fair price for never forgetting to commit; auto-push removes your last review point before other machines can pull a mistake.

Sources: setup · daily operations · .chezmoi.$FORMAT.tmpl

9 · Scripts & automation: the run_ family

Dotfiles describe files; machines also need actions — install packages, set macOS defaults, build a font cache. chezmoi models actions as scripts in the source state whose filename declares when they run.

Apply order is fixed and worth memorizing: run_before_ scripts (alphabetical) → files and directories (alphabetical by target name) → run_after_ scripts (alphabetical). Scripts without before/after run in the file pass, interleaved alphabetically.

cat > $LAB/src/run_once_install-packages.sh <<'EOF'
#!/bin/sh
echo "[script] installing packages (runs once)"
EOF
cat > $LAB/src/run_onchange_reload-config.sh.tmpl <<'EOF'
#!/bin/sh
# hash of .gitconfig: {{ include "dot_gitconfig.tmpl" | sha256sum }}
echo "[script] config changed, reloading"
EOF
$LAB/cz apply
[script] installing packages (runs once)
[script] config changed, reloading
$LAB/cz apply
                                  # silence — both satisfied
printf '# comment\n' >> $LAB/src/dot_gitconfig.tmpl
$LAB/cz apply
[script] config changed, reloading   # hash line changed → onchange fired

Real-world script patterns for your goals

# run_onchange_darwin-defaults.sh.tmpl — macOS settings as code
{{ if eq .chezmoi.os "darwin" -}}
#!/bin/sh
defaults write com.apple.dock autohide -bool true
killall Dock
{{ end -}}

# run_onchange_install-packages.sh.tmpl — Brewfile-driven, re-runs when the list changes
{{ if eq .chezmoi.os "darwin" -}}
#!/bin/sh
# Brewfile hash: {{ include "Brewfile" | sha256sum }}
brew bundle --file=- <<'BREWS'
brew "fzf"
brew "lazygit"
brew "age"
BREWS
{{ end -}}

Sources: use scripts to perform actions · application order · state

10 · Secrets: KeePassXC first, age for files

The rule with no exceptions: secret material never enters the git repo. chezmoi offers two clean mechanisms — reference secrets from a password manager at render time, or encrypt whole files in the source. You want both: KeePassXC for values, age for the occasional whole secret file.

KeePassXC: values at render time

chezmoi shells out to keepassxc-cli show and exposes entries to templates. Configure once:

# ~/.config/chezmoi/chezmoi.toml
[keepassxc]
    database = "/Users/you/secrets.kdbx"

# dot_config/private_gh-token.tmpl — the repo stores only this reference
GITHUB_TOKEN={{ (keepassxc "github-token").Password }}
USER={{ (keepassxc "github-token").UserName }}

Three template functions cover the entry surface: keepassxc "title" returns the entry (fields via .UserName, .Password, .URL, .Notes), keepassxcAttribute "title" "attr" reads one attribute (including custom ones), keepassxcAttachment "title" "name" reads a file attachment.

# Throwaway database (key file instead of password → non-interactive labs)
head -c 64 /dev/urandom > $LAB/kdbx-keyfile
keepassxc-cli db-create -k $LAB/kdbx-keyfile $LAB/secrets.kdbx
Successfully created new database.
printf 'ghp_sandboxtoken123\n' | keepassxc-cli add --no-password -k $LAB/kdbx-keyfile \
    -u you -p $LAB/secrets.kdbx github-token
Successfully added entry github-token.

# Wire it into the sandbox config
cat >> $LAB/cfg/chezmoi.toml <<EOF
[keepassxc]
    database = "$LAB/secrets.kdbx"
    args = ["--no-password", "--key-file", "$LAB/kdbx-keyfile"]
    prompt = false
EOF
$LAB/cz execute-template '{{ (keepassxc "github-token").UserName }}'
you

# The private_ + .tmpl combination: rendered secret, 600 perms
mkdir -p $LAB/src/dot_config
printf 'GITHUB_TOKEN={{ (keepassxc "github-token").Password }}\n' \
    > $LAB/src/dot_config/private_gh-token.tmpl
$LAB/cz apply -v
new file mode 100600
+GITHUB_TOKEN=ghp_sandboxtoken123

age: whole encrypted files in the repo

For things that are files — an SSH key, a kubeconfig — encrypt them into the source state. chezmoi bundles age encrypt/decrypt, but not key generation: install the real thing (brew install age, tested v1.3.1) for age-keygen.

age-keygen -o ~/.config/chezmoi/key.txt
Public key: age1uank7kslpm8kerxu2ndalukp7mceu7l4mqmugfls5k5th8fzyp6qmlaa9k

# chezmoi.toml — encryption MUST be top-level, ABOVE any [section]
encryption = "age"

[age]
    identity = "~/.config/chezmoi/key.txt"
    recipient = "age1uank7kslpm8kerxu2ndalukp7mceu7l4mqmugfls5k5th8fzyp6qmlaa9k"

chezmoi add --encrypt ~/.secret-key
ls ~/.local/share/chezmoi
encrypted_dot_secret-key.age
head -1 ~/.local/share/chezmoi/encrypted_dot_secret-key.age
-----BEGIN AGE ENCRYPTED FILE-----
chezmoi cat ~/.secret-key          # decrypts on demand, on the fly

The age identity file is now your recovery keystone: without it, encrypted files in the repo are noise. Store a copy of key.txt in KeePassXC (as an attachment) — the vault guards the key, the key guards the files.

Sources: KeePassXC integration · age encryption · keepassxc template functions

11 · External dependencies: stop vendoring other people's code

Right now your source repo contains a full copy of oh-my-zsh as tracked files. That is vendoring: upstream updates never arrive, and hundreds of files that aren't yours pollute every diff. .chezmoiexternal declares "fetch this from there" instead.

# .chezmoiexternal.toml (in the source root)
[".oh-my-zsh"]
    type = "archive"
    url = "https://github.com/ohmyzsh/ohmyzsh/archive/master.tar.gz"
    exact = true
    stripComponents = 1
    refreshPeriod = "168h"     # re-check upstream weekly

Three types cover practice: file (single file), archive (unpacked tarball/zip), git-repo (cloned/pulled). refreshPeriod controls how often chezmoi re-downloads; between refreshes, applies use the cache and work offline. exact = true keeps the unpacked tree pristine.

Verified in the sandbox with a single-file external:

[".local/share/fzf-license"]
    type = "file"
    url = "https://raw.githubusercontent.com/junegunn/fzf/master/LICENSE"
    refreshPeriod = "168h"
# → chezmoi apply downloaded it; `chezmoi managed` now lists it

Sources: include files from elsewhere · .chezmoiexternal reference

12 · Capstone: finish your real adoption

Everything above was rehearsal. This is the performance: take your stalled real setup — dot_zshrc, dot_zshrc.d, dot_gitconfig, dot_gitignore_global, and a vendored dot_oh-my-zsh — to a complete, published, secrets-aware, second-machine-ready system. Work top to bottom; each phase ends with a verifiable checkpoint.

13 · Troubleshooting

Every symptom below was either reproduced while building this guide or is a documented failure mode. Start with chezmoi doctor; it catches config, git, and tool problems in one table.

14 · Cheat sheet

chezmoi add ~/.zshrc
chezmoi edit --apply ~/.zshrc
chezmoi diff
chezmoi apply -v
chezmoi status
chezmoi re-add
chezmoi cd

chezmoi update            # pull + apply
chezmoi git pull -- --autostash --rebase
chezmoi diff              # then apply
chezmoi init --apply $GITHUB_USERNAME
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply you

chezmoi managed
chezmoi source-path ~/.zshrc
chezmoi cat ~/.gitconfig
chezmoi data --format json
chezmoi execute-template '{{ .chezmoi.os }}'
chezmoi doctor
chezmoi state dump

chezmoi chattr private,+template ~/.gitconfig

# bring a machine from zero to yours
sh -c "$(curl -fsLS get.chezmoi.io)" \
  -- init --apply $GITHUB_USERNAME

{{ (keepassxc "entry").Password }}
{{ keepassxcAttribute "entry" "attr" }}
chezmoi add --encrypt ~/.secret-key
age-keygen -o key.txt

Glossary

source state

The declared truth: the contents of the source directory, attribute-encoded filenames and all. What you version and share. (§1)

source directory

~/.local/share/chezmoi — a normal git repository holding the source state. chezmoi cd drops you into it. (§5)

target state

The computed desired result: templates rendered with data, attributes resolved to permissions and types. Exists in memory during a run. (§1)

destination state

What is actually in the destination directory (usually ~) right now. apply converges it toward the target state. (§1)

attribute

A filename prefix/suffix in the source state (private_, dot_, .tmpl…) declaring metadata git can't store natively. (§6)

config file

~/.config/chezmoi/chezmoi.toml — per-machine, never in the repo. Holds [data], secrets backends, git automation, encryption settings. (§7)

.chezmoi.toml.tmpl

Special repo file rendered by chezmoi init to generate the config file, typically via prompt functions. The bridge between shared repo and per-machine data. (§8)

template data

The merged dictionary visible to templates: built-in .chezmoi.* values + config [data] + .chezmoidata.* + secret functions. Inspect with chezmoi data. (§7)

external

Content fetched from a URL at apply time (file, archive, git-repo) declared in .chezmoiexternal.toml, cached per refreshPeriod. (§11)

persistent state

A small boltdb (not the git repo) where chezmoi records script hashes and last-written file states — the memory behind run_once_ and the clobber guard. chezmoi state dump shows it. (§9)

clobber guard

Apply-time confirmation when a managed destination file changed out-of-band since chezmoi last wrote it. Resolved by re-add (keep) or --force (discard). (§6)

script (run_)

A source-state entry executed rather than written: run_once_ (per unique contents), run_onchange_ (when rendered contents change), with before_/after_ ordering around the file pass. (§9)

adoption

Bringing existing real files under management with chezmoi add — as opposed to authoring files in the source first. Your current, half-finished journey. (§5, §12)

Index

Commands, files, flags, and concepts → the section that teaches them.

Retrieval quiz

Flashcard style: answer out loud first, then reveal. Aim for 12/14 before calling the guide done; anything marked Review, reread its section the next day.

Sources

Checked against chezmoi v2.72.0 (Homebrew) on macOS, 2026-08-06, with keepassxc-cli 2.7.12 and age v1.3.1. Every transcript in this guide is real output from a sandboxed run of those versions; drift notes record where behavior surprised. External links need network; the guide itself works offline.

• Quick start — the official 10-minute loop; best as a warm-up before §5.
• Setup — publishing to GitHub and bootstrapping new machines; pairs with §8.
• Daily operations — edit/update/autoCommit reference; pairs with §5 and §8.
• Machine-to-machine differences — the templating cookbook behind §7.
• Source state attributes — the complete attribute table; the authority behind §6.
• Application order — exact apply sequencing; behind §9.
• KeePassXC integration — config keys and template functions; behind §10.
• age encryption — full encryption setup including passphrase mode; behind §10.
• Include files from elsewhere — externals cookbook (oh-my-zsh is its lead example); behind §11.
• Design FAQ — why no symlinks, one source of truth; behind §1.
• Releases — v2.72.0 (2026-08-02) confirmed latest at check date; trust the changelog over this page as versions move.
• chezmoi help and man chezmoi — exact flag semantics for your installed binary.

Compiled 2026-08-06 by Claude Code for Paul. Facts verified against the sources and live sandbox runs on that date.

Printed from the local chezmoi field guide.