Chezmoi
This setup uses chezmoi to keep a macOS development environment reproducible.
If you have not used chezmoi before, start at Getting Started.
Source Layout
home/contains files that will be written into$HOME.- Templates use
*.tmpland accesschezmoidata (like.primaryEmail). - Hooks live in
home/.chezmoiscripts/. - Externals live in
home/.chezmoiexternal.toml.
If you are reading the source on GitHub, you can treat home/ as "what gets installed".
Render Model
Prompt definitions and computed values are defined in:
This is where machine-specific values are decided (for example emails, homebrewPrefix, and cache TTL values).
If something renders differently than expected, start by inspecting this file.
Hook Pipeline (High Signal)
The first-run and converge flow is driven by ordered scripts in home/.chezmoiscripts/:
| Order | Hook | Purpose |
|---|---|---|
| 00 | run_once_before_00-install-xcode.sh | Xcode CLT |
| 01 | run_once_after_01-install-brew.sh | Homebrew install |
| 02 | run_once_after_02-install-fish.sh | Fish install + login shell |
| 03 | run_onchange_after_03-install-brew-packages.fish.tmpl | Brew bundle |
| 04 | run_onchange_after_04-update-fish-packages.fish.tmpl | Fish plugins |
| 05 | run_onchange_after_05-* | Package, OS, and integration scripts |
| 06 | run_onchange_after_06-update-uv-tools.sh.tmpl | uv global tools |
This is the first place to look when chezmoi apply fails.
Core Workflows
Safe apply loop
chezmoi diff
chezmoi apply
Use chezmoi diff before apply whenever you changed templates or prompt data.
Pull remote changes safely
chezmoi update --apply=false
chezmoi diff
chezmoi apply
Debug a failing hook
- Re-run and capture the failing script path:
chezmoi apply
- If it is a template hook, render it directly:
chezmoi execute-template < home/.chezmoiscripts/<script>.tmpl
- Run the generated command or script directly to isolate dependency issues.
Verification And Troubleshooting
Useful checks:
chezmoi doctor
chezmoi status
chezmoi diff
Externals can be refreshed with:
chezmoi apply --refresh-externals=always
If a script fails with command not found, check whether its prerequisite hook (usually Homebrew/mise) ran successfully.