Dotfiles (chezmoi)

Manage config files as a git-backed source of truth with chezmoi. The source dir (chezmoi source-path, a git repo) is authoritative; live files in $HOME are generated by chezmoi apply. chezmoi-first (detect and respect other setups, but drive chezmoi).

Route to a workflow

The scripts (prefer these over ad-hoc bash)

Stable, tested helpers live in scripts/ — call them instead of re-deriving the chezmoi discovery / status / secret-scan commands each session. Run by absolute path from this skill's directory. All three are read-only, resolve the source dir internally (never hardcode ~/.local/share/chezmoi), and degrade gracefully when chezmoi is absent/uninitialized.

Full contract + a worked example: scripts/README.md. The inline commands in the sections and reference files below is what these run under the hood — reach for it only for novel, one-off checks.

Discovery (always run first)

Run scripts/chezmoi_status.py — it prints all of the following as key<TAB>value lines:

• Not initialized (initialized no) → this is setup.
• Initialized → the script's status_drift / diff_pending counts flag drift, and scripts/dotfiles_inventory.py shows managed/unmanaged for gaps.
• The source repo, config (~/.config/chezmoi/chezmoi.toml), and any .tmpl / .chezmoiignore / encryption settings (all surfaced by the status script) tell you how the user's dotfiles are organized — read before editing.

command -v chezmoi && chezmoi --version | head -1
# NOTE: `chezmoi source-path` prints a path even when NOT initialized — don't use it as the test.
test -d "$(chezmoi source-path)/.git" && echo "(source repo exists)" || echo "(not initialized)"
chezmoi managed 2>/dev/null | head          # empty + no source repo => this is `setup`
chezmoi status 2>/dev/null                  # drift (empty = in sync)
chezmoi git -- remote -v 2>/dev/null         # is there a remote?

Core model (don't fight it)

• Source is truth. chezmoi apply writes source → $HOME. Home edits are drift until captured back into source.
• Pick ONE editing flow and stick to it (mixing causes drift):
  • chezmoi edit --apply <target> — edit the source copy, then apply. Preferred.
  • or edit the home file, then chezmoi re-add to pull it back into source.
• .tmpl files template per-machine values ({{ .chezmoi.hostname }}, {{ .chezmoi.os }}) and pull secrets from a password manager at apply time.

Core principles

1. Verify with chezmoi, not by eyeballing. After changes, re-run scripts/chezmoi_status.py: status_drift and diff_pending back to 0 means source == home, doctor warning=0 error=0 means healthy. See reference/verification.md. Confirm apply is idempotent (a second run leaves both counts at 0).
2. Secrets never land in git as plaintext. This is the #1 dotfiles hazard. Before any commit, run scripts/secret_scan.py (paths + reason only, never values; exit 1 = findings) and route anything it flags through encryption or password-manager templates (reference/secrets.md). Make the dotfiles repo private.
3. Diff before apply. chezmoi apply overwrites home files from source — show chezmoi diff and confirm before applying onto an existing, hand-maintained config.
4. Don't assume inventory. Read chezmoi managed and the source tree each time.

Settings

Read ~/.config/devenv/config.toml before prompting; if a [dotfiles] section exists, use it as defaults (precedence: explicit answer this session > config.toml > ask). Had to ask? Offer to save the answer back. Managed by the devenv skill. Keys honored:

• manager — dotfiles manager (e.g. chezmoi).
• repo — remote repo name (keep it private).
• ignore — extra .chezmoiignore patterns to apply.

Safety

• A secret's plaintext never enters the model's context. Detection is paths-and-reason only (secret_scan.py reports only paths + a reason, never the matched text); verification is by exit code, encrypted_*.age markers, and unresolved {{ ... }} references — never by reading the value. Ops needing the real plaintext (age key, password-manager unlock, moving a private key) run out of band via !. See reference/secrets.md.
• Never open a flagged file to "see" or confirm the finding. Once the scanner flags a path, that line is the evidence — the reason names the rule (token shape, key block, secret-by-location), which is everything needed to classify and route it. Reading, grepping, or chezmoi cat-ing the file to double-check pulls the very value into context that the whole pipeline exists to keep out — one "let me verify" read undoes the guarantee. Classify by path + reason alone; if genuinely ambiguous, ask the user what the file holds rather than looking. For secret-by-location paths (private keys, .netrc, .aws/credentials) the plugin's PreToolUse guard (scripts/secret_read_guard.py) enforces this mechanically — a denial from it is the contract working, not an obstacle to route around.
• The source repo is personal and often sensitive — private remote, and never publish it as an Artifact or paste its contents outward.
• On a fresh machine, chezmoi init --apply overwrites local configs — back up or diff first.
• .chezmoiignore excludes machine-local-only files from management; use it rather than deleting.