Gotchas¶

Don't edit $HOME files directly

Editing ~/.zshrc or ~/.gitconfig directly works until the next chezmoi apply silently overwrites it. Always edit the source (dot_zshrc, dot_gitconfig.tmpl) in this repo, then chezmoi apply.

Why: chezmoi treats the source as truth. Anything in $HOME is just the rendered output. The mental model is "the repo IS the dotfiles, not a backup of them."

Always use --encrypt for any file with credentials

chezmoi add ~/.zshrc.local (no flag) commits plaintext. Once committed, it's in git history forever. Use chezmoi add --encrypt ~/.zshrc.local.

Why: the gitleaks pre-commit hook and ggshield pre-push scan catch most patterns, but not all. The --encrypt flag is the deterministic guard.

The age recipient is public but the key is private

The recipient = "age1..." line in .chezmoi.toml.tmpl is committed and visible on GitHub. That's intentional — it identifies who can decrypt. The matching private key.txt is what unlocks it; never commit that file or anything generated from it.

env bash is bash 3.2 during the bootstrap window

Every chezmoi-deployed script uses #!/usr/bin/env bash, which resolves against the ambient PATH — on a fresh Mac that's /bin/bash 3.2 until brew bundle installs Homebrew bash (run_onchange_02-brew-bundle.sh.tmpl). Anything that runs before that point (the audit helpers, the drift scripts) must stay 3.2-compatible: no ${var,,}/${var^} case-modifying expansion, no readarray/mapfile, no declare -A.

Why it bit: normalize_bool's ${1,,} threw bad substitution under 3.2 (#143). Note the failure mode — it's the opposite of what you'd expect. normalize_bool is called in command substitution (exp_n=$(normalize_bool "$expected")), so the subshell died and both sides came back empty. [[ "" == "" ]] then counted every -bool key as matched: the audit reported a false all-clear and silently hid real drift, rather than inflating it. A guard that fails open is worse than one that fails loud — which is why the fix is paired with a pre-commit gate rather than trusting review to catch the next instance.

The guard: scripts/check-bash4-isms.sh, a pre-commit hook, sweeps every executable_* file and the root run_once_*/run_onchange_* scripts for this construct class. It's a required check on main (pre-commit (all hooks)) — unlike a bats assertion of the same shape, it actually blocks a regression from landing. make ci does not run pre-commit, so this class isn't caught by a local make ci pass; run pre-commit run --all-files (or just commit — the hook is installed) to exercise it.

The strip must stay non-greedy: .tmpl files are scanned with their {{ }} actions removed by scripts/strip-template-actions.sh — the same helper the Makefile's lint target pipes templates through before ShellCheck, so the two scans can't drift apart. Its substitution class is [^{}]*, not .*. A greedy .* spans from the first {{ to the last }} on a line, so real shell sitting between two actions ({{ if x }}v=${1,,}{{ end }}) is deleted along with them and reaches neither the guard nor ShellCheck — a false all-clear of exactly the shape above.

Two GnuPG installations share one ~/.gnupg, and the agent is first-come-first-served

GPG Suite installs MacGPG2 2.2 under /usr/local/MacGPG2, and Homebrew's gnupg 2.5 lands alongside it at /opt/homebrew/bin/gpg — not because it was ever requested (installed_on_request: false), but as a transitive dependency of gpgme, gpgmepp, and poppler. It can't simply be uninstalled, and brew shellenv puts it ahead of MacGPG2 on PATH.

Only one gpg-agent can own the ~/.gnupg/S.gpg-agent socket. Whichever starts first wins and then serves both frontends — so the terminal and the Finder "Services → Decrypt Selection" menu silently share one daemon whose identity depends on what you ran first that session.

Why it bit (#150): Homebrew's gnupg ships only pinentry-curses, and gpg-agent.conf had no pinentry-program line, so the agent chose a pinentry off its own PATH. When the Homebrew agent won the socket, GUI decryption got a terminal passphrase prompt with no terminal to draw in. GPG Services surfaced only Decryption failed code = 152 — GPG_ERR_DECRYPT_FAILED, libgpg-error's catch-all, which named neither the agent nor the pinentry. The keyring, the secret key, and the message were all fine.

The fix: private_dot_gnupg/private_gpg-agent.conf pins pinentry-program to GPG Suite's pinentry-mac. Both agents read the same config file, so the outcome no longer depends on which one won. pinentry-mac also reaches the macOS Keychain for a saved passphrase, which pinentry-curses can never do.

Diagnosing the next one: stderr says only "decryption failed". Use --status-fd for the machine-readable stream, which names the pinentry that launched and the key considered:

gpg --batch --status-fd 2 --decrypt msg.asc 2>&1 >/dev/null | grep -E 'PINENTRY_LAUNCHED|NO_SECKEY'

A healthy GUI-capable agent reports PINENTRY_LAUNCHED … mac; … curses is the broken state. Confirm which agent holds the socket with lsof -p "$(pgrep -x gpg-agent)" | awk '$4=="txt"' — the version handshake (gpg-connect-agent 'GETINFO version' /bye) tells you the same thing faster.

Related: dot_gitconfig.tmpl pins gpg.program to the MacGPG2 path by stat, not lookPath, for the same underlying reason — a render-time PATH lookup baked in whichever gpg happened to be first and produced phantom drift.

Never parse the hook payload with a regex

.claude/hooks/guard-destructive.sh receives a JSON payload on stdin and decides whether to refuse a Bash call. It used to pull the command out with sed -nE 's/.*"command"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p', and that failed open: [^"]* stops at the first escaped quote inside the JSON string, so echo "hi" && chezmoi apply arrived as the harmless echo \ and passed every rule. The .* prefix was greedy too, so a payload mentioning command twice matched the wrong one. It now parses with python3 -c 'json.load(...)', and if the parser is missing or the payload won't parse it scans the raw payload — over-blocking rather than under-blocking.

The mirror-image defect: a raw substring match also fires on a guarded phrase that is merely quoted as data, so a commit message discussing chezmoi apply was refused. Heredoc bodies are now stripped before matching — but only when nothing in the command could execute them. bash <<EOF, … | sh, python3 -c, xargs and friends keep their bodies scanned, because there the body is code.

Both directions are pinned by tests/guard-destructive.bats, which builds payloads with a real JSON encoder. The previous suite interpolated into a format string and therefore could not express a command containing a quote — which is precisely why the fail-open survived 14 passing tests. If you touch this hook, run those tests against the old version first and watch them go red.