Chezmoi Workflows

Chezmoi Workflows

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

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

---

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

---

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

---

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

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

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Skill: Chezmoi Workflows

Configuration Reference

~/.config/chezmoi/chezmoi.toml:

[edit]
command = "hx"            # Your preferred editor (vim, nvim, code, etc.)
apply = false             # Manual apply after review

[git]
autoadd = true            # Auto-stage changes on chezmoi add
autocommit = true         # Auto-commit on add/apply
autopush = false          # Manual push for review before sync

[add]
secrets = "error"         # Fail-fast on detected secrets

Key Settings:

---

Template Handling

Files ending in .tmpl in source directory are Go templates.

1. Identify Template

/usr/bin/env bash << 'CONFIGURATION_SCRIPT_EOF'
ls "$(chezmoi source-path)/dot_zshrc.tmpl" 2>/dev/null && echo "Is template"
CONFIGURATION_SCRIPT_EOF

2. Edit Template

chezmoi edit ~/.zshrc

Or edit source file directly in $(chezmoi source-path)/.

3. Test Rendering

/usr/bin/env bash << 'CONFIGURATION_SCRIPT_EOF_2'
chezmoi execute-template < "$(chezmoi source-path)/dot_zshrc.tmpl"
CONFIGURATION_SCRIPT_EOF_2

4. Apply to Home

chezmoi apply ~/.zshrc

5. Commit and Push

chezmoi git -- add dot_zshrc.tmpl
chezmoi git -- commit -m "Update zshrc template"
chezmoi git -- push

---

Template Variables

Built-in variables available in .tmpl files:

Custom variables from [data] section:

[data]
[data.git]
  name = "Your Name"
  email = "you@example.com"

Access in templates: {{ .data.git.name }}, {{ .data.git.email }}

---

Conditional Templates

OS-specific configuration:

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

Architecture-specific:

{{ if eq .chezmoi.arch "arm64" -}}
# ARM64 config
{{ end -}}

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Skill: Chezmoi Workflows

Command Reference

Quick reference for chezmoi commands with expected outputs.

---

Status Commands

---

Tracking Commands

---

Sync Commands

---

Git Commands

All git operations use chezmoi git -- prefix for portability:

---

Workflow: Track Changes

chezmoi status                    # 1. Check what changed
chezmoi diff ~/.zshrc             # 2. Review diff
chezmoi add ~/.zshrc              # 3. Add (auto-commits)
chezmoi git -- push               # 4. Push to remote

Workflow: Sync from Remote

chezmoi update                    # 1. Pull + apply
chezmoi verify                    # 2. Verify success

Workflow: Push All Changes

chezmoi re-add                    # 1. Re-add all managed files
chezmoi git -- push               # 2. Push to remote

Workflow: Resolve Conflicts

/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status             # 1. Identify conflicts
# Edit conflicted files in $(chezmoi source-path)
chezmoi git -- add <files>        # 2. Stage resolved
chezmoi git -- commit -m "Resolve conflicts"
chezmoi apply                     # 3. Apply to home
chezmoi git -- push               # 4. Push resolution
GIT_EOF

---

Validation Checklist

After major operations:

chezmoi verify && echo "OK"       # All files match source
chezmoi diff | head               # No unexpected drift
chezmoi git -- status             # No uncommitted changes

Skill: Chezmoi Workflows

Secret Detection

Chezmoi can detect secrets in files before adding them to the repository.

---

Configuration

Enable fail-fast secret detection in ~/.config/chezmoi/chezmoi.toml:

[add]
secrets = "error"    # Fail immediately when secret detected

Options:

• "error" - Fail and abort (recommended)
• "warning" - Warn but continue
• "ignore" - No detection

---

Detection Example

When adding a file containing a secret:

$ chezmoi add ~/.zshrc
chezmoi: ~/.zshrc:42: Uncovered a GCP API key, potentially...

The operation fails immediately. The file is NOT added to the repository.

---

Resolution Options

1. Remove Secret from File

Edit the file to remove the hardcoded secret:

/usr/bin/env bash << 'SECRET_DETECTION_SCRIPT_EOF'
# Before
export API_KEY="sk-abc123..."

# After
export API_KEY="${API_KEY:-}"  # Set via environment
SECRET_DETECTION_SCRIPT_EOF

Then retry:

chezmoi add ~/.zshrc

2. Template with External Source

Convert to template that pulls from secure source:

/usr/bin/env bash << 'SECRET_DETECTION_SCRIPT_EOF_2'
# Rename in source
mv "$(chezmoi source-path)/dot_zshrc" "$(chezmoi source-path)/dot_zshrc.tmpl"
SECRET_DETECTION_SCRIPT_EOF_2

Edit template to use password manager:

{{ $secret := (onepassword "API Key").password -}}
export API_KEY="{{ $secret }}"

3. Use Environment Variable

Remove secret from dotfile entirely. Set via:

• Shell profile sourcing a non-tracked file
• Password manager CLI (op run, doppler run)
• System keychain

---

Supported Secret Types

Chezmoi detects common secret patterns:

• API keys (AWS, GCP, Azure, OpenAI, etc.)
• Private keys (RSA, SSH, PGP)
• Tokens (JWT, OAuth, GitHub PAT)
• Passwords in common formats
• Connection strings with credentials

---

Best Practice

Never bypass secret detection. If a secret is detected:

1. Remove or externalize the secret 2. Use chezmoi's password manager integration 3. Re-add the cleaned file

Secrets in git history are extremely difficult to fully remove and may be exposed even in private repositories.

Skill: Chezmoi Workflows

First-Time Setup

1. Detect Current State

command -v chezmoi || echo "NOT INSTALLED"
chezmoi source-path 2>/dev/null || echo "NOT INITIALIZED"
chezmoi git -- remote -v 2>/dev/null || echo "NO REMOTE"

2. Install

/usr/bin/env bash << 'SETUP_EOF'
# macOS
brew install chezmoi

# Linux
sh -c "$(curl -fsLS get.chezmoi.io)"
SETUP_EOF

3. Initialize

Fresh start:

chezmoi init

Clone existing repo:

chezmoi init git@github.com:<username>/dotfiles.git
chezmoi apply

---

Remote Configuration

Create Private Repository

/usr/bin/env bash << 'GIT_EOF'
# Using gh CLI (recommended)
gh repo create dotfiles --private --source="$(chezmoi source-path)" --push

# Or manually after creating repo on github.com:
chezmoi git -- remote add origin git@github.com:<username>/dotfiles.git
chezmoi git -- push -u origin main
GIT_EOF

Change Remote

chezmoi git -- remote -v                                               # View current
chezmoi git -- remote set-url origin git@github.com:<username>/<repo>.git
chezmoi git -- push -u origin main

---

Custom Source Directory

Default: ~/.local/share/chezmoi

To use custom location:

/usr/bin/env bash << 'VALIDATE_EOF'
# 1. Move existing source
mv "$(chezmoi source-path)" ~/path/to/dotfiles

# 2. Update config
cat >> ~/.config/chezmoi/chezmoi.toml << 'EOF'
sourceDir = "~/path/to/dotfiles"
EOF

# 3. Verify
chezmoi source-path
VALIDATE_EOF

---

Multi-Account SSH

For users with multiple GitHub accounts, configure SSH to select account by directory pattern:

# ~/.ssh/config

# Default account
Host github.com
    HostName github.com
    IdentityFile ~/.ssh/id_ed25519_default

# Override for specific directory pattern
Match host github.com exec "pwd | grep -qE '/(personal|private)/'"
    IdentityFile ~/.ssh/id_ed25519_personal

---

Recommended Configuration

~/.config/chezmoi/chezmoi.toml:

[edit]
command = "hx"            # Or vim, nvim, code, etc.
apply = false             # Manual apply after review

[git]
autoadd = true            # Auto-stage on chezmoi add
autocommit = true         # Auto-commit on add/apply
autopush = false          # Manual push for review

[add]
encrypt = false           # Set true for age/gpg encryption
secrets = "error"         # Fail-fast on detected secrets

[data]
[data.git]
  name = "Your Name"
  email = "you@example.com"

---

Show Current Setup

chezmoi source-path
chezmoi git -- remote -v
chezmoi git -- status --short
chezmoi managed | wc -l
cat ~/.config/chezmoi/chezmoi.toml 2>/dev/null || echo "Using defaults"

---

Migration: Change GitHub Account

# 1. Switch gh CLI account
gh auth switch -u <new-account>

# 2. Create new private repo
gh repo create dotfiles --private

# 3. Update remote
chezmoi git -- remote set-url origin git@github.com:<new-account>/dotfiles.git

# 4. Push history (force required for new empty repo)
chezmoi git -- push -u origin main --force

# 5. (Optional) Delete old repo
gh auth switch -u <old-account>
gh repo delete <old-account>/dotfiles --yes

Note: Force push is safe here because the new repo is empty. Never force push to a repo with existing history unless intentional.

---

Troubleshooting

No remote configured

chezmoi git -- remote add origin git@github.com:<username>/dotfiles.git
chezmoi git -- push -u origin main

Permission denied (publickey)

ssh -T git@github.com                  # Check which account is active

If wrong account, configure SSH Match directives or use HTTPS:

chezmoi git -- remote set-url origin https://github.com/<username>/dotfiles.git

Source directory not found

/usr/bin/env bash << 'CONFIG_EOF'
grep sourceDir ~/.config/chezmoi/chezmoi.toml
ls -la "$(chezmoi source-path)" || echo "Directory missing"
CONFIG_EOF