home / skills / gwenwindflower / .charmschool / chezmoi

chezmoi skill

This skill helps you manage and troubleshoot dotfiles with chezmoi by guiding source, destination, and target states and apply workflow.

npx playbooks add skill gwenwindflower/.charmschool --skill chezmoi

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

3.9 KB

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

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

## 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](./references/templates.md).

## Scripts

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

## Hooks

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

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

- [Attributes](./references/attributes.md) - Source state prefixes/suffixes
- [Target types](./references/target-types.md) - Files, directories, symlinks, scripts
- [Special files](./references/special-files.md) - `.chezmoi*` files and directories
- [Application order](./references/application-order.md) - Execution flow during apply
- [Hooks](./references/hooks.md) - Command hooks configuration
- [Templates](./references/templates.md) - Template syntax and functions
- [Scripts](./references/scripts.md) - Script patterns and examples

Overview

This skill helps you manage dotfiles with chezmoi, a cross-platform source-state dotfile manager. It focuses on configuring the source directory, controlling file attributes, writing templates and scripts, and applying changes safely to your home directory. Use it to inspect, modify, and troubleshoot chezmoi repositories and operations.

How this skill works

The skill interprets chezmoi concepts: source (declared files), target (desired state), and destination (your home). It explains filename attributes, target types (files, symlinks, directories, scripts), templates (Go text/template with sprig), scripts (.chezmoiscripts), hooks, and external sources. It also shows common commands for init, add, diff, apply, doctor, and debug flows, and clarifies application order (before scripts → file updates → after scripts).

When to use it

Setting up or initializing a chezmoi source directory
Adding, editing, or removing managed files and symlinks
Writing or debugging templates and sprig functions (.tmpl files)
Creating and ordering run_once_/run_onchange_ scripts in .chezmoiscripts
Configuring file attributes (dot_, private_, executable_, encryption) and special files
Troubleshooting apply failures, dry runs, or metadata/state issues

Best practices

Keep source under ~/.local/share/chezmoi and use clear attribute prefixes to encode behavior
Prefer symlink templates for apps that modify their own config to prevent divergence
Use chezmoi diff and apply -n -v for safe, verbose dry runs before making changes
Name and order scripts using run_[once_|onchange_][before_|after_]<order>-<name> to guarantee predictable execution
Store reusable data in .chezmoidata and test templates with chezmoi execute-template
Use chezmoi doctor and state commands to diagnose and reset script-run state if needed

Example use cases

Move an application config into chezmoi, ignore the original, and create a symlink template so the app can update it normally
Add a private executable script with private_executable_ prefix and verify permissions are preserved on apply
Create a template that inserts OS-specific content using .chezmoi.os and sprig functions, then preview with chezmoi execute-template
Write a run_once_before_10-bootstrap.sh.tmpl script to provision tools before dotfiles are written
Pull external snippets via .chezmoiexternal.yaml and refresh them with chezmoi apply -R

FAQ

How can I stop a script from running again?

Use run_once_ prefix for scripts; to reset tracking, run chezmoi state delete-bucket for the script bucket.

How do I manage configs that external programs modify?

Move the live config into your source, add it to .chezmoiignore, and create a symlink template pointing to the source copy.

What order does chezmoi follow during apply?

Chezmoi runs before scripts first, then updates files and targets, then runs after scripts; use ordering prefixes to control sequencing.