Documentation Index Fetch the complete documentation index at: https://mintlify.com/twpayne/chezmoi/llms.txt
Use this file to discover all available pages before exploring further.
Introduction Templates allow you to change file contents based on the environment. For example, use different email addresses or API keys on different machines.
chezmoi uses Go’s text/templateSprig functions .
A file is interpreted as a template if:
The filename has a .tmpl suffix
The file is in .chezmoitemplates directory or its subdirectories
Template data View all available data
Example output
Data sources (later sources override earlier ones):
Built-in variables in .chezmoi (e.g., .chezmoi.os, .chezmoi.hostname).chezmoidata.$FORMAT filesdata section
chezmoi also provides functions to retrieve runtime data from password managers, environment variables, and the file system.
Creating a template file Add with --template
Convert existing file
Create manually
Shared templates
chezmoi add --template ~/.zshrc
Creates ~/.local/share/chezmoi/dot_zshrc.tmpl. chezmoi chattr +template ~/.zshrc
Converts an already-managed file to a template. chezmoi cd $EDITOR dot_zshrc.tmpl
Create the template file directly in the source directory. chezmoi cd mkdir -p .chezmoitemplates cd .chezmoitemplates $EDITOR mytemplate
Templates in .chezmoitemplates must be created manually. Editing a template file Edit template
Edit and apply
The edit command opens the source file and checks template syntax when you quit the editor.
Testing templates Simple expression
Test file
PowerShell
chezmoi execute-template '{{ .chezmoi.hostname }}'
Output: myhost chezmoi cd chezmoi execute-template < dot_zshrc.tmpl
Shows what the template will generate. cat foo.txt | chezmoi execute - template
Use piping if file redirection doesn’t work. Template syntax Template actions are written inside {{ }}. Text outside is copied literally.
Variables
Conditionals
Removing whitespace
{{ .chezmoi.hostname }} {{ .email }}
{{ if eq .chezmoi.os "darwin" }} # darwin {{ else if eq .chezmoi.os "linux" }} # linux {{ else }} # other operating system {{ end }}
HOSTNAME={{- .chezmoi.hostname }}
Output: HOSTNAME=myhostname The - removes all surrounding whitespace (tabs, spaces, newlines). Simple logic Conditional sections
Multiple conditions
# common config export EDITOR = vi # machine-specific configuration {{- if eq .chezmoi.hostname "work-laptop" }} # this will only be included in ~/.bashrc on work-laptop export WORK_VAR = value {{- end }}
Boolean functions Function Description eqReturns true if first argument equals any other argument notReturns boolean negation andReturns boolean AND (returns first empty arg or last arg) orReturns boolean OR (returns first non-empty arg or last arg)
Integer comparison functions Function Description lenReturns integer length eqarg1 == arg2 nearg1 != arg2 ltarg1 < arg2 learg1 <= arg2 gtarg1 > arg2 gearg1 >= arg2
More complicated logic Multiple eq arguments
Chaining operators
{{ if eq "foo" "foo" "bar" }}hello{{end}}
Checks if first arg equals any of the other args. {{ if (and (eq .chezmoi.os "linux") (ne .email "me@home.org")) }} # Linux and not home email {{ end }}
Parentheses are required to chain operators. Helper functions chezmoi includes:
Access template variables
Use in templates
Using .chezmoitemplates Files in .chezmoitemplates can be included in other templates using the template action:
Create shared template
.chezmoitemplates/part.tmpl
{{ if eq .chezmoi.os "linux" }} # linux config {{ else }} # non-linux config {{ end }}
Use in another template
{{ template "part.tmpl" . }}
Pass . to make template variables available. Without it, the template receives nil data.
Creating similar files with shared templates
Create shared template
.chezmoitemplates/alacritty
some: config fontsize: {{ . }} more: config
Files in .chezmoitemplates don’t need .tmpl extension.
Create files using the template
small-font.yml.tmpl
big-font.yml.tmpl
{{- template "alacritty" 12 -}}
Test the output
chezmoi cat ~/small-font.yml
Output: some : config fontsize : 12 more : config
Passing multiple arguments Via config file
Via dictionary
~/.config/chezmoi/chezmoi.toml
[ data . alacritty . big ] fontsize = 18 font = "DejaVu Serif" [ data . alacritty . small ] fontsize = 12 font = "DejaVu Sans Mono"
Template: .chezmoitemplates/alacritty
some: config fontsize: {{ .fontsize }} font: {{ .font }} more: config
Usage: {{- template "alacritty" .alacritty.small -}}
{{- template "alacritty" dict "fontsize" 12 "font" "DejaVu Sans Mono" -}}
Use this approach to pass arguments inline without config file duplication.