Chezmoi

Shell Consistency

Fish is the primary shell, but bash (dot_bashrc.mine.tmpl) and zsh (dot_zshrc) configs must stay consistent for shared concerns:

• PATH setup: all three shells should have /opt/homebrew/bin
• Shell plugins: 1Password plugins.sh sourced in all three
• Aliases/abbreviations: common aliases (cat→bat, vi→nvim, l→eza) in all three
• Tool activation: mise activate in all three
• Prompt: starship init in bash and zsh

When adding something to fish config, check if bash/zsh need the equivalent.

Chezmoi-First Principle

When the user asks to configure something (a new app, shell setting, tool, environment variable, etc.), always put the configuration into chezmoi:

• App config files → add to dot_config/ (or appropriate chezmoi path)
• New packages → add to .chezmoidata/packages.yaml (not brew install)
• New npm/pip tools → add to dot_config/mise/config.toml (not npm -g)
• Shell config → edit dot_config/fish/config.fish.tmpl (not ~/.config/fish/config.fish)
• New scripts → add to .chezmoiscripts/ with proper run_once_/run_onchange_ prefix
• Environment variables → add to the appropriate shell config template
• Machine-specific config → use template conditionals or .chezmoiignore

The goal: chezmoi apply on a fresh machine should fully reproduce the user's environment. If a change wouldn't survive chezmoi apply, it's wrong.

Never run brew install, npm install -g, pip install, or similar commands directly. Always update the declarative config and let chezmoi apply handle installation.

Prefix Mappings

Source directory: ~/.local/share/chezmoi/

Template Variables

All variables defined in .chezmoi.toml.tmpl. Key flags:

.targetname              # machine name (starship, nessie, work hostnames)
.is_work_machine         # semantic boolean
.is_personal_machine     # semantic boolean
.is_wife_machine         # semantic boolean
.is_child_machine        # semantic boolean
.is_laptop               # semantic boolean
.personalpackages        # true on non-work machines
.work.user, .work.domain # work identity
.packages.*              # package lists from .chezmoidata/packages.yaml

Use chezmoi data to see all current values. Use chezmoi execute-template '{{ .is_work_machine }}' to test snippets.

Template Whitespace

{{- trims leading whitespace, -}} trims trailing. Both are needed on guards before shebangs to avoid blank lines:

{{- if (eq .chezmoi.os "darwin") -}}
#!/bin/bash

Adding/Editing Config Files

Workflow

1. Find the source: chezmoi source-path ~/.config/foo/bar
2. Check if templated: look for .tmpl suffix in source
3. Edit the source file (in ~/.local/share/chezmoi/)
4. Preview: chezmoi diff
5. Apply: chezmoi apply (or chezmoi apply ~/.config/foo/bar for one file)

Adding a New File

chezmoi add ~/.config/foo/bar        # Add as static file
chezmoi add --template ~/.config/foo # Add as template (if it needs variables)

Machine-Specific Conditionals

{{ if .is_work_machine -}}
# work-only config
{{- end }}

{{ if .personalpackages -}}
# personal machine only
{{- end }}

For excluding entire files by machine type, add entries to .chezmoiignore.

Managing Brew Packages

Packages are declared in .chezmoidata/packages.yaml under .packages.brew. The brew install script (run_onchange_01_install-brew-packages.sh.tmpl) re-runs automatically whenever the rendered package list changes.

Package lists

To install a new brew package

1. Edit .chezmoidata/packages.yaml
2. Add the package name to the appropriate list (alphabetically sorted)
3. Run chezmoi apply — the run_onchange_ script auto-triggers

# Example: add a new CLI tool
# Edit .chezmoidata/packages.yaml, add under packages.brew.brews:
#   - ripgrep
# Then:
chezmoi apply

To install a new cask

Same as above but under packages.brew.casks or packages.brew.personal_casks.

Private tap

nettleton/tap is hardcoded in the brew script (not in YAML) because it uses a custom SSH git URL. Auth token is injected via op read. To add a formula from this tap, add it as "nettleton/tap/formulaname" in the brews list.

Managing Mise Tools

Tool versions are in dot_config/mise/config.toml. The mise install script (dot_config/mise/run_onchange_configure-mise.fish.tmpl) re-runs when the config changes.

# dot_config/mise/config.toml
[tools]
java = "corretto-21"
python = "latest"
node = "latest"
pipx = "latest"
"npm:neovim" = "latest"
"npm:npm" = "latest"

To add a new tool or npm package, edit this file and run chezmoi apply.

Managing Fisher Plugins

Fisher plugins are listed in .chezmoidata/packages.yaml under .packages.fisher. The fish config script installs them during 02-00_configure-fish.

Managing Go Binaries

Go packages are in .chezmoidata/packages.yaml under .packages.go. The install script (run_onchange_03-02_install-go.fish.tmpl) re-runs when the list changes.

Managing Mac App Store Apps

MAS apps are in .chezmoidata/packages.yaml under .packages.mas.apps (with name and id). The install script (run_onchange_04-01_install-mas-apps.sh.tmpl) re-runs when the list changes.

Conflict Resolution

When local drift exists (files modified outside chezmoi):

1. Check status: chezmoi status (shows drift between source and target)
2. Capture local changes: copy modified target files back to source
3. Preview: chezmoi diff
4. Apply: chezmoi apply

Do NOT use chezmoi add on templated files — copy directly instead:

# Wrong (strips template):
chezmoi add ~/.config/foo

# Right (preserves template):
cp ~/.config/foo ~/.local/share/chezmoi/dot_config/foo.tmpl

Script Taxonomy

Scripts in .chezmoiscripts/ follow a numeric prefix taxonomy that controls execution order (alphabetical by target path):

Script design principles

• One script per tool/concern. Each script should configure exactly one tool or service. Do not create catch-all scripts that configure multiple unrelated things. Example: 02-01_configure-rust only sets up Rust, 02-02_configure-go only sets up Go.
• Name scripts after what they configure, not what they do generically. Good: 02-06_configure-git-auth. Bad: 02-06_setup-stuff.
• Use the right prefix type: run_onchange_ for package installs (re-run when lists change), run_once_ for one-time configuration, run_after_ for every-apply fixups.
• When adding a new tool, create a new script rather than appending to an existing one. Pick the appropriate numeric prefix for the phase.

Idempotency

All chezmoi scripts must be safe to run multiple times. chezmoi apply can re-run at any time, and scripts must not fail or produce side effects on repeated execution.

Script types and re-run behavior

Patterns for idempotent scripts

• Package installs: brew bundle is inherently idempotent (skips installed)
• Config changes: Check before modifying (grep -q before appending)
• Service setup: Guard with existence checks (if not test -d, command -v)
• File operations: Use mkdir -p, ln -sfn (safe to repeat)
• Destructive ops: Always guard ([ -f "$file" ] && chmod ...)

run_after_ scripts

These run on every chezmoi apply. Keep them fast and guard every operation:

#!/bin/bash
[ -f "$HOME/.netrc" ] && chmod 400 "$HOME/.netrc"
exit 0  # Always succeed (avoid blocking apply)

Content hash triggers

run_onchange_ scripts embed content hashes in comments to trigger re-runs when data changes:

# packages hash: {{ include ".chezmoidata/packages.yaml" | sha256sum }}
# mise config hash: {{ include "dot_config/mise/config.toml" | sha256sum }}

When the referenced file changes, the rendered script content changes, and chezmoi re-runs it.

Update Phase Ordering

Scripts, externals, and files run alphabetically by target path during apply. This matters for dependencies:

• dot_config/mise/config.toml (placed as .config/mise/config.toml)
• dot_config/mise/run_onchange_configure-mise.fish.tmpl (runs as .config/mise/configure-mise.fish — sorts after config.toml)

If a script depends on a config file, ensure the script's target path sorts after the config file's target path.

Secrets

All secrets come from 1Password:

• op read "op://vault/item/field" in scripts
• {{ onepasswordRead "op://vault/item/field" }} in templates
• Never hardcode tokens or passwords
• All SSH keys (both public and private keys) also come from 1Password's SSH agent

Other Sensitive Information

• As this is a public repo, never check in work names, domains, URLs directly
• chezmoi data contains fields like .workcompanyname and .work.domain to obfuscate this

Common Mistakes