Templating

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/template syntax extended with Sprig 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

chezmoi data

Data sources (later sources override earlier ones):

Built-in variables in .chezmoi (e.g., .chezmoi.os, .chezmoi.hostname)
.chezmoidata.$FORMAT files (read in alphabetical order)
data section in your config file

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

chezmoi edit ~/.zshrc

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=myhostnameThe - removes all surrounding whitespace (tabs, spaces, newlines).

Simple logic

# 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
`eq`	Returns true if first argument equals any other argument
`not`	Returns boolean negation
`and`	Returns boolean AND (returns first empty arg or last arg)
`or`	Returns boolean OR (returns first non-empty arg or last arg)

Integer comparison functions

Function	Description
`len`	Returns integer length
`eq`	arg1 == arg2
`ne`	arg1 != arg2
`lt`	arg1 < arg2
`le`	arg1 <= arg2
`gt`	arg1 > arg2
`ge`	arg1 >= 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 "[email protected]")) }}
# Linux and not home email
{{ end }}

Parentheses are required to chain operators.

Helper functions

chezmoi includes:

All Sprig functions
Custom chezmoi functions (see reference)

chezmoi data

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

dot_file.tmpl

{{ 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

{{- 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:

small-font.yml.tmpl

{{- template "alacritty" .alacritty.small -}}

small-font.yml.tmpl

{{- template "alacritty" dict "fontsize" 12 "font" "DejaVu Sans Mono" -}}

Use this approach to pass arguments inline without config file duplication.

Get Started

Core Concepts

User Guide

Encryption & Secrets

Password Managers

Advanced Usage

FAQ

Introduction

Template data

Creating a template file

Editing a template file

Testing templates

Template syntax

Simple logic

Boolean functions

Integer comparison functions

More complicated logic

Helper functions

Using `.chezmoitemplates`

Creating similar files with shared templates

Passing multiple arguments

Build docs developers (and LLMs) love

Get Started

Core Concepts

User Guide

Encryption & Secrets

Password Managers

Advanced Usage

FAQ

​Introduction

​Template data

​Creating a template file

​Editing a template file

​Testing templates

​Template syntax

​Simple logic

​Boolean functions

​Integer comparison functions

​More complicated logic

​Helper functions

​Using .chezmoitemplates

​Creating similar files with shared templates

​Passing multiple arguments

Build docs developers (and LLMs) love

Introduction

Template data

Creating a template file

Editing a template file

Testing templates

Template syntax

Simple logic

Boolean functions

Integer comparison functions

More complicated logic

Helper functions

Using `.chezmoitemplates`

Creating similar files with shared templates

Passing multiple arguments