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

Add existing file as template:
bash
```
chezmoi add --template ~/.gitconfig
```
Or create manually:
bash
```
chezmoi cd
$EDITOR dot_gitconfig.tmpl
```

Use Go template syntax:

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

Managing External Resources

Create

.chezmoiexternal.toml.tmpl

toml

[".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

bash

{{ 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):

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:

bash

{{ 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:

yaml

darwin:
  brews:
    - git
    - vim
    - ripgrep

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

4. Include External Resources

.chezmoiexternal.toml.tmpl:

toml

[".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:

toml

{{- $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):

text

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.

~/.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:

bash

#!/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:

bash

# 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

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

Consulting Latest Documentation

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

bash

# 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

bash

# ⚠️ 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:

bash

chezmoi apply --verbose

Check what would change:

bash

chezmoi diff

Validate configuration:

bash

chezmoi doctor

See expanded template:

bash

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.

chezmoi-config

NPX Install

Tags

SKILL.md Content

Chezmoi Configuration Management

⚠️ Safety Constraints

Forbidden Operations

Allowed Safe Operations

User Responsibility

Quick Start

Creating a New Template

Managing External Resources

Writing Scripts

Reference Documentation

Common Tasks

1. Create Platform-Specific Configuration

2. Manage Secrets with Password Managers

3. Install Packages Conditionally

4. Include External Resources

5. Configure Interactive Prompts

6. Ignore Files Conditionally

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

8. Manage run_once Scripts

Built-in Variables

Template Syntax Reference

Conditionals

Loops

String Operations

Best Practices

Consulting Latest Documentation

Useful Commands

File Structure

Debugging

When to Use This Skill

chezmoi-config

NPX Install

Tags

SKILL.md Content

Chezmoi Configuration Management

⚠️ Safety Constraints

Forbidden Operations

Allowed Safe Operations

User Responsibility

Quick Start

Creating a New Template

Managing External Resources

Writing Scripts

Reference Documentation

Common Tasks

1. Create Platform-Specific Configuration

2. Manage Secrets with Password Managers

3. Install Packages Conditionally

4. Include External Resources

5. Configure Interactive Prompts

6. Ignore Files Conditionally

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

8. Manage run_once Scripts

Built-in Variables

Template Syntax Reference

Conditionals

Loops

String Operations

Best Practices

Consulting Latest Documentation

Useful Commands

File Structure

Debugging

When to Use This Skill

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