Chezmoi Dotfile Management Skill

Overview

Chezmoi manages dotfiles and system configuration, syncing them to a Git repository for version control and portability across machines. This includes ansible playbooks for system package installation.

Key Locations

•Chezmoi source: /Users/trent/.local/share/chezmoi/
•Git repository: https://github.com/trentshaines/dotfiles.git
•Home directory: ~/ (managed files)
•Config directory: ~/.config/ (managed files)
•Ansible playbooks: ~/ansible/ (managed via chezmoi)

Managed Files

Important files tracked by chezmoi (in source directory):

Dotfiles

•dot_zshrc → ~/.zshrc
•dot_tmux.conf → ~/.tmux.conf
•dot_gitconfig → ~/.gitconfig
•dot_gitignore_global → ~/.gitignore_global
•dot_fzf.zsh → ~/.fzf.zsh
•dot_ideavimrc → ~/.ideavimrc
•dot_aerospace.toml → ~/.aerospace.toml

Directories

•dot_config/ → ~/.config/ (includes tmuxinator, gh, etc.)
•dot_claude/ → ~/.claude/ (skills, settings, etc.)
•dot_cursor/ → ~/.cursor/
•dot_local/ → ~/.local/
•ansible/ → ~/ansible/ (ansible playbooks for package installation)
•private_Documents/ → ~/Documents/ (private, encrypted)
•private_Library/ → ~/Library/ (private, encrypted)

Common Commands

User's Aliases (from ~/.zshrc)

bash

cadd      # chezmoi re-add (sync changes back to source)
capply    # chezmoi apply (apply changes from source to home)

CRITICAL: `add` vs `re-add`

This is the most important distinction:

•chezmoi add <file> - Add a NEW file that's NOT YET managed by chezmoi
•chezmoi re-add <file> - Update an EXISTING file that's ALREADY managed
•chezmoi re-add <directory> - Update directory AND pick up new files within it

How to know which to use:

bash

chezmoi managed | grep filename   # If it shows up → use re-add
                                  # If it doesn't → use add

SHORTCUT for managed directories:

If the parent directory is already managed, re-add on the directory picks up new files!

bash

# These directories are ALREADY managed:
chezmoi re-add ~/.claude/skills/          # Picks up new AND modified skills
chezmoi re-add ~/.config/tmuxinator/      # Picks up new AND modified templates

# So you DON'T need 'add' for new skills or templates - just re-add the directory!

IMPORTANT: chezmoi re-add with NO arguments

Running chezmoi re-add without any arguments will re-add ALL modified managed files:

bash

chezmoi re-add    # Re-add everything that changed

When to use this:

•After making multiple config changes across different files
•When you're unsure what you modified
•To catch any manual edits you forgot about

⚠️ CRITICAL: Always check what changed before committing!

bash

chezmoi re-add                    # Re-add all changes
cd ~/.local/share/chezmoi
git status                        # See what files changed
git diff                          # Review the actual changes

Why this matters:

•You might have accidentally modified a managed file
•Ensures you don't commit unwanted changes
•Helps you write accurate commit messages
•Catches any test/debug changes you forgot to revert

Essential Chezmoi Commands

bash

# Sync changes FROM home TO chezmoi source
chezmoi add ~/.new-file           # Add NEW file (first time)
chezmoi re-add ~/.zshrc           # Re-add EXISTING managed file
chezmoi re-add ~/.config/tmuxinator/admin.yml  # Re-add EXISTING config
chezmoi re-add                    # Re-add ALL modified managed files (no args!)

# Apply changes FROM chezmoi source TO home
chezmoi apply                     # Apply all changes
chezmoi apply ~/.zshrc            # Apply specific file

# View changes
chezmoi diff                      # See what would change
chezmoi status                    # See modified files
chezmoi managed                   # List all managed files

# Git operations (in chezmoi source)
chezmoi cd                        # cd to source directory
chezmoi git -- status             # Git status
chezmoi git -- add .              # Git add
chezmoi git -- commit -m "msg"    # Git commit
chezmoi git -- push               # Git push
exit                              # Exit chezmoi source directory

Claude's Recommended Workflow (SIMPLE & FOOLPROOF)

When you modify or create config files, use this workflow:

bash

# Step 1: Re-add managed directories or files
chezmoi re-add ~/.claude/skills/         # For skills (new OR modified)
chezmoi re-add ~/.config/tmuxinator/     # For tmuxinator (new OR modified)
chezmoi re-add ~/.zshrc                  # For individual files

# Step 2: Work directly in the chezmoi source directory
cd ~/.local/share/chezmoi

# Step 3: Use git commands directly
git add .                              # Stage everything
git status                             # Review what's changed
git commit -m "Descriptive message"    # Commit
git push                               # Push to GitHub

# Step 4: Return to previous directory
cd -

Key insight: For ~/.claude/skills/ and ~/.config/tmuxinator/, just use re-add on the directory - it picks up new AND modified files!

Even simpler alternative (when unsure):

bash

# Just work directly in the chezmoi source!
cd ~/.local/share/chezmoi
git add .
git status    # See what changed
git commit -m "Update configs"
git push
cd -

This avoids confusion about add vs re-add since git will show you exactly what changed.

Typical Workflow After Config Changes

When Claude (or the user) modifies a config file like ~/.zshrc, ~/.config/tmuxinator/admin.yml, or any other managed file:

Step 1: Sync the file to chezmoi source

bash

# For NEW files (not yet managed):
chezmoi add ~/.config/tmuxinator/config.yml

# For EXISTING managed files:
chezmoi re-add ~/.zshrc
chezmoi re-add ~/.config/tmuxinator/admin.yml

Step 2: Check for unexpected changes and commit

bash

cd ~/.local/share/chezmoi
git status  # ⚠️ ALWAYS check what files changed
git diff    # Review the actual changes (optional but recommended)
git add .
git commit -m "Description of changes"
git push
cd -

⚠️ IMPORTANT: Always run git status before committing to catch:

•Unintended modifications to managed files
•Leftover test/debug changes
•Files you modified but forgot about

Claude's Responsibility

IMPORTANT: After making ANY configuration changes to managed files, Claude should:

•
✅ Inform the user that changes were made to a managed file

•

✅ Prompt the user if they want to sync to chezmoi:

code

I've updated ~/.zshrc. Would you like me to sync this to your dotfiles repo?
This involves:
1. chezmoi re-add ~/.zshrc
2. Commit and push to github.com/trentshaines/dotfiles

•
✅ Offer global re-add option when appropriate:
- •If multiple files were changed, or
- •If there might be other uncommitted changes, or
- •After syncing specific files
Ask: "Would you like to run chezmoi re-add (no args) to sync ALL modified managed files?"

This is useful because:
- •It catches any other changes the user made manually
- •It's simpler than specifying individual files
- •It ensures everything is in sync
•
⚠️ Wait for user confirmation before running chezmoi commands
•
✅ If user confirms, execute the re-add and git workflow
•
⚠️ ALWAYS check git status before committing:
bash
```
cd ~/.local/share/chezmoi
git status  # Show user what files changed
```
- •If unexpected files appear, inform the user
- •Ask if they want to review changes with git diff
- •Only proceed with commit if changes look correct

Example Prompt Template

After modifying a config file:

code

Updated: ~/.config/tmuxinator/admin.yml

Would you like to sync this change to your dotfiles repo?
- Run: chezmoi re-add ~/.config/tmuxinator/admin.yml
- Commit and push to github.com/trentshaines/dotfiles.git

Chezmoi File Naming Convention

Chezmoi uses special prefixes in the source directory:

•
dot_ → . (hidden files)
- •Example: dot_zshrc → ~/.zshrc
- •Example: dot_config/ → ~/.config/
•
private_ → Private files (can be encrypted)
- •Example: private_Documents/ → ~/Documents/
•
Combined: private_dot_ → Private hidden files
- •Example: private_dot_ssh/ → ~/.ssh/

Checking What's Managed

bash

chezmoi managed                   # List all managed files
chezmoi managed | grep tmux       # Find tmux-related managed files

Ansible Playbooks

Overview

Ansible playbooks in ~/ansible/ define system package installation and configuration. These are managed by chezmoi and synced to the dotfiles repo.

Location

•~/ansible/playbooks/packages.yml - Main package installation playbook

What It Installs

•Homebrew packages (formulae and casks)
•Homebrew taps (custom repositories)
•Oh My Zsh (if not already installed)
•TPM (Tmux Plugin Manager)
•npm global packages (like Claude Code)

Running the Playbook

bash

cd ~/ansible
ansible-playbook playbooks/packages.yml

After Modifying Ansible Playbooks

bash

# Option 1: Re-add ansible directory
chezmoi re-add ~/ansible/

# Option 2: Re-add specific playbook
chezmoi re-add ~/ansible/playbooks/packages.yml

# Then commit and push
cd ~/.local/share/chezmoi
git add ansible/
git commit -m "Update ansible packages playbook"
git push
cd -

Common Ansible Modifications

•Adding new brew packages: Add to name: list under Install brew formulae
•Adding new casks: Add to name: list under Install brew casks
•Adding new taps: Add to name: list under Add brew taps
•Adding new tasks: Add new task blocks for additional setup steps

Common Scenarios

1. Modified an existing dotfile (e.g., .zshrc)

bash

chezmoi re-add ~/.zshrc           # Re-add existing managed file
cd ~/.local/share/chezmoi
git add .
git commit -m "Update zshrc: describe changes"
git push
cd -

2. Created NEW tmuxinator template

bash

# EASY: Just re-add the directory (it's already managed!)
chezmoi re-add ~/.config/tmuxinator/
cd ~/.local/share/chezmoi
git add .
git commit -m "Add new tmuxinator template: newtemplate"
git push
cd -

3. Created NEW Claude skill

bash

# EASY: Just re-add the directory (it's already managed!)
chezmoi re-add ~/.claude/skills/
cd ~/.local/share/chezmoi
git add .
git status                                # Verify the new files
git commit -m "Add my-skill Claude skill"
git push
cd -

4. Modified multiple existing config files

bash

chezmoi re-add                    # Re-add all changed managed files
cd ~/.local/share/chezmoi
git add .
git status                        # Review all changes
git commit -m "Update multiple configs"
git push
cd -

5. Mixed: new skills + modified configs (EASIEST)

bash

# Re-add managed directories (picks up new AND modified files)
chezmoi re-add ~/.claude/skills/
chezmoi re-add ~/.config/tmuxinator/

# Re-add individual modified files
chezmoi re-add ~/.zshrc

# Then commit everything
cd ~/.local/share/chezmoi
git add .
git status  # Review everything
git commit -m "Add new skills and update existing configs"
git push
cd -

6. Modified ansible playbook

bash

chezmoi re-add ~/ansible/playbooks/packages.yml
cd ~/.local/share/chezmoi
git add ansible/
git commit -m "Add fd, btop, oh-my-zsh, TPM, and Claude Code to ansible"
git push
cd -

7. Want to see what changed

bash

chezmoi diff                      # See what would change
cd ~/.local/share/chezmoi && git status  # See what's uncommitted

Files NOT Managed by Chezmoi

Some config files are NOT tracked (check .chezmoiignore):

•Temporary files
•Cache directories
•Machine-specific configs (if marked)
•Secrets (should use encrypted templates)

Best Practices

•Always re-add after editing: Run chezmoi re-add <file> after modifying managed files
•Commit frequently: Keep dotfiles repo up to date with descriptive commits
•Review diffs: Use chezmoi diff before applying to see what will change
•Test changes: Modify in home directory first, test, then re-add to chezmoi
•Use meaningful commit messages: Describe what changed and why

Troubleshooting

File not syncing?

•Check if it's managed: chezmoi managed | grep filename
•Check .chezmoiignore for exclusions
•Ensure you used chezmoi re-add after editing

Conflicts between source and home?

bash

chezmoi diff        # See differences
chezmoi apply -v    # Apply with verbose output
chezmoi re-add      # Or re-add to update source

Lost changes?

•Source of truth is in ~/.local/share/chezmoi/
•Git history: chezmoi cd && git log
•Can recover from Git history if needed

Integration with Other Tools

•tmuxinator: Templates in ~/.config/tmuxinator/ are managed
•Claude skills: Skills in ~/.claude/skills/ are managed via dot_claude/
•zsh: .zshrc is managed as dot_zshrc
•git: .gitconfig is managed as dot_gitconfig

Security Note

•Private files use private_ prefix
•Sensitive data should be encrypted (chezmoi supports encryption)
•Never commit secrets in plain text
•Use chezmoi templates for machine-specific values

Chezmoi Dotfile Management Skill

Overview

Key Locations

Managed Files

Dotfiles

Directories

Common Commands

User's Aliases (from ~/.zshrc)

CRITICAL: add vs re-add

Essential Chezmoi Commands

Claude's Recommended Workflow (SIMPLE & FOOLPROOF)

Typical Workflow After Config Changes

Step 1: Sync the file to chezmoi source

Step 2: Check for unexpected changes and commit

Claude's Responsibility

Example Prompt Template

Chezmoi File Naming Convention

Checking What's Managed

Ansible Playbooks

Overview

Location

What It Installs

Running the Playbook

After Modifying Ansible Playbooks

Common Ansible Modifications

Common Scenarios

1. Modified an existing dotfile (e.g., .zshrc)

2. Created NEW tmuxinator template

3. Created NEW Claude skill

4. Modified multiple existing config files

5. Mixed: new skills + modified configs (EASIEST)

6. Modified ansible playbook

7. Want to see what changed

Files NOT Managed by Chezmoi

Best Practices

Troubleshooting

File not syncing?

Conflicts between source and home?

Lost changes?

Integration with Other Tools

Security Note

CRITICAL: `add` vs `re-add`