chezmoi

name	chezmoi
description	Manage dotfiles with chezmoi. Use when working with chezmoi config, setup, or repo structure, managing files, templates, or script's (Go template syntax, run_once_/run_onchange_ scripts, .chezmoidata), handling file attributes (symlinks, permissions, encryption, external sources), Troubleshooting chezmoi operations or understanding application order.
license	MIT
allowed-tools	Read, Edit, Write, Glob, Grep, Bash(chezmoi:*)

chezmoi - Cross platform dotfiles manager

Core Principles

• Preview Changes: Always execute chezmoi diff or chezmoi cat <file> before any applying.
• Secret Management: If you find any security concerns, HIGHLIGHT them and suggest improvements or alternatives.

Core Concepts

Three-Tier Architecture

1. Home directory (~) - Your actual dotfiles (destination state)
2. Source directory (~/.local/share/chezmoi/) - Chezmoi's managed files (source state)
3. Remote repository - Git repo for syncing across machines

Source State Encoding

Chezmoi encodes file attributes in filenames:

• dot_bashrc → ~/.bashrc
• private_dot_netrc → ~/.netrc (restricted permissions)
• executable_dot_local/bin/script → ~/.local/bin/script (executable)

Directory Structure

~/.local/share/chezmoi/
├── .chezmoiroot              # Root directory specifier
└──  home/                    # $HOME directory
      ├── .chezmoidata/       # Custom template data
      ├── .chezmoiexternals/  # External resource config
      ├── .chezmoiscripts/    # Script directory
      ├── .chezmoitemplates/  # Reusable partial templates
      ├── .chezmoi.toml.tmpl  # Config template (prompts during init)
      ├── .chezmoiremove.tmpl # Patterns of files to remove on apply
      ├── .chezmoiignore      # Ignore patterns
      └── .chezmoiversion     # Minimum version specifier

References

• Commands: chezmoi commands with usage
• Special Files & Directories: .chezmoi* files and directories control chezmoi behavior.
• Attributes: Prefixes / suffixes on source filenames control behavior (dot_, private_, .tmpl, etc).
• Scripts: Scripts in .chezmoiscripts/ run during apply. Format: run_[once_|onchange_][before_|after_]<order>-<name>.<ext>[.tmpl]
• Templates: Go text/template library syntax used in chezmoi, variables, and functions
• Externals: External resources config in .chezmoiexternals/ which is fetched from URLs, archives, and git repositories
• Secrets: Secret management instructions which have to use encryption or 1Password