dotfiles/docs/CHEZMOI-QUICK-REFERENCE.md

Chezmoi Quick Reference

Quick reference guide for common chezmoi operations with your dotfiles.

Installation

# Fresh install on a new machine
sh -c "$(curl -fsLS get.chezmoi.io/lb)" -- init --apply ivuorinen

# Or if chezmoi is already installed
chezmoi init --apply ivuorinen

Daily Workflow

Making Changes

# Edit a dotfile (opens in $EDITOR)
chezmoi edit ~/.bashrc

# Or edit directly and add to chezmoi
vim ~/.bashrc
chezmoi add ~/.bashrc

# See what would change
chezmoi diff

# Apply changes
chezmoi apply

Syncing Across Machines

# On machine A: commit and push changes
cd $(chezmoi source-path)
git add -A
git commit -m "Update configuration"
git push

# On machine B: pull and apply changes
chezmoi update
# This is equivalent to:
# cd $(chezmoi source-path) && git pull && chezmoi apply

Common Commands

Viewing and Inspecting

# See what chezmoi would do
chezmoi diff

# List all managed files
chezmoi managed

# List unmanaged files
chezmoi unmanaged

# Show the source path
chezmoi source-path

# Show what a file would look like after templating
chezmoi cat ~/.bashrc

# Show available template data
chezmoi data

Adding and Removing Files

# Add a file
chezmoi add ~/.newfile

# Add a file as a template
chezmoi add --template ~/.newfile

# Add a directory recursively
chezmoi add --recursive ~/.config/newapp

# Add with autodetection (templates, scripts, etc.)
chezmoi add --autotemplate ~/.newfile

# Stop managing a file (removes from chezmoi)
chezmoi forget ~/.oldfile

# Remove a file from both chezmoi and home directory
chezmoi remove ~/.oldfile

Working with Templates

# Execute a template expression
chezmoi execute-template "{{ .chezmoi.hostname }}"

# Edit template data
chezmoi edit-config

# Verify templates
chezmoi verify

Applying Changes

# Apply all changes
chezmoi apply

# Apply with verbose output
chezmoi apply -v

# Dry run (show what would happen)
chezmoi apply --dry-run -v

# Force apply (re-runs scripts)
chezmoi apply --force

# Apply only specific files
chezmoi apply ~/.bashrc ~/.zshrc

Updating from Repository

# Update dotfiles from repository
chezmoi update

# Update but don't apply
cd $(chezmoi source-path) && git pull

# Update with interactive merge
chezmoi update --interactive

File Naming Conventions

Basic Prefixes

Source File	Destination	Description
dot_bashrc	~/.bashrc	Dot file
dot_config/	~/.config/	Dot directory
private_dot_ssh/	~/.ssh/	Private directory (0700)
executable_dot_local/bin/script	~/.local/bin/script	Executable
symlink_dot_vim	~/.vim	Symlink
readonly_dot_file	~/.file	Read-only

Template Files

Source File	Description
dot_bashrc.tmpl	Template file
dot_config/fish/config.fish.tmpl	Nested template

Scripts

Script Name	When It Runs
run_once_before_*.sh	Once before applying
run_once_after_*.sh	Once after applying
run_before_*.sh	Every time before applying
run_after_*.sh	Every time after applying
run_onchange_*.sh	When script content changes

Template Syntax

Basic Variables

// Hostname
{{ .chezmoi.hostname }}

// Username
{{ .chezmoi.username }}

// Operating system
{{ .chezmoi.os }}

// Home directory
{{ .chezmoi.homeDir }}

// Source directory
{{ .chezmoi.sourceDir }}

// Custom data from .chezmoi.yaml
{{ .is_macos }}
{{ .is_linux }}

Conditionals

{{ if eq .chezmoi.hostname "air" }}
# Configuration for air
{{ else if eq .chezmoi.hostname "lakka" }}
# Configuration for lakka
{{ else }}
# Default configuration
{{ end }}

{{ if .is_macos }}
# macOS-specific
{{ end }}

{{ if and .is_macos (eq .chezmoi.hostname "air") }}
# macOS on air
{{ end }}

Loops

{{ range $key, $value := .data }}
{{ $key }}: {{ $value }}
{{ end }}

Including Files

{{ include "template-file.txt" }}
{{ includeTemplate "template-file.tmpl" }}

Host-Specific Configuration

Method 1: Template Conditionals

In dot_bashrc.tmpl:

# Common configuration
export PATH="$HOME/.local/bin:$PATH"

{{ if eq .chezmoi.hostname "air" }}
# air-specific configuration
export WORK_DIR="$HOME/Work"
{{ end }}

{{ if eq .chezmoi.hostname "lakka" }}
# lakka-specific configuration
export WORK_DIR="$HOME/Projects"
{{ end }}

Method 2: Separate Files with Symlinks

Use .chezmoiignore to exclude files for specific hosts:

{{ if ne .chezmoi.hostname "air" }}
dot_config/air-specific-app/
{{ end }}

{{ if ne .chezmoi.hostname "lakka" }}
dot_config/lakka-specific-app/
{{ end }}

Working with Secrets

Environment Variables

{{ .Env.MY_SECRET }}

1Password

{{ (onepasswordDocument "my-secret").content }}
{{ (onepasswordItemFields "my-item").password.value }}

External Commands

{{ output "op" "read" "op://vault/item/field" }}

Troubleshooting

Check Configuration

# Verify chezmoi is working correctly
chezmoi doctor

# Check state
chezmoi verify

# See detailed info
chezmoi data

Debug Templates

# See what a template would produce
chezmoi cat ~/.bashrc

# Execute a template
chezmoi execute-template "{{ .chezmoi.hostname }}"

# Verbose output
chezmoi apply -v

Fix Issues

# Re-apply everything
chezmoi apply --force

# Reset state (dangerous!)
chezmoi state reset

# Clear cache
rm -rf $(chezmoi source-path)/.git/chezmoi-*

Common Errors

Error: template: ... undefined variable

• Check template syntax
• Verify data with chezmoi data

Error: entry ... is not in source state

• File not added to chezmoi: chezmoi add <file>

Error: ... has been modified since chezmoi last wrote it

• See changes: chezmoi diff
• Re-add: chezmoi add <file>
• Or force apply: chezmoi apply --force

Useful Aliases

Add these to your shell configuration:

# Chezmoi shortcuts
alias cm='chezmoi'
alias cma='chezmoi apply'
alias cmd='chezmoi diff'
alias cme='chezmoi edit'
alias cmu='chezmoi update'
alias cmcd='cd $(chezmoi source-path)'

# Common workflows
alias cmup='chezmoi git pull && chezmoi apply'
alias cmpush='cd $(chezmoi source-path) && git add -A && git commit && git push'

Environment Variables

# Change source directory (default: ~/.local/share/chezmoi)
export CHEZMOI_SOURCE_DIR="$HOME/.dotfiles"

# Change config file location
export CHEZMOI_CONFIG_FILE="$HOME/.config/chezmoi/chezmoi.yaml"

# Use different editor
export EDITOR="vim"

Advanced Usage

Using chezmoi as a dotfiles manager

# Initialize with local directory
chezmoi init --source ~/.dotfiles

# Use current directory as source
chezmoi init --source $(pwd)

Managing Multiple Machines

Use data in .chezmoi.yaml.tmpl:

data:
  is_work_machine: {{ or (eq .chezmoi.hostname "work-laptop") (eq .chezmoi.hostname "work-desktop") }}
  is_personal: {{ eq .chezmoi.hostname "personal-laptop" }}

Then in templates:

{{ if .is_work_machine }}
# Work configuration
{{ end }}

External Files

# .chezmoiexternal.yaml
".config/nvim/lua/plugins":
  type: "archive"
  url: "https://github.com/user/nvim-config/archive/main.tar.gz"
  stripComponents: 1
  refreshPeriod: "168h"

Resources

• Official Documentation
• User Guide
• Template Reference
• Command Reference
• FAQ

Help

# General help
chezmoi help

# Command-specific help
chezmoi help apply
chezmoi help add

# Show version
chezmoi --version