athal7/dotfiles / dot_agents/skills/chezmoi
chezmoi
UnverifiedManage dotfiles via chezmoi — apply safely, destroy files, manage LaunchAgents and externals, config and template gotchas
chezmoi apply deploys source files to ~ and runs run_onchange scripts (brew bundle, skill sync, etc.).
Deploy workflow
Changes land via chezmoi-deploy, not pull requests. The source dir is pinned to the primary checkout, so a bare chezmoi apply always reads main — work is verified render-only until deployed.
- Verify render-only — never a bare
chezmoi applyfrom a worktree. Pass-S "$(pwd)"with no-mutation verbs:chezmoi diff -S "$(pwd)",chezmoi apply -n -v -S "$(pwd)"(dry-run; also shows which scripts would fire),chezmoi cat -S "$(pwd)" <target>. A worktree has no gitignored.chezmoidata/local.yaml, so add--override-data-file "$(chezmoi source-path)/.chezmoidata/local.yaml"(the primary checkout's copy) to render against real machine data. - Read the rendered diff, don't re-assert template literals.
chezmoi diffis the change report: review it before deploying to confirm the change matches the intention. Scripted tests inscripts/are for what a diff cannot judge — values derived from other data, cross-file consistency (packages.yaml → externals → rendered config), and generated scripts' runtime behavior — not for restating template contents. - Deploy with
chezmoi-deploy <branch>. It locks, rebases the branch onto the primary checkout'smainwhen needed, fast-forward-merges it intomain, prints thechezmoi difffor~(aborting if rendering fails), runschezmoi apply --force, and pushesmainto origin. A rebase conflict is aborted; resolve it in the worktree and retry. Safe from a hosted aoe session: the session runs in a tmux pane independent of any LaunchAgent, and the generator only reloads agents whose plist content actually changed — it never touches the tmux pane a deploy is running from. - Escape hatch — to exercise one deployed file's runtime behavior without a full deploy:
chezmoi apply -S "$(pwd)" --exclude=scripts --persistent-state "${TMPDIR:-/tmp}/branch-state.boltdb" <target>— mutates only that path, runs no scripts, leaves global state untouched.
chezmoi apply reloads changed LaunchAgents automatically — the .chezmoiscripts/run_onchange_after_zz-launch-agents.sh.tmpl generator renders plists from dot_config/launchd-yaml/agents.yaml.tmpl after package installation and reloads only what changed. To force-reload an agent manually during testing:
# Restart a running agent (picks up plist changes):
launchctl kickstart -k "gui/$(id -u)/<label>"
# Full reload (for structural changes like new binary paths):
launchctl bootout "gui/$(id -u)/<label>"
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/<plist-file>
# Load a new agent for the first time:
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/<plist-file>
Notes
- Adding a new
[data]key to.chezmoi.toml.tmplrequireschezmoi initbeforechezmoi apply—applyalone does not regenerate~/.config/chezmoi/chezmoi.toml chezmoi initis destructive to the live config — it re-renders the template from scratch. The "config file template has changed" warning fromchezmoi applyis cosmetic when scripts are already deployed; do not runchezmoi initto silence it.- Machine-specific config lives in
.chezmoidata/local.yamlin the source directory — calendar config, reminders, per-org config, and OMPomp_model_roles(model names are account-specific, soconfig.yml.tmplships none; roles absent from the map stay unset). Gitignored. Thelocal.yaml.exampletemplate must NOT live under.chezmoidata/itself — files there get merged intochezmoi dataand would leak placeholder values into runtime.
Gotchas
.chezmoidatavalues are plain data — template expressions like{{ .chezmoi.arch }}inside YAML string values are not evaluated. Arch/OS logic must live in the.tmplfile itself..appbundles viachezmoiexternal— usetype = "archive"with target"Applications/<AppName>.app"(unique TOML key per app) andstripComponents = 1to strip the archive's root directory. WithoutstripComponents = 1the app ends up double-nested inside the archive's root directory. TOML does not allow duplicate keys, so each app needs its own unique target path.- LaunchAgent binary path changes — after moving a binary (e.g., brew →
~/.local/bin),launchctl bootout+bootstrapis required to pick up the new plist;kickstartalone is not sufficient if the service is crash-looping. - Inline shell in plist templates — avoid
/bin/sh -cwith inline scripts inProgramArguments. Three escaping layers (XML entities, shell quoting, content characters) make this fragile — an apostrophe in text content will silently break single-quoted strings,&needs&in XML, etc. UseProgramArgumentswith a standalone script instead: each argument is a separate<string>element, no shell involved. - Deleting a managed file —
chezmoi applydoes not remove files whose source entry was deleted. Usechezmoi destroy <target>before removing the source entry — it removes both in one step. Order matters: if yougit rmthe source first,chezmoi destroyreturnsnot managedand you mustrmthe deployed file manually. Note: files managed via.chezmoiexternal.toml.tmplcannot be destroyed this way — chezmoi owns them; remove the external entry instead. - Deleting an authored skill —
dot_agents/skills/is managed directly at~/.agents/skills/. Runchezmoi destroy ~/.agents/skills/<name>before deleting its source directory; removing source first makes the target unmanaged. Externally installed skills are separate sibling directories and are never erased during authored-skill updates. .chezmoiignorewins over.chezmoiremove— an ignored target is never removed, so listing the path in both places deletes nothing. Remove the stale copies first (or drop the ignore entry, apply, then re-add it), otherwise they linger forever while chezmoi reports them unmanaged.- Empty files are skipped — chezmoi does not deploy 0-byte files. Python
__init__.pyfiles need at least a comment (e.g.,# package name) or they won't appear at the target. - "X has changed since chezmoi last wrote it" prompt — chezmoi's persistent state SHA for that target drifted from the live file (often after an external tool rewrote it, after a template edit between sessions, or after picking
skip in a previous prompt). Ifchezmoi diffis empty after the prompt, the live and rendered content actually match — pickoverwrite (or rerun with--force) to resync state. Pickingskip leaves state stale and the prompt will reappear next apply. Recurring offender:~/.zshrc, occasionally rewritten by tool installers (bun, mise) at session startup. __pycache__under managed lib dirs — Python bytecache in~/.local/lib/{kb,cal}/__pycache__/is generated at runtime and triggers "has changed since chezmoi last wrote it" prompts on every apply. Fix: add**/__pycache__to.chezmoiignore.- Non-TTY "has changed" prompt fails — when
chezmoi applyruns from an agent session (no TTY attached), the interactive prompt errors with "could not open a new TTY: open /dev/tty: device not configured". Usechezmoi apply --forceto skip prompts in non-interactive contexts. chezmoi-templatespre-commit hook renders the current worktree — it passes-S "$(git rev-parse --show-toplevel)". Gitignored.chezmoidata/local.yamlis absent in worktrees, so the hook layers trackedlocal.yaml.examplethroughchezmoi execute-template --override-data-file. Keep placeholder keys there for templates that require private machine data.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |