chezmoi Dotfile Management

chezmoi manages dotfiles using a three-state model: source (declared in ~/.local/share/chezmoi), destination (current home directory), and target (computed desired state). Running chezmoi apply updates destination to match target.

Quick Reference

chezmoi init                    # Initialize source directory
chezmoi add ~/.bashrc           # Add file to management
chezmoi edit ~/.bashrc          # Edit source file
chezmoi diff                    # Preview changes
chezmoi apply                   # Apply changes to home directory
chezmoi apply -n -v             # Dry run with verbose output
chezmoi cd                      # Enter source directory
chezmoi data                    # Show template variables
chezmoi doctor                  # Diagnose issues
chezmoi managed                 # List managed files

Core Concepts

• Attributes: Prefixes/suffixes on source filenames control behavior (dot_, private_, executable_, .tmpl, etc.). See attributes reference.
• Target types: Files, directories, symlinks, scripts. See target types reference.
• Special files: .chezmoi* files control chezmoi behavior. See special files reference.
• Application order: Before scripts → file updates → after scripts. See application order reference.

Handling Externally-Modified Files

For tools that modify their own configs (Claude Code, VS Code), use symlinks pointing to source:

# 1. Move config to source (without chezmoi prefixes)
mv ~/.config/tool/settings.json ~/.local/share/chezmoi/tool-settings.json

# 2. Ignore the raw file
echo "tool-settings.json" >> ~/.local/share/chezmoi/.chezmoiignore

# 3. Create symlink template
echo '{{ .chezmoi.sourceDir }}/tool-settings.json' > \
  ~/.local/share/chezmoi/symlink_dot_config/tool/settings.json.tmpl

# 4. Apply
chezmoi apply

Templates

Templates use Go text/template with sprig functions. See templates reference.

Scripts

Scripts in .chezmoiscripts/ run during apply. Format: run_[once_|onchange_][before_|after_]<order>-<name>.<ext>[.tmpl]. See scripts reference.

Hooks

Hooks run before/after chezmoi commands (not during apply like scripts). See hooks reference.

External Sources

Pull from git repos/archives via .chezmoiexternal.yaml. Refresh with chezmoi apply -R.

Debugging

chezmoi doctor                                     # Check setup
chezmoi diff                                       # Show pending changes
chezmoi cat ~/.bashrc                              # Show what would be written
chezmoi execute-template '{{ .chezmoi.os }}'       # Test template
chezmoi state delete-bucket --bucket=scriptState  # Reset run_once_ tracking

References

• Attributes - Source state prefixes/suffixes
• Target types - Files, directories, symlinks, scripts
• Special files - .chezmoi* files and directories
• Application order - Execution flow during apply
• Hooks - Command hooks configuration
• Templates - Template syntax and functions
• Scripts - Script patterns and examples