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.
Templates Overview
chezmoi executes templates using Go’s text/template package. Templates allow you to create dynamic configuration files that adapt to different machines, operating systems, and environments.
Basic Concepts
Templates are files with a .tmpl suffix in the source state. chezmoi processes these files and outputs the result to the destination.
Example
~/.local/share/chezmoi/dot_gitconfig.tmpl
[user]
name = {{ .name }}
email = {{ .email }}
{{ if eq .chezmoi.os "darwin" }}
[credential]
helper = osxkeychain
{{ end }}
Template Execution
The result of template execution is treated differently depending on the target type:
For Files
- If the result is an empty string, the file is removed
- Otherwise, the target file contents are the result
For Symlinks
- Leading and trailing whitespace are stripped from the result
- If the result is an empty string, the symlink is removed
- Otherwise, the target symlink target is the result
Template Options
chezmoi executes templates using text/template’s missingkey=error option by default, which means that misspelled or missing keys will raise an error.
This can be overridden by setting options in the configuration file:
~/.config/chezmoi/chezmoi.toml
[template]
options = ["missingkey=zero"]
missingkey=default - Use the default behaviormissingkey=error - Return an error on missing keys (default)missingkey=zero - Use the zero value for missing keysmissingkey=invalid - Print <no value> for missing keys
For a full list of template options, see Template.Option.
Template Syntax
Basic Substitution
{{ .variable }} # Output a variable
{{ .chezmoi.os }} # Access nested values
{{ .email | quote }} # Use functions
{{/* This is a comment */}}
{{- /* Comments can trim whitespace */ -}}
Whitespace Control
{{- .value }} # Trim whitespace before
{{ .value -}} # Trim whitespace after
{{- .value -}} # Trim both sides
Conditionals
{{ if .condition }}
# Rendered if condition is true
{{ end }}
{{ if .condition }}
# True branch
{{ else }}
# False branch
{{ end }}
{{ if .condition1 }}
# Branch 1
{{ else if .condition2 }}
# Branch 2
{{ else }}
# Default branch
{{ end }}
Loops
{{ range .items }}
Item: {{ . }}
{{ end }}
{{ range $index, $value := .items }}
{{ $index }}: {{ $value }}
{{ end }}
{{ range $key, $value := .dict }}
{{ $key }} = {{ $value }}
{{ end }}
Variables
{{ $var := .value }}
{{ $var }}
{{ $name := "John" }}
{{ $email := .email }}
Comparison Operators
{{ if eq .chezmoi.os "darwin" }}Mac{{ end }}
{{ if ne .value "test" }}Not test{{ end }}
{{ if lt .count 10 }}Less than 10{{ end }}
{{ if le .count 10 }}10 or less{{ end }}
{{ if gt .count 5 }}Greater than 5{{ end }}
{{ if ge .count 5 }}5 or more{{ end }}
Boolean Operators
{{ if and .condition1 .condition2 }}Both true{{ end }}
{{ if or .condition1 .condition2 }}At least one true{{ end }}
{{ if not .condition }}Negated{{ end }}
Template Functions
chezmoi provides all standard text/template functions, all Sprig functions, and many additional functions.
See Template Functions for a complete list.
Common Functions
{{ .value | quote }} # Quote a string
{{ .value | upper }} # Convert to uppercase
{{ .value | lower }} # Convert to lowercase
{{ .dict | toYaml }} # Convert to YAML
{{ .dict | toJson }} # Convert to JSON
{{ include "file.txt" }} # Include file contents
{{ includeTemplate "template.tmpl" . }} # Include and execute template
Template Variables
chezmoi provides automatically-populated variables accessible via .chezmoi:
{{ .chezmoi.os }} # Operating system (linux, darwin, etc.)
{{ .chezmoi.arch }} # Architecture (amd64, arm64, etc.)
{{ .chezmoi.hostname }} # Hostname
{{ .chezmoi.username }} # Username
{{ .chezmoi.homeDir }} # Home directory
{{ .chezmoi.sourceDir }} # Source directory
{{ .chezmoi.config }} # Configuration data
Template Directives
File-specific template options can be set using directives:
chezmoi:template:$KEY=$VALUE
Custom Delimiters
#!/bin/bash
# chezmoi:template:left-delimiter="# [[" right-delimiter="]]"
# [[ .variable ]]
Line Endings
{{/* chezmoi:template:line-endings=crlf */}}
Encoding
{{/* chezmoi:template:encoding=utf-16-le */}}
Practical Examples
OS-Specific Configuration
# Common configuration
export EDITOR=vim
{{ if eq .chezmoi.os "darwin" }}
# macOS-specific
export PATH="/usr/local/bin:$PATH"
alias ls="ls -G"
{{ else if eq .chezmoi.os "linux" }}
# Linux-specific
export PATH="/usr/bin:$PATH"
alias ls="ls --color=auto"
{{ end }}
Machine-Specific Configuration
dot_config_app_config.toml.tmpl
{{ if eq .chezmoi.hostname "workstation" }}
theme = "dark"
font_size = 14
{{ else }}
theme = "light"
font_size = 12
{{ end }}
Using Custom Data
packages:
- vim
- git
- tmux
run_once_install-packages.sh.tmpl
#!/bin/bash
{{ range .packages }}
apt-get install -y {{ . }}
{{ end }}
Using Secrets
dot_config_app_credentials.ini.tmpl
[api]
key = {{ onepassword "API Key" }}
secret = {{ onepassword "API Secret" }}
[database]
password = {{ bitwarden "item-id" }}
Error Handling
Templates will stop execution if an error occurs:
# This will error if .missing doesn't exist (with default missingkey=error)
{{ .missing }}
# Use default to provide a fallback
{{ .missing | default "default-value" }}
# Check if a key exists
{{ if hasKey . "missing" }}
{{ .missing }}
{{ else }}
default-value
{{ end }}
Testing Templates
Use chezmoi execute-template to test template expressions:
# Test a simple expression
chezmoi execute-template '{{ .chezmoi.os }}'
# Test with file
echo '{{ .chezmoi.hostname }}' | chezmoi execute-template
# Test complex template
chezmoi execute-template < template.tmpl
- Cache expensive operations: Store results in variables
- Avoid repeated function calls: Call once and store
- Use includes wisely: Don’t include large files multiple times
- Minimize external calls: Group
output calls when possible
{{/* GOOD: Call once */}}
{{ $os := .chezmoi.os }}
{{ if eq $os "darwin" }}...{{ end }}
{{ if eq $os "linux" }}...{{ end }}
{{/* BAD: Multiple calls */}}
{{ if eq .chezmoi.os "darwin" }}...{{ end }}
{{ if eq .chezmoi.os "linux" }}...{{ end }}
Related Pages