Skip to main content

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.

​
Use templates

The primary goal of chezmoi is to manage configuration files across multiple machines with different requirements. chezmoi uses Go’s text/template syntax for customization.
1

Create a machine-specific config file

Define variables that vary between machines:
[data]
    email = "me@home.org"
If storing private data (access tokens), ensure permissions are 0600.
2

Add the file as a template

chezmoi add --template ~/.gitconfig
This creates ~/.local/share/chezmoi/dot_gitconfig.tmpl.
3

Edit the template

chezmoi edit ~/.gitconfig
Update the file to use template variables:
~/.local/share/chezmoi/dot_gitconfig.tmpl
[user]
    email = {{ .email | quote }}

chezmoi data
Shows all template variables available on your system.

​
Common template patterns

# ~/.local/share/chezmoi/dot_bashrc.tmpl
# 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_ENV=production
{{- end }}
The - inside template brackets removes surrounding whitespace. This prevents extra newlines in your output.

​
Ignore files or directories on different machines

Use .chezmoiignore templates for coarse-grained control: 
README.md
{{- if ne .chezmoi.hostname "work-laptop" }}
.work # only manage .work on work-laptop
{{- end }}
Use ne (not equal) to express “only install if”. We say “ignore unless work-laptop” instead of “install if work-laptop” because chezmoi installs everything by default.

​
Handle different file locations on different systems with the same contents

Use shared templates in .chezmoitemplates:
1

Create shared template

~/.local/share/chezmoi/.chezmoitemplates/file.conf
# Common configuration
setting1 = value1
setting2 = value2
2

Create platform-specific files

{{- template "file.conf" . -}}
3

Ignore files on wrong platforms

~/.local/share/chezmoi/.chezmoiignore
{{ if ne .chezmoi.os "darwin" }}
Library/Application Support/App/file.conf
{{ end }}
{{ if ne .chezmoi.os "linux" }}
.config/app/file.conf
{{ end }}

​
Use completely different dotfiles on different machines

~/.local/share/chezmoi/dot_bashrc.tmpl
{{ if eq .chezmoi.os "darwin" -}}
# macOS .bashrc contents
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" -}}
# Linux .bashrc contents
export PATH="$PATH:/usr/local/bin"
{{ end -}}

Build docs developers (and LLMs) love

Get started for freeTalk to us