chezmoi - Dotfiles Manager

Manage your dotfiles across multiple machines, securely.

Quick Reference

Installation

bash

# macOS
brew install chezmoi

# Linux (snap)
snap install chezmoi --classic

# Linux (binary)
sh -c "$(curl -fsLS get.chezmoi.io)"

# Windows
winget install twpayne.chezmoi
# or
choco install chezmoi

Essential Commands

Command	Description
`chezmoi init`	Initialize chezmoi on new machine
`chezmoi add ~/.bashrc`	Add file to source state
`chezmoi edit ~/.bashrc`	Edit file in source state
`chezmoi diff`	Preview changes before apply
`chezmoi apply`	Apply changes to home directory
`chezmoi update`	Pull from remote and apply
`chezmoi cd`	Open shell in source directory
`chezmoi doctor`	Check for common problems

Quick Start (New Machine)

bash

# Initialize from GitHub (combines clone + apply)
chezmoi init --apply $GITHUB_USERNAME

# Or with full URL
chezmoi init --apply https://github.com/username/dotfiles.git

Daily Workflow

bash

# Add new dotfile
chezmoi add ~/.config/starship.toml

# Edit and apply in one command
chezmoi edit --apply ~/.bashrc

# Check what would change
chezmoi diff

# Apply all changes
chezmoi apply -v

# Push changes (in source directory)
chezmoi cd
git add . && git commit -m "Update dotfiles" && git push

Source State Attributes

File Prefixes

Prefix	Effect	Example
`dot_`	Adds `.` to filename	`dot_bashrc` → `.bashrc`
`private_`	Mode 0600 (user only)	`private_dot_ssh/`
`executable_`	Mode +x	`executable_dot_local/bin/script`
`readonly_`	Mode -w	`readonly_dot_config`
`encrypted_`	Encrypted file	`encrypted_private_dot_ssh/id_rsa`
`empty_`	Keep empty file	`empty_dot_gitkeep`
`create_`	Create only if missing	`create_dot_config`
`modify_`	Modify existing file	`modify_dot_bashrc`
`remove_`	Remove from target	`remove_dot_old_config`
`symlink_`	Create symlink	`symlink_dot_vimrc`
`exact_`	Remove unlisted items	`exact_dot_config/`

Template Suffix

Add .tmpl to process as Go template:

code

dot_gitconfig.tmpl
private_dot_ssh/config.tmpl

Script Prefixes

Prefix	Behavior
`run_`	Run every apply
`run_once_`	Run once (tracks hash)
`run_onchange_`	Run when content changes
`before_`	Run before file updates
`after_`	Run after file updates

Example: run_once_before_install-packages.sh.tmpl

Templates

Basic Syntax

code

{{ .chezmoi.hostname }}
{{ .chezmoi.os }}
{{ .chezmoi.arch }}
{{ .chezmoi.username }}
{{ .chezmoi.homeDir }}

Conditionals

code

{{ if eq .chezmoi.os "darwin" }}
# macOS specific
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" }}
# Linux specific
export PATH="$HOME/.local/bin:$PATH"
{{ end }}

Complex Conditions

code

{{ if and (eq .chezmoi.os "linux") (eq .chezmoi.hostname "workstation") }}
# Work machine Linux config
{{ end }}

Whitespace Control

code

{{- .variable -}}  # Trim both sides
{{- .variable }}   # Trim left only
{{ .variable -}}   # Trim right only

View Available Data

bash

chezmoi data

Test Templates

bash

chezmoi execute-template '{{ .chezmoi.hostname }}'
chezmoi cat ~/.bashrc  # Preview rendered template

Password Manager Integration

1Password

code

{{ onepassword "item-name" }}
{{ onepasswordRead "op://vault/item/field" }}
{{ onepasswordDocument "document-uuid" }}
{{ onepasswordDetailsFields "item-name" }}

Modes: account (default), connect, service (for CI/CD)

Bitwarden

code

{{ bitwarden "item" "example.com" }}
{{ (bitwarden "item" "example.com").login.password }}
{{ bitwardenFields "item" "example.com" }}
{{ bitwardenAttachment "id_rsa" "item-uuid" }}
{{ bitwardenSecrets "secret-id" }}
{{ rbw "item-name" }}

Auto-unlock (chezmoi.toml):

toml

[bitwarden]
    unlock = "auto"

pass (Unix Password Manager)

code

{{ pass "path/to/secret" }}
{{ passFields "path/to/secret" }}

gopass

code

{{ gopass "path/to/secret" }}

LastPass

code

{{ lastpass "item-id" }}

AWS Secrets Manager

code

{{ awsSecretsManager "secret-name" }}

Azure Key Vault

code

{{ azureKeyVault "secret-name" }}

Vault (HashiCorp)

code

{{ vault "secret/path" }}

Encryption

Setup with age (Recommended)

bash

# Generate key
age-keygen -o ~/.config/chezmoi/key.txt

# Configure chezmoi.toml
[age]
    identity = "~/.config/chezmoi/key.txt"
    recipient = "age1..."

Setup with GPG

bash

# Configure chezmoi.toml
[gpg]
    recipient = "your-gpg-key-id"

Add Encrypted Files

bash

chezmoi add --encrypt ~/.ssh/id_rsa
chezmoi add --encrypt ~/.config/secrets.yaml

Encrypted files use encrypted_ prefix automatically.

Configuration File

Location: ~/.config/chezmoi/chezmoi.toml

Common Settings

toml

# Source directory (default: ~/.local/share/chezmoi)
sourceDir = "~/.dotfiles"

# Default editor
[edit]
    command = "nvim"

# Git auto-commit and push
[git]
    autoCommit = true
    autoPush = true

# Diff settings
[diff]
    pager = "delta"

# Merge tool
[merge]
    command = "nvim"
    args = ["-d", "{{ .Destination }}", "{{ .Source }}", "{{ .Target }}"]

# age encryption
[age]
    identity = "~/.config/chezmoi/key.txt"
    recipient = "age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Machine-Specific Data

toml

[data]
    email = "user@example.com"
    name = "Your Name"

[data.work]
    proxy = "http://proxy.work.com:8080"

Access in templates: {{ .email }}, {{ .work.proxy }}

Machine-Specific Configuration

Config Template (`.chezmoi.toml.tmpl`)

Create in source root for interactive setup:

toml

[data]
    email = {{ promptString "email" | quote }}
    name = {{ promptString "name" | quote }}
{{- if eq .chezmoi.hostname "work-laptop" }}
    work = true
{{- end }}

Data Files (`.chezmoidata.yaml`)

yaml

packages:
  common:
    - git
    - tmux
    - neovim
  work:
    - docker
    - kubectl

Access: {{ .packages.common }}

Conditional File Inclusion (`.chezmoiignore`)

code

# Ignore on non-Linux
{{ if ne .chezmoi.os "linux" }}
.config/i3/
.xinitrc
{{ end }}

# Ignore work config on personal machines
{{ if not .work }}
.config/work/
{{ end }}

Scripts

Install Packages (run_onchange)

bash

#!/bin/bash
# run_onchange_install-packages.sh.tmpl

{{ if eq .chezmoi.os "darwin" -}}
brew bundle --file=/dev/stdin <<EOF
{{ range .packages.common -}}
brew "{{ . }}"
{{ end -}}
EOF
{{ else if eq .chezmoi.os "linux" -}}
sudo apt-get update
sudo apt-get install -y {{ range .packages.common }}{{ . }} {{ end }}
{{ end -}}

One-Time Setup (run_once)

bash

#!/bin/bash
# run_once_before_setup-directories.sh

mkdir -p ~/.local/bin
mkdir -p ~/.config
mkdir -p ~/.cache

Trigger on File Change

bash

#!/bin/bash
# run_onchange_reload-shell.sh.tmpl
# Hash: {{ include "dot_bashrc.tmpl" | sha256sum }}

source ~/.bashrc

Common Patterns

GitHub SSH Keys

code

# dot_ssh/authorized_keys.tmpl
{{ range gitHubKeys "username" }}
{{ . }}
{{ end }}

Include Partial Templates

code

# .chezmoitemplates/git-config
[user]
    name = {{ .name }}
    email = {{ .email }}

# dot_gitconfig.tmpl
{{ template "git-config" . }}

[core]
    editor = nvim

External Files

yaml

# .chezmoiexternal.yaml
".vim/autoload/plug.vim":
    type: file
    url: "https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim"
    refreshPeriod: 168h

".oh-my-zsh":
    type: archive
    url: "https://github.com/ohmyzsh/ohmyzsh/archive/master.tar.gz"
    stripComponents: 1

All Commands (56 Total)

Core: add, apply, archive, cat, cd, data, diff, edit, forget, init, manage, managed, merge, re-add, remove, source-path, status, target-path, unmanage, unmanaged, update, verify

Config: cat-config, dump-config, edit-config, edit-config-template

Encryption: age, age-keygen, decrypt, edit-encrypted, encrypt, secret

Utility: chattr, completion, destroy, doctor, dump, generate, git, help, ignored, import, license, list, merge-all, purge, ssh, state, upgrade

Container: docker

Troubleshooting

Check for Issues

bash

chezmoi doctor

Verbose Output

bash

chezmoi apply -v
chezmoi diff -v

Dry Run

bash

chezmoi apply -n  # Preview without changes

Debug Templates

bash

chezmoi execute-template < file.tmpl
chezmoi cat ~/.config/file  # Show rendered content

Reset State

bash

chezmoi state delete-bucket --bucket=scriptState  # Re-run scripts
chezmoi forget ~/.config/file  # Stop managing file

When to Use This Skill

•Setting up dotfiles management across machines
•Creating machine-specific configurations with templates
•Encrypting sensitive dotfiles (SSH keys, API tokens)
•Integrating password managers with dotfiles
•Writing install/setup scripts for new machines
•Syncing dotfiles via Git repository
•Managing complex multi-machine configurations

chezmoi - Dotfiles Manager

Quick Reference

Installation

Essential Commands

Quick Start (New Machine)

Daily Workflow

Source State Attributes

File Prefixes

Template Suffix

Script Prefixes

Templates

Basic Syntax

Conditionals

Complex Conditions

Whitespace Control

View Available Data

Test Templates

Password Manager Integration

1Password

Bitwarden

pass (Unix Password Manager)

gopass

LastPass

AWS Secrets Manager

Azure Key Vault

Vault (HashiCorp)

Encryption

Setup with age (Recommended)

Setup with GPG

Add Encrypted Files

Configuration File

Common Settings

Machine-Specific Data

Machine-Specific Configuration

Config Template (.chezmoi.toml.tmpl)

Data Files (.chezmoidata.yaml)

Conditional File Inclusion (.chezmoiignore)

Scripts

Install Packages (run_onchange)

One-Time Setup (run_once)

Trigger on File Change

Common Patterns

GitHub SSH Keys

Include Partial Templates

External Files

All Commands (56 Total)

Troubleshooting

Check for Issues

Verbose Output

Dry Run

Debug Templates

Reset State

When to Use This Skill

Resources

Config Template (`.chezmoi.toml.tmpl`)

Data Files (`.chezmoidata.yaml`)

Conditional File Inclusion (`.chezmoiignore`)