Working With Chezmoi

Working with Chezmoi

Core Principle

Chezmoi manages dotfiles with a git-backed source directory. Always check for templates first, work with the source, understand prefix mappings, and follow the conflict resolution workflow to avoid losing changes.

CRITICAL: Check for Templates FIRST

Before editing ANY config file:

# Check if file is templated:
ls -la ~/.local/share/chezmoi/[prefix_mapped_name]*

If .tmpl exists:

• Edit the template source, NOT the generated file
• NEVER use chezmoi add (removes template attribute)
• Copy directly: cp ~/file ~/.local/share/chezmoi/prefix_mapped_name.tmpl

Why this matters:

• Editing generated file when .tmpl exists → changes overwritten on next apply
• Using chezmoi add on templates → loses template logic permanently
• Templates contain variables like {{ .chezmoi.hostname }} that must be preserved

Quick Reference: Prefix Mappings

Pattern:

• . → dot_
• Private/sensitive → private_ prefix
• Executable scripts → executable_ prefix
• Templated files → .tmpl suffix

Chezmoi source location: ~/.local/share/chezmoi/

Common Claude Hooks

Valid hook names (cannot create arbitrary names):

• SessionStart - runs at session start
• stop-notification.sh - custom notification hooks

These are specific hook types, not arbitrary filenames.

Standard Editing Workflow

For any config file edit:

1. Check if templated FIRST: ls ~/.local/share/chezmoi/prefix_mapped_name*
2. Edit correct source: Template if exists, otherwise edit local file
3. Copy to source: cp ~/file ~/.local/share/chezmoi/prefix_mapped_name
4. Verify changes: chezmoi diff
5. Commit locally: cd ~/.local/share/chezmoi && git add -A && git commit -m "msg"
6. Push: git push

Conflict Resolution Workflow

When working with config files that may have local drift + remote changes:

Step 1: Capture Local Drift (BEFORE pulling)

chezmoi status
# Shows files modified locally vs chezmoi source
# MM = modified in both local and source
# M  = modified in source only

For each modified file:

• Decide: keep local changes or discard?
• If keeping: cp ~/actual-file ~/.local/share/chezmoi/prefix_mapped_name
• Verify: chezmoi diff shows expected changes

Commit local changes:

cd ~/.local/share/chezmoi
git add -A
git commit -m "Capture local config changes"
# Don't push yet

Step 2: Pull Remote Changes

cd ~/.local/share/chezmoi
git pull --rebase
# Handle any git conflicts in source files if needed

Step 3: Review What Would Apply

chezmoi diff
# Shows what would change if you apply chezmoi now

For each file in diff:

• Remote version better? → Will apply in step 4
• Local version better? → Already committed in step 1
• Need to merge? → Edit source file, commit again

Step 4: Apply or Override

If remote changes are good:

chezmoi apply

If local changes should override remote:

• Already committed in step 1
• Just push (step 5)

If need to merge:

• Edit source file: ~/.local/share/chezmoi/prefix_mapped_name
• Commit: cd ~/.local/share/chezmoi && git add file && git commit -m "Merge local and remote changes"

Step 5: Push Everything

cd ~/.local/share/chezmoi
git push

Now all machines get the resolved state.

Common Mistakes

Red Flags - STOP and Check

• About to use chezmoi add → Check if file is templated first
• About to edit dotfile → Check if .tmpl version exists first
• User says "quick" → Still check for templates, don't skip steps
• Can't find file in source → Check prefix mapping table

When to Use This Skill

Trigger this skill when:

• Editing ANY file in ~/.config/, ~/.ssh/, dotfiles like .zshrc, .claude/
• User mentions "chezmoi", "dotfiles", "sync configs"
• Before running chezmoi status, chezmoi diff, chezmoi apply
• Pulling updates from another machine
• Adding new config files to chezmoi

Don't use for:

• Files in project directories (~/Code/*) unless already managed by chezmoi (like ~/Code/CLAUDE.md)
• Temporary files or caches