Chezmoi

Suffixes

Examples

Templates (.tmpl files)

Chezmoi uses Go's text/template syntax. Template files have the .tmpl suffix.

Available data

• .chezmoi.os -- operating system (linux, darwin, windows)
• .chezmoi.arch -- architecture (amd64, arm64)
• .chezmoi.hostname -- machine hostname
• .chezmoi.username -- current username
• .chezmoi.homeDir -- home directory path
• .chezmoi.sourceDir -- source state directory path
• Custom data defined in .chezmoi.toml.tmpl under [data]

Template syntax

# Conditionals
{{ if eq .chezmoi.os "darwin" }}
# macOS-specific config
{{ else if eq .chezmoi.os "linux" }}
# Linux-specific config
{{ end }}

# Variable substitution
{{ .myVariable }}

# Pipeline with quote
{{ .myVariable | quote }}

Config template (.chezmoi.toml.tmpl)

Located at the source root. Defines data variables and chezmoi settings. Common functions:

[data]
  # Prompt once and persist the answer
  email = {{ promptStringOnce . "email" "What is your email?" | quote }}
  profile = {{ promptChoiceOnce . "profile" "Which profile?" (list "work" "personal") | quote }}

Secret management in templates

Chezmoi integrates with password managers. Common patterns:

# 1Password
{{ onepasswordRead "op://vault/item/field" }}

# Bitwarden
{{ (bitwarden "item" "my-item").login.password }}

# Dashlane
{{ (index (dashlanePassword "Entry Name") 0).password }}

# Age encryption (for encrypted_ files)
# Requires age key configured in chezmoi.toml

# Environment variable
{{ env "MY_SECRET" }}

Key commands

.chezmoiignore

Located at source root. Lists target paths (not source paths) that chezmoi should skip. Supports glob patterns and Go templates:

# Ignore a specific file
.config/nvim/lazy-lock.json

# Ignore a directory
.config/chezmoi/**

# Conditional ignore
{{ if ne .chezmoi.os "darwin" }}
.config/ghostty/**
{{ end }}

Workflow for editing dotfiles

1. Edit in source: Work in ~/.local/share/chezmoi/ directly
2. Preview: Run chezmoi diff to see what would change
3. Apply: Run chezmoi apply to deploy changes
4. Commit: git add, git commit, git push in the source directory

If you edited the target file directly instead:

1. Run chezmoi re-add to pull changes back into source
2. Or chezmoi merge <file> to merge conflicts

Important rules when editing chezmoi-managed files

• ALWAYS edit the source state files (in ~/.local/share/chezmoi/), never the target files directly
• Use the correct chezmoi naming conventions for new files
• When adding secrets, use template functions for password manager integration -- never hardcode secrets
• After editing .tmpl files, use chezmoi cat <target-path> to verify template rendering
• Run chezmoi diff before chezmoi apply to review changes
• The .chezmoiignore file uses target paths, not source paths
• When creating a new .tmpl file, ensure the Go template syntax is valid
• Remember that dot_ translates to . -- do not create files starting with . in the source