chezmoi-workflows
Dotfile backup, sync, and version control with chezmoi. Tracks shell configs (.zshrc, .bashrc, .zshenv), git (.gitconfig), editors (helix, vim, nvim), terminal tools (broot, starship, alacritty, kitty, wezterm), and XDG .config/ files. Operations include track, add, sync, push, pull, backup, restore, status, diff, re-add. Setup for chezmoi init, dotfiles remote, GitHub private repository, cross-machine sync, multi-account SSH. Handles merge conflicts, secret detection, Go templates.
When & Why to Use This Skill
This Claude skill provides a comprehensive workflow for managing dotfiles using chezmoi, enabling seamless backup, synchronization, and version control of development environments. It automates the tracking of shell configurations, editor settings, and terminal tools across multiple machines via GitHub. By leveraging chezmoi's powerful templating and secret detection, it ensures a consistent and secure setup for developers across different operating systems.
Use Cases
- Cross-Machine Synchronization: Keep your shell (Zsh, Bash), editor (Vim, Neovim, Helix), and terminal (Alacritty, Kitty) configurations identical across work and personal computers.
- Automated Environment Bootstrapping: Quickly set up a fresh Linux or macOS installation by cloning and applying your personal dotfiles repository from GitHub.
- Configuration Version Control: Track changes to complex configuration files with full Git history, allowing you to diff, revert, and manage updates with confidence.
- Secure Secret Management: Handle sensitive information within configuration files using chezmoi's secret detection and Go templates to prevent accidental exposure in public repositories.
- Conflict Resolution: Efficiently manage and resolve merge conflicts when updating configurations from multiple sources or machines.
| name | chezmoi-workflows |
|---|---|
| description | Dotfile backup, sync, and version control with chezmoi. Tracks shell configs (.zshrc, .bashrc, .zshenv), git (.gitconfig), editors (helix, vim, nvim), terminal tools (broot, starship, alacritty, kitty, wezterm), and XDG .config/ files. Operations include track, add, sync, push, pull, backup, restore, status, diff, re-add. Setup for chezmoi init, dotfiles remote, GitHub private repository, cross-machine sync, multi-account SSH. Handles merge conflicts, secret detection, Go templates. |
| allowed-tools | Read, Edit, Bash |
Chezmoi Workflows
Architecture
| Component | Location | Purpose |
|---|---|---|
| Source | $(chezmoi source-path) |
Git repository with dotfile templates |
| Target | ~/ |
Home directory (deployed files) |
| Remote | GitHub (private recommended) | Cross-machine sync and backup |
| Config | ~/.config/chezmoi/chezmoi.toml |
User preferences and settings |
1. Status Check
chezmoi source-path # Show source directory
chezmoi git -- remote -v # Show GitHub remote
chezmoi status # Show drift between source and target
chezmoi managed | wc -l # Count tracked files
2. Track File Changes
After editing a config file, add it to chezmoi:
chezmoi status # 1. Verify file shows as modified
chezmoi diff ~/.zshrc # 2. Review changes
chezmoi add ~/.zshrc # 3. Add to source (auto-commits if configured)
chezmoi git -- log -1 --oneline # 4. Verify commit created
chezmoi git -- push # 5. Push to remote
3. Track New File
Add a previously untracked config file:
chezmoi add ~/.config/app/config.toml # 1. Add file to source
chezmoi managed | grep app # 2. Verify in managed list
chezmoi git -- push # 3. Push to remote
4. Sync from Remote
Pull changes from GitHub and apply to home directory:
chezmoi update # 1. Pull + apply (single command)
chezmoi verify # 2. Verify all files match source
chezmoi status # 3. Confirm no drift
5. Push All Changes
Bulk sync all modified tracked files to remote:
chezmoi status # 1. Review all drift
chezmoi re-add # 2. Re-add all managed files (auto-commits)
chezmoi git -- push # 3. Push to remote
6. First-Time Setup
Install chezmoi
brew install chezmoi # macOS
Initialize (fresh start)
/usr/bin/env bash << 'CONFIG_EOF'
chezmoi init # Create empty source
chezmoi add ~/.zshrc ~/.gitconfig # Add first files
gh repo create dotfiles --private --source="$(chezmoi source-path)" --push
CONFIG_EOF
Initialize (clone existing)
chezmoi init git@github.com:<user>/dotfiles.git
chezmoi apply # Deploy to home directory
7. Configure Source Directory
Move source to custom location (e.g., for multi-account SSH):
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
mv "$(chezmoi source-path)" ~/path/to/dotfiles
SKILL_SCRIPT_EOF
Edit ~/.config/chezmoi/chezmoi.toml:
sourceDir = "~/path/to/dotfiles"
Verify:
chezmoi source-path # Should show new location
8. Change Remote
Switch to different GitHub account or repository:
chezmoi git -- remote -v # View current
chezmoi git -- remote set-url origin git@github.com:<user>/<repo>.git # Change
chezmoi git -- push -u origin main # Push to new remote
9. Resolve Merge Conflicts
/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status # 1. Identify conflicted files
chezmoi git -- diff # 2. Review conflicts
# Manually edit files in $(chezmoi source-path)
chezmoi git -- add <resolved-files> # 3. Stage resolved files
chezmoi git -- commit -m "Resolve merge conflict"
chezmoi apply # 4. Apply to home directory
chezmoi git -- push # 5. Push resolution
GIT_EOF
10. Validation (SLO)
After major operations, verify system state:
chezmoi verify # Exit 0 = all files match source
chezmoi diff # Empty = no drift
chezmoi managed # Lists all tracked files
chezmoi git -- log --oneline -3 # Recent commit history
Reference
- Setup Guide - Installation, multi-account GitHub, migration
- Prompt Patterns - Detailed workflow examples
- Configuration - chezmoi.toml settings, templates
- Secret Detection - Handling detected secrets
Chezmoi docs: https://www.chezmoi.io/reference/