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)

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:

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!

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

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!

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

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

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

# 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

# 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

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:

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

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

   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

3. ✅ 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

4. ⚠️ Wait for user confirmation before running chezmoi commands

5. ✅ If user confirms, execute the re-add and git workflow

6. ⚠️ ALWAYS check git status before committing:

   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:

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

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

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

After Modifying Ansible Playbooks

# 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

1. Adding new brew packages: Add to name: list under Install brew formulae
2. Adding new casks: Add to name: list under Install brew casks
3. Adding new taps: Add to name: list under Add brew taps
4. Adding new tasks: Add new task blocks for additional setup steps

Common Scenarios

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

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

# 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

# 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

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)

# 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

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

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

1. Always re-add after editing: Run chezmoi re-add <file> after modifying managed files
2. Commit frequently: Keep dotfiles repo up to date with descriptive commits
3. Review diffs: Use chezmoi diff before applying to see what will change
4. Test changes: Modify in home directory first, test, then re-add to chezmoi
5. 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?

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