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.

⭐4stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026⬇️1downloads

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.
namechezmoi-workflows
descriptionDotfile 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-toolsRead, 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

Chezmoi docs: https://www.chezmoi.io/reference/