Chezmoi

Chezmoi Dotfile Manager

Manage your dotfiles across multiple diverse machines, securely.

Quick Reference

Local Workflow Contract

On this machine, use the dotfiles helper as the control plane instead of jumping straight to chezmoi update.

Dry Run First

dotfiles status                 # Summary dashboard for chezmoi + ~/.agents
dotfiles sync                   # Dry-run planner, writes latest report
dotfiles inspect report         # Full dry-run report
dotfiles inspect chezmoi-diff   # Full target/source diff
dotfiles inspect chezmoi-remote # Remote commits not yet local
dotfiles inspect agents-remote  # ~/.agents remote commits not yet local

Explicit Apply Paths

dotfiles sync --apply chezmoi   # Re-add, commit, pull --rebase, push, apply
dotfiles sync --apply agents    # Commit, pull --rebase, push ~/.agents
dotfiles sync --apply all       # Run both explicit apply paths
dotfiles pull                   # Pull chezmoi source repo and apply
dotfiles agents-pull            # Pull ~/.agents with rebase

Behavior Rules

• dotfiles sync is the safe entry point. It performs a dry run and does not mutate state.
• Read the dry-run report before choosing an apply action when local and remote both moved.
• ~/.agents stays a separate git repo; it is surfaced in the same dashboard but is not folded into chezmoi source state.
• The latest dry-run report is written to ~/.local/state/lev/dotfiles-sync-plan.latest.txt.

One-liner Bootstrap

sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB_USERNAME

Core Concepts

Source State vs Target State

• Source state: Files in ~/.local/share/chezmoi/ (managed by chezmoi)
• Target state: Files in your home directory (what chezmoi manages)
• Destination directory: Usually ~ (your home)

File Naming Conventions

Directory Attributes

~/.local/share/chezmoi/
├── dot_config/
│   ├── exact_nvim/           # exact_ = remove unlisted files
│   └── private_gnupg/        # private_ = mode 0700
├── private_dot_ssh/
│   └── private_config        # mode 0600
└── dot_bashrc.tmpl           # template

Templating

Basic Template Syntax

{{ .chezmoi.hostname }}       # Current hostname
{{ .chezmoi.os }}             # darwin, linux, windows
{{ .chezmoi.arch }}           # amd64, arm64
{{ .chezmoi.username }}       # Current user
{{ .chezmoi.homeDir }}        # Home directory path

Conditionals

# dot_bashrc.tmpl
{{ if eq .chezmoi.os "darwin" -}}
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" -}}
export HOMEBREW_PREFIX="${HOMEBREW_PREFIX:-$HOME/.linuxbrew}"
{{ end -}}

Machine-specific Config

Create ~/.config/chezmoi/chezmoi.toml for machine-specific data:

[data]
    email = "me@work.com"
    git_signing_key = "ABC123"
    
[data.work]
    enabled = true

Then in templates:

{{ .email }}
{{ if .work.enabled }}
# Work-specific config
{{ end }}

Prompt for Data on Init

Create .chezmoi.<format>.tmpl (e.g., .chezmoi.toml.tmpl):

[data]
    email = {{ promptString "Email address" | quote }}
    signingkey = {{ promptString "GPG signing key" | quote }}

Password Manager Integration

1Password

# In template
{{ onepasswordRead "op://vault/item/field" }}
{{ (onepassword "item-name").password }}

Bitwarden

{{ (bitwarden "item-name").login.password }}

pass (Unix Password Store)

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

Generic (Any Password Manager)

# In chezmoi.toml
[secret]
    command = "my-secret-tool"
    args = ["get"]

# In templates
{{ secret "secret-name" }}

Encryption

Using age (Recommended)

# Generate key
chezmoi age-keygen

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

Encrypt Files

# Add encrypted file
chezmoi add --encrypt ~/.ssh/id_rsa

# Result: encrypted_private_dot_ssh/private_id_rsa.age

Scripts

Run Scripts on Apply

Script Ordering

Scripts run alphabetically. Use numeric prefixes:

.chezmoiscripts/
├── run_once_before_01-install-homebrew.sh
├── run_once_before_02-install-packages.sh
└── run_onchange_after_reload-shell.sh

Script Template

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

{{ if eq .chezmoi.os "darwin" -}}
brew bundle --file=/dev/stdin <<EOF
brew "ripgrep"
brew "fd"
cask "wezterm"
EOF
{{ else if eq .chezmoi.os "linux" -}}
sudo apt-get install -y ripgrep fd-find
{{ end -}}

External Files

Import from URL/Archive

Create .chezmoiexternal.toml:

[".oh-my-zsh"]
    type = "archive"
    url = "https://github.com/ohmyzsh/ohmyzsh/archive/master.tar.gz"
    stripComponents = 1
    refreshPeriod = "168h"

[".local/bin/starship"]
    type = "file"
    url = "https://starship.rs/install.sh"
    executable = true

Import from Git

[".tmux/plugins/tpm"]
    type = "git-repo"
    url = "https://github.com/tmux-plugins/tpm.git"
    refreshPeriod = "168h"

Configuration File

Located at ~/.config/chezmoi/chezmoi.toml:

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

# Diff tool
[diff]
    pager = "delta"

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

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

# Data for templates
[data]
    name = "Your Name"
    email = "your@email.com"

Common Workflows

New Machine Setup

# Install chezmoi and apply dotfiles
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB_USERNAME

Daily Updates

# Pull changes and apply
chezmoi update

# Or step-by-step
chezmoi git pull
chezmoi diff
chezmoi apply

Adding New Files

chezmoi add ~/.bashrc                    # Regular file
chezmoi add --encrypt ~/.ssh/config      # Encrypted
chezmoi add --template ~/.gitconfig      # As template
chezmoi add --autotemplate ~/.config/X   # Auto-detect template

Editing Files

chezmoi edit ~/.bashrc     # Edit source, then apply
chezmoi edit-config        # Edit chezmoi.toml

Troubleshooting

See references/troubleshooting.md for common issues including:

• Vimpager/AnsiEsc ANSI escape code issues
• Diff pager configuration
• Encryption setup problems

References

• Official Docs: https://www.chezmoi.io/
• GitHub: https://github.com/twpayne/chezmoi
• Quick Start: https://www.chezmoi.io/quick-start/
• User Guide: https://www.chezmoi.io/user-guide/
• Reference: https://www.chezmoi.io/reference/

Template Functions Reference

Filesystem

Strings

Data Formats

Execution