Skip to content

chezmoi.md

Latest commit

 

History

History
150 lines (119 loc) · 6.45 KB

chezmoi.md

File metadata and controls

150 lines (119 loc) · 6.45 KB
Raw

Chezmoi Source State

This repo uses chezmoi for public-safe dotfile source state. Chezmoi owns files under chezmoi/ and applies them to $HOME through scripts/bootstrap/apply-dotfiles.sh.

Source Layout

Use chezmoi source attributes instead of literal target filenames:

Source Target
chezmoi/.chezmoidata/profiles.json Versioned template data for profile capabilities and composition
chezmoi/dot_zshrc.tmpl ~/.zshrc; all profiles set EDITOR/VISUAL to vim
chezmoi/dot_gitconfig.tmpl ~/.gitconfig
chezmoi/private_dot_config/mise/config.toml.tmpl ~/.config/mise/config.toml
chezmoi/private_dot_config/private_dotfiles/profile.tmpl ~/.config/dotfiles/profile
chezmoi/private_dot_ssh/private_config ~/.ssh/config
chezmoi/private_dot_local/private_libexec/private_dotfiles/private_executable_git-ssh-sign-agentless ~/.local/libexec/dotfiles/git-ssh-sign-agentless
chezmoi/private_dot_claude/modify_private_settings.json Selected values inside ~/.claude/settings.json for developer profiles
chezmoi/private_dot_config/zed/private_settings.json ~/.config/zed/settings.json for workstation profiles
chezmoi/private_dot_config/zed/private_keymap.json ~/.config/zed/keymap.json for workstation profiles
chezmoi/private_AGENTS.md.tmpl ~/AGENTS.md, the shared global agent rules composed with optional start and end Markdown fragments
chezmoi/private_dot_claude/symlink_CLAUDE.md ~/.claude/CLAUDE.md link to ~/AGENTS.md
chezmoi/private_dot_codex/symlink_AGENTS.md ~/.codex/AGENTS.md link to ~/AGENTS.md

The private_ attribute is used for parent config directories and files that should land as owner-only local config.

Profile differences:

  • Personal-workstation and workstation manage Ghostty and Zed settings.
  • All four developer profiles share GitHub authentication, outbound SSH, signing-helper, and allowed-signers sources.
  • The assistant profile renders a minimal Git base with a local workload-identity include and excludes those developer surfaces. Only assistant includes the optional GitHub App helper.

Claude Code user settings:

  • All four developer profiles set permissions.defaultMode=auto.
  • The modify template preserves every other setting, including the complete env object.
  • User settings are the lowest-precedence Claude Code scope; project, local, command-line, and managed settings can override this default.
  • The repository does not manage Claude Code environment values or ~/.claude.json.

SSH config ownership:

  • The developer SSH entrypoint is exclusively Chezmoi-managed.
  • Host-specific directives belong in ~/.ssh/config.local.
  • Tools that support a configurable output path should own a fragment under ~/.ssh/config.d/*.conf.
  • Tools with a fixed generated path receive a stable managed include. For example, Colima owns and regenerates ~/.colima/ssh_config as its virtual machines start and stop.
  • Do not preserve arbitrary mutations to ~/.ssh/config: route each writer to its own included file so unexpected changes remain visible as drift.

Use attributes deliberately:

  • dot_ maps to a leading dot.
  • private_ sets restrictive permissions for target files and directories.
  • executable_ is only for target files that must be executable.
  • .tmpl is only for real host, user, or OS branching. Keep templates small and avoid secrets unless values are fetched at apply time from an approved external secret source.

Workflow

Operators preview and apply the full per-user flow through the root command:

mise trust
./dotfiles diff workstation
./dotfiles apply workstation

Contributors changing chezmoi source use the repository task interface:

mise trust
mise run dotfiles:diff workstation
mise run dotfiles:apply workstation

./dotfiles apply delegates to scripts/bootstrap/install.sh, which applies the same source before running the remaining profile install steps.

For normal edits:

  1. Edit the source file under chezmoi/.
  2. Preview with mise run dotfiles:diff <profile>.
  3. If changing bootstrap behavior, test in a temporary destination:
tmp_dest="$(mktemp -d /tmp/dotfiles-chezmoi-apply.XXXXXX)"
chezmoi --source "$PWD/chezmoi" --destination "$tmp_dest" \
  --override-data '{"dotfilesProfile":"workstation"}' --force apply
find "$tmp_dest" -maxdepth 4 -type f -o -type l | sort
rm -rf "$tmp_dest"

For permission-sensitive paths, verify modes with:

stat -f '%OLp %N' "$path"

Boundaries

  • Edit files under chezmoi/, not generated files in $HOME.
  • Keep chezmoi.toml, ~/.config/dotfiles/agents.start.md, ~/.config/dotfiles/agents.end.md, ~/.config/dotfiles/zshenv.local, local data files, hostnames, identities, vault names, item names, tokens, private keys, and generated env files out of Git.
  • ~/.zshenv sources ~/.config/dotfiles/zshenv.local when that path is a readable regular file. Use it for machine-specific exports the shared zshenv must not own. Chezmoi ignores this path; create it manually and keep it owner-only (0600); symlinks are ignored. Example: if 1Password's SSH agent is SSH_AUTH_SOCK, set TELEPORT_ADD_KEYS_TO_AGENT=no there instead of changing the shared zshenv. Keep service tokens and secret values out of shell startup.
  • Prefer public-safe templates and local-only config over checked-in secret references.
  • Do not use exact_ at $HOME scope.
  • Do not add run_, run_once_, or run_onchange_ scripts unless the repo explicitly needs that lifecycle and the docs explain it.
  • Do not use chezmoi add against the live home directory when migrating already tracked repo files. Prefer repo-local edits or git mv so history and review stay clear.
  • Keep macOS GUI state, App Store auth, 1Password sessions, Tailscale node identity, Tizen secrets, and local secret-manager auth state in the existing explicit scripts or manual setup docs.

Package and Runtime Layers

Chezmoi applies dotfiles only. Homebrew Bundle remains the package layer, and mise remains the runtime/tool-version layer. Do not duplicate package lists into chezmoi scripts unless there is a concrete idempotency reason.

Wrapper Expectations

Keep scripts/bootstrap/apply-dotfiles.sh non-interactive and preserve:

  • --dry-run and --verbose.
  • Backups for pre-existing local files before --force apply.
  • mise run verify:domain config and mise run verify:domain profiles when wrapper behavior changes.