Chezmoi Dotfile Management Skill

Overview

Chezmoi manages dotfiles and system configuration, syncing them to a Git repository for version control and portability across machines.

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)

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/
• 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!

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

# 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: Commit and push to Git

cd ~/.local/share/chezmoi
git add .
git status  # Review changes
git commit -m "Description of changes"
git push
cd -

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

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

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