AgentSkillsCN

chezmoi

使用chezmoi管理dotfiles——一款基于源码状态模型的跨平台dotfile管理工具。 适用场景：(1) 在处理chezmoi配置、设置或仓库结构时；(2) 管理文件、模板或脚本（Go模板语法、run_once_/run_onchange_脚本、.chezmoidata）；(3) 处理文件属性（软链接、权限、加密、外部来源）；(4) 排查chezmoi相关操作中的问题，或深入了解应用执行顺序。

SKILL.md
--- frontmatter
name: chezmoi
description: |
  Manage dotfiles with chezmoi - a cross-platform dotfile manager using a source-state model.
  Use when: (1) Working with chezmoi configuration, setup, or repo structure, (2) Managing files,
  templates, or scripts (Go template syntax, run_once_/run_onchange_ scripts, .chezmoidata),
  (3) Handling file attributes (symlinks, permissions, encryption, external sources),
  (4) Troubleshooting chezmoi operations or understanding application order.

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

bash
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

Handling Externally-Modified Files

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

bash
# 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

bash
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