shepherdjerred/monorepo/chezmoi-helper

Chezmoi Helper Agent

What's New

Recent chezmoi releases (latest: v2.69.3):

Overview

Chezmoi manages dotfiles across multiple machines from a single source of truth. The source directory (default: ~/.local/share/chezmoi) contains the declarative desired state. Run chezmoi apply to update the destination directory (~) to match.

Core workflow:

1. Add files: chezmoi add ~/.gitconfig
2. Edit source: chezmoi edit ~/.gitconfig
3. Preview changes: chezmoi diff
4. Apply changes: chezmoi apply
5. Commit and push: chezmoi cd && git add . && git commit && git push

Source directory location: ~/.local/share/chezmoi (view with chezmoi source-path)

Configuration file: ~/.config/chezmoi/chezmoi.toml (or .yaml/.json/.jsonc)

Naming Conventions

Chezmoi maps source filenames to target filenames using prefix/suffix attributes:

File Prefixes (applied in order)

Directory Prefixes

Script Prefixes

Combined Prefix Examples

Prefixes combine: private_dot_config -> .config (mode 0o700), run_onchange_after_install.sh.tmpl -> templated script that runs after apply when content changes.

CLI Quick Reference

# Core workflow
chezmoi add ~/.gitconfig              # Add file to source state
chezmoi add --template ~/.bashrc      # Add as template
chezmoi add --encrypt ~/.ssh/id_rsa   # Add encrypted
chezmoi edit ~/.gitconfig             # Edit source state
chezmoi diff                          # Preview changes
chezmoi apply                         # Apply all changes
chezmoi apply --dry-run --verbose     # Preview without applying
chezmoi apply ~/.gitconfig            # Apply single file
 
# Inspection
chezmoi managed                       # List all managed files
chezmoi managed --include=files       # List only files
chezmoi unmanaged                     # List unmanaged files in ~
chezmoi data                          # Show template data
chezmoi cat ~/.gitconfig              # Show target state of file
chezmoi source-path ~/.gitconfig      # Show source path for target
chezmoi target-path ~/src/dot_git...  # Show target path for source
chezmoi doctor                        # Check for common issues
 
# Template debugging
chezmoi execute-template '{{ .chezmoi.os }}'
chezmoi execute-template < ~/.local/share/chezmoi/dot_bashrc.tmpl
 
# File management
chezmoi re-add                        # Update source from changed targets
chezmoi forget ~/.old_config          # Stop managing a file
chezmoi destroy ~/.old_config         # Remove from both source and target
chezmoi merge ~/.gitconfig            # Three-way merge conflicts
chezmoi merge-all                     # Merge all conflicts
 
# Source directory
chezmoi cd                            # Open shell in source dir
chezmoi git -- add .                  # Run git in source dir
chezmoi git -- commit -m "update"
chezmoi git -- push
 
# Setup on new machine
chezmoi init https://github.com/user/dotfiles.git
chezmoi init --apply user             # Clone and apply (shorthand for GitHub)
 
# Encryption
chezmoi age-keygen --output=key.txt   # Generate age key
chezmoi edit-encrypted ~/.secret      # Edit encrypted file transparently
 
# State management
chezmoi status                        # Show pending changes
chezmoi verify                        # Verify target matches source
chezmoi update                        # Pull and apply from remote
chezmoi state delete-bucket --bucket=scriptState  # Reset run_once_ state

Template Basics

Chezmoi uses Go text/template syntax with sprig functions. Files ending in .tmpl or placed in .chezmoitemplates/ are processed as templates.

Common Variables

{{ .chezmoi.os }}              # "darwin", "linux", "windows"
{{ .chezmoi.arch }}            # "amd64", "arm64"
{{ .chezmoi.hostname }}        # Machine hostname (up to first dot)
{{ .chezmoi.username }}        # Current username
{{ .chezmoi.homeDir }}         # Home directory path
{{ .chezmoi.sourceDir }}       # Source directory path
{{ .chezmoi.kernel }}          # Kernel info (Linux only)
{{ .chezmoi.osRelease }}       # /etc/os-release data (Linux only)

OS-Conditional Configuration

{{ if eq .chezmoi.os "darwin" -}}
# macOS-specific config
{{ else if eq .chezmoi.os "linux" -}}
# Linux-specific config
{{ end -}}

Password Manager Integration (1Password)

{{ onepasswordRead "op://vault/item/field" }}

Reusable Templates

Place shared templates in .chezmoitemplates/ and include with:

{{ template "shared-config.tmpl" . }}

Template Data

Define custom data in .chezmoidata.yaml, .chezmoidata.toml, or .chezmoidata.json at the root of the source directory. Access with {{ .customKey }}.

User's Chezmoi Patterns

This repository demonstrates several chezmoi patterns:

• OS-conditional ignoring: .chezmoiignore uses templates to ignore Windows-only paths on non-Windows, and macOS-only paths on non-macOS
• OS-conditional Brewfile: dot_Brewfile.tmpl includes OS-specific Brewfile using {{ include ".Brewfile_darwin" }}
• 1Password integration: config.fish.tmpl uses {{ onepasswordRead "op://..." }} with {{ if lookPath "op" }} guard
• Onchange scripts: run_onchange_after_launchagent.sh.tmpl uses {{ include ... | sha256sum }} in a comment to trigger re-run when the included file changes
• After scripts: run_after_sync-theme.sh.tmpl runs theme sync after every apply, guarded by OS check
• Licensed Berkeley Mono bootstrap: install_macos.sh discovers the externally supplied static TTF package under ~/Downloads (or BERKELEY_MONO_SOURCE_DIR) and invokes packages/fonts/patch-berkeley-mono.py; source and patched fonts must remain outside the repository
• `run_after_` scripts always show as a pending "new file" in `chezmoi diff`. A plain run_after_ script (not run_once_/run_onchange_, e.g. run_after_sync-theme.sh.tmpl) runs on every apply and isn't state-tracked, so it renders as new file mode 100755 ... sync-theme.sh even right after a clean chezmoi apply. Treat a chezmoi diff whose only remaining hunk is that run script as fully reconciled. Also: chezmoi apply on .claude/settings.json needs --force in non-interactive shells because Claude Code rewrites that file out-of-band ("changed since chezmoi last wrote it").

Special Files and Directories

Reference Files

• `references/templates.md` - Go template syntax, chezmoi template functions, conditionals, data sources, OS detection, password manager functions
• `references/commands.md` - Full CLI reference with flags and examples for all chezmoi commands
• `references/advanced.md` - External sources, encryption (age/gpg), scripts, hooks, multi-machine patterns, 1Password integration

When to Ask for Help

Ask the user for clarification when:

• Target machine OS or architecture is ambiguous for template conditionals
• Encryption method (age vs gpg) is not specified
• Password manager choice or vault/item paths are unclear
• Script execution order requirements are complex
• External source URLs or refresh periods need confirmation
• Modify script logic for merging existing file content is non-trivial