Chezmoi Configuration Management

Comprehensive guide for managing chezmoi dotfiles with templates, scripts, external resources, and advanced configurations.

⚠️ Safety Constraints

This skill is READ-ONLY and validation-only. It MUST NOT modify your actual environment.

Forbidden Operations

NEVER execute these commands - they will modify your system:

• chezmoi apply - Applies changes to your home directory
• chezmoi apply --force - Forcefully applies changes
• chezmoi update - Updates source state and may change managed files
• Any operations that directly execute scripts (scripts run automatically during chezmoi apply)

Allowed Safe Operations

ONLY use these read-only validation commands:

• chezmoi diff - Preview what would change (safe)
• chezmoi apply --dry-run - Simulate changes without applying (safe)
• chezmoi doctor - Check configuration validity (safe)
• chezmoi data - Display template data variables (safe)
• chezmoi managed - List files currently managed by chezmoi (read-only, safe)
• chezmoi unmanaged - List files currently unmanaged by chezmoi (read-only, safe)
• chezmoi ignored - List files ignored by chezmoi (read-only, safe)
• chezmoi execute-template < file.tmpl - Preview expanded template output (safe)
• chezmoi state dump - View script execution state (safe)
• chezmoi verify - Verify source state integrity (safe)
• chezmoi cd - Enter source directory (safe)
• chezmoi source-path - Show source directory path (safe)

User Responsibility

This skill helps you create and validate chezmoi configurations. To apply changes, you must manually run chezmoi apply in your terminal after reviewing the output.

Quick Start

Creating a New Template

1. Add existing file as template:

   chezmoi add --template ~/.gitconfig
   

2. Or create manually:

   chezmoi cd
   $EDITOR dot_gitconfig.tmpl
   

3. Use Go template syntax:

   [user]
       name = {{ .name }}
   {{- if eq .chezmoi.os "darwin" }}
   [credential]
       helper = osxkeychain
   {{- end }}
   

Managing External Resources

Create .chezmoiexternal.toml.tmpl:

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

Writing Scripts

Create run_onchange_install-packages.sh.tmpl:

{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash
brew install git vim ripgrep
{{ end -}}

Reference Documentation

This skill includes comprehensive reference documentation. Consult these guides for detailed information:

• template-syntax.md - Go template syntax, variables, conditionals, loops, and examples
• external-files.md - .chezmoiexternal configuration for files, archives, and git repositories
• ignore-files.md - .chezmoiignore/.chezmoiignore.tmpl patterns, templates, and scope
• password-managers.md - Integrating 20+ password managers (1Password, Bitwarden, Vault, etc.)
• scripts.md - run_once, run_onchange, run_before, run_after scripts
• advanced-configuration.md - .chezmoi.toml, prompting, encryption, and advanced features

Common Tasks

1. Create Platform-Specific Configuration

Template file (dot_gitconfig.tmpl):

[user]
    name = {{ .name }}
    email = {{ .email }}

{{- if eq .chezmoi.os "darwin" }}
[credential]
    helper = osxkeychain
{{- else if eq .chezmoi.os "linux" }}
[credential]
    helper = cache
{{- end }}

Configuration (chezmoi.toml):

[data]
    name = "John Doe"
    email = "john@example.com"

2. Manage Secrets with Password Managers

{{- if (bitwarden "github") }}
[github]
    token = {{ (bitwarden "github").login.password }}
{{- end }}

3. Install Packages Conditionally

run_onchange_install-packages.sh.tmpl:

{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash
brew bundle --file=/dev/stdin <<EOF
{{ range .packages.darwin.brews -}}
brew "{{ . }}"
{{ end -}}
EOF
{{ else if eq .chezmoi.os "linux" -}}
#!/bin/bash
sudo apt install -y {{ range .packages.linux }}{{ . }} {{ end }}
{{ end -}}

.chezmoidata/packages.yaml:

darwin:
  brews:
    - git
    - vim
    - ripgrep

linux:
  - git
  - vim
  - ripgrep
  - fd-find

4. Include External Resources

.chezmoiexternal.toml.tmpl:

[".vim/autoload/plug.vim"]
    type = "file"
    url = "https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim"

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

[".local/bin/age"]
    type = "archive-file"
    url = "https://github.com/FiloSottile/age/releases/download/v1.1.1/age-v1.1.1-{{ .chezmoi.os }}-{{ .chezmoi.arch }}.tar.gz"
    path = "age/age"
    executable = true

5. Configure Interactive Prompts

.chezmoi.toml.tmpl:

{{- $editor := promptChoice "favorite editor" ["vim" "neovim" "vscode"] -}}
[data]
    name = "{{ promptString "your name" }}"
    email = "{{ promptString "your email" }}"
    editor = {{ $editor }}

{{ if promptBool "enable work config?" -}}
[data.work]
    enabled = true
    work_email = "{{ promptString "work email" }}"
{{ end }}

6. Ignore Files Conditionally

.chezmoiignore (template-aware):

README.md
*.log

{{- if ne .chezmoi.hostname "work-laptop" }}
.work
{{- end }}

{{- if eq .chezmoi.os "windows" }}
Documents/*
!Documents/*PowerShell/
{{- end }}

7. Interpret chezmoi managed / chezmoi unmanaged Output (Config Files)

When reviewing chezmoi unmanaged, note that the destination config file is ~/.config/chezmoi/chezmoi.toml, while the source is typically managed as a template such as dot_config/chezmoi/chezmoi.toml.tmpl (or private_dot_config/chezmoi/chezmoi.toml.tmpl) in the chezmoi source state.

If ~/.config/chezmoi appears as unmanaged:

• First check chezmoi managed to confirm whether the config file is already managed in source.
• If it is not managed, add it as a template and manage it in source (recommended when you maintain machine-specific values in chezmoi.toml).

8. Manage run_once Scripts

run_once_000-bootstrap.sh.tmpl:

#!/bin/bash
{{ if eq .chezmoi.os "darwin" -}}
if ! command -v brew &> /dev/null; then
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi
{{ end -}}

Reset run_once state:

# Clear all run_once script state
chezmoi state delete-bucket --bucket=scriptState

Built-in Variables

Commonly used chezmoi variables available in all templates:

Variable	Description	Example
.chezmoi.os	Operating system	linux, darwin, windows
.chezmoi.arch	Architecture	amd64, arm64
.chezmoi.hostname	Machine hostname	my-laptop
.chezmoi.username	Current user	john
.chezmoi.homeDir	Home directory	/home/john
.chezmoi.sourceDir	Source state directory	/home/john/.local/share/chezmoi
.chezmoi.env.VAR	Environment variables	.chezmoi.env.EDITOR

Template Syntax Reference

Conditionals

{{ if eq .chezmoi.os "darwin" }}
# macOS-specific
{{ else if eq .chezmoi.os "linux" }}
# Linux-specific
{{ end }}

Loops

{{ range .packages.darwin.brews -}}
brew "{{ . }}"
{{ end -}}

String Operations

{{ .name | quote }}          # Add quotes
{{ .chezmoi.homeDir }}        # No trimming
{{- "content" -}}            # Trim whitespace

Best Practices

1. Use templates for cross-platform configs - Leverage .chezmoi.os, .chezmoi.arch
2. Store secrets in password managers - Never hardcode sensitive data
3. Make scripts idempotent - Safe to run multiple times
4. Use descriptive filenames - run_once_000-bootstrap.sh.tmpl
5. Test templates locally - Use chezmoi execute-template < file.tmpl
6. Organize .chezmoidata - Separate concerns into multiple files
7. Document dependencies - Comment complex configurations
8. Use appropriate refresh periods - Balance freshness and bandwidth

Consulting Latest Documentation

This skill can consult the latest chezmoi documentation via Context7 to ensure accuracy:

# When in doubt, ask for the latest docs
"Check the chezmoi documentation for [topic]"

If the question involves .tmpl behavior (especially .chezmoiignore{,.tmpl}), prefer checking the official docs first.

Useful Commands

# ⚠️ FORBIDDEN - Apply all changes (must run manually)
chezmoi apply

# Dry run (preview changes) - SAFE
chezmoi apply --dry-run

# ⚠️ FORBIDDEN - Update source state (may change managed files)
chezmoi update

# Edit source state - SAFE
chezmoi cd

# Add file as template - SAFE
chezmoi add --template ~/.config/file

# Verify configuration - SAFE
chezmoi doctor

# View all template data - SAFE
chezmoi data

# List ignored files - SAFE
chezmoi ignored

# Test template (preview output) - SAFE
chezmoi execute-template < ~/.local/share/chezmoi/dot_file.tmpl

# View run_once state - SAFE
chezmoi state dump

# Clear run_once script state (use with caution) - SAFE
chezmoi state delete-bucket --bucket=scriptState

# Clear run_onchange script state (use with caution) - SAFE
chezmoi state delete-bucket --bucket=entryState

# See what would change - SAFE
chezmoi diff

# Verify files match expected state - SAFE
chezmoi verify

File Structure

Standard chezmoi source state structure:

~/.local/share/chezmoi/
├── .chezmoi.toml.tmpl          # Main configuration (optional)
├── .chezmoiexternal.toml.tmpl   # External resources (optional)
├── .chezmoiignore.tmpl          # Ignore rules (template-aware, optional)
├── .chezmoidata/
│   ├── packages.yaml            # Custom data
│   └── work.yaml
├── dot_gitconfig.tmpl           # Regular templates
├── dot_zshrc.tmpl
├── run_once_000-bootstrap.sh.tmpl
├── run_onchange_install-packages.sh.tmpl
└── run_after_dot_vimrc.sh.tmpl

Debugging

注意：调试时也不要执行 chezmoi update，如需检查变更请用 chezmoi diff 或 chezmoi apply --dry-run。

Verbose output:

chezmoi apply --verbose

Check what would change:

chezmoi diff

Validate configuration:

chezmoi doctor

See expanded template:

chezmoi execute-template < template-file

When to Use This Skill

Use this skill whenever you're:

• Creating new chezmoi templates with Go syntax
• Modifying existing .chezmoi configuration files
• Managing .chezmoiignore/.chezmoiignore.tmpl rules
• Setting up .chezmoiexternal for external resources
• Writing run_once/run_onchange scripts
• Integrating password managers for secrets
• Managing cross-platform dotfiles
• Debugging template issues
• Organizing .chezmoidata files

For specific concerns, refer to the detailed reference documentation listed above.