Chezmoi Workflows When to Use This Skill Use this skill when: Backing up dotfiles to Git repository Syncing configuration files across machines Tracking changes to shell configs, editor settings, or other dotfiles Managing templated configurations with chezmoi Troubleshooting dotfile drift between source and target 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

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

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

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

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

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

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

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

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

1. Forget (Untrack) a File Stop tracking a file without deleting it from home directory: chezmoi managed | grep config.local

1. Confirm file is tracked

chezmoi forget --force ~/.config/app/config.local.toml

2. Remove from source (--force skips TTY prompt)

chezmoi git -- push

3. Push removal to remote

ls ~/.config/app/config.local.toml

4. Verify file still exists in home

When to use

Machine-specific configs, files with secrets that shouldn't be synced, files accidentally added. 12. Template Management Create OS/architecture-conditional configs using Go templates: Convert existing file to template chezmoi add --template ~/.config/app/config.toml

1. Add as template (creates .tmpl suffix in source)

chezmoi edit ~/.config/app/config.toml

2. Edit template in $EDITOR (helix)

chezmoi diff ~/.config/app/config.toml

3. Preview what would change

chezmoi apply ~/.config/app/config.toml

4. Apply rendered template to home

Common template patterns

OS-conditional block

{{ if eq .chezmoi.os "darwin" -}} export HOMEBREW_PREFIX="/opt/homebrew" {{ else if eq .chezmoi.os "linux" -}} export HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew" {{ end -}}

Architecture-conditional

{{ if eq .chezmoi.arch "arm64" -}} ARCH="aarch64" {{ else -}} ARCH="x86_64" {{ end -}}

Custom data from chezmoi.toml [data] section

git_name = "{{ .git.name }}" git_email = "{{ .git.email }}"

1Password secret (requires op CLI)

api_key = {{ onepasswordRead "op://Vault/Item/Field" }} Verify template renders correctly chezmoi execute-template < " $( chezmoi source-path ) /dot_config/app/config.toml.tmpl" chezmoi cat ~/.config/app/config.toml

Show rendered output without applying

1. Safe Update (Diff Before Apply) Pull from remote with review step — safer than blind chezmoi update : chezmoi git -- pull

1. Pull source changes only (no apply)

chezmoi diff

2. Review what WOULD change in home directory

chezmoi apply --dry-run --verbose

3. Dry run — shows actions without executing

chezmoi apply

4. Apply after review

chezmoi status

5. Confirm clean state

When to use

When pulling changes made on another machine, or after a long gap between syncs. Avoids surprise overwrites of local edits. 14. Doctor (Diagnostic) Troubleshoot chezmoi setup and environment: chezmoi doctor

Full diagnostic — checks all components

Key fields to verify : Check Expected Meaning if failing config-file found ~/.config/chezmoi/chezmoi.toml Config missing or wrong path source-dir ~/own/dotfiles is a git working tree (clean) Source dirty or not a git repo git-command found /opt/homebrew/bin/git Git not installed edit-command found /opt/homebrew/bin/hx Editor not configured 1password found /opt/homebrew/bin/op 1Password CLI needed for templates age/gpg info = optional Only needed for encrypted files chezmoi doctor | grep -v "^ok"

Show only warnings and errors

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/ Troubleshooting Issue Cause Solution chezmoi not found Not installed Install via brew install chezmoi Source path empty Not initialized Run chezmoi init Git remote not set Missing GitHub repo Run chezmoi git -- remote add origin URL Apply fails Template error Check template syntax with chezmoi diff Merge conflicts Diverged source and target Use chezmoi merge to resolve Secrets detected Plain text credentials Use chezmoi templates with 1Password/Doppler forget needs TTY Interactive confirmation Use chezmoi forget --force Template not found Missing .tmpl suffix Use chezmoi add --template to create .tmpl