feat: post on dotfiles migration

Author: stevecrawshaw

_posts/2026-08-18-migrating-dotfiles-to-chezmoi.md

@@ -0,0 +1,163 @@
+---
+layout: post
+title: "Migrating my dotfiles to chezmoi: one config for a work desktop and an AI-harness-testing laptop"
+date: 2026-08-18
+categories: [Development Tools]
+tags:
+- chezmoi
+- dotfiles
+- ubuntu
+- windows
+- claude
+- ai-coding
+- shell
+- dev-tools
+---
+
+**TLDR; I migrated my dotfiles into a single [chezmoi](https://chezmoi.io)-managed repo at [github.com/stevecrawshaw/dotfiles](https://github.com/stevecrawshaw/dotfiles). One source tree is rendered per machine by Go templates: a Windows 11 work desktop (bash, Git Bash) and a Lenovo T490 Ubuntu laptop (zsh, Ghostty) that exists mainly to test AI coding harnesses like DeepSeek and Pi.**
+
+## Why I needed this
+
+For years my configuration lived in roughly three places, none of them authoritative:
+
+- a `.bashrc` for the work desktop, hand-edited over several jobs' worth of cruft
+- a `.zshrc` on the new Ubuntu laptop, written from scratch and already diverging
+- `~/.claude` as its own git repo — which was fine until I started building skills, agents and hooks, and the repo stopped being a clean mirror of reality
+
+The trigger was the laptop. I'd just set up a Lenovo T490 with Ubuntu as a dedicated testbed for AI coding harnesses, and within a month the two machines' configs had drifted so far that "copy the file across" wasn't working anymore. Editor settings, shell aliases, git config — everything was subtly different, and nothing was the source of truth.
+
+## The laptop's job: an AI harness testbed
+
+It's worth being explicit about what the personal laptop is *for*, because it shaped the whole migration. The laptop is a testing ground for AI coding harnesses — DeepSeek, Pi, Claude Code, whatever new coding agent shows up next. I install a harness there first, point it at my repos, and run it against real tasks before trusting it anywhere near work.
+
+That role drives three decisions in the dotfiles:
+
+1. **The entire `~/.claude` tree is version-controlled** — agents, skills, hooks, commands, rules. When an experiment breaks something (and they do), I can diff against the last good state and re-provision in seconds instead of reconstructing it from memory.
+2. **The shell is tuned for watching agents work** — fast zsh startup, fzf for history and file jumping, an oh-my-posh prompt with Nerd Font glyphs in Ghostty. The terminal is the dashboard for the experiments.
+3. **The bootstrap provisions exactly what a coding harness needs** on a fresh machine: `uv`, `gh`, `ripgrep`, `fzf`, git, plus the R and Python toolchains my data work needs. A harness is useless if it can't run code.
+
+The joke is that the migration I'm writing about is *because* of the AI testing, not in spite of it — version-controlled config is what makes harness experimentation reversible.
+
+## Why chezmoi
+
+I considered the usual options first:
+
+- **A bare git repo with symlinks** — the classic approach, but symlinks need privileges on Windows, which is a whole conversation I didn't want to have with the IT department.
+- **GNU Stow** — same symlink problem, and no templating.
+- **Dotbot or a custom script** — reinventing the wheel, badly.
+
+chezmoi won on three concrete points:
+
+1. **It copies files rather than symlinking them.** This sidesteps the Windows symlink-privilege problem entirely. No admin rights, no developer mode, no junction-point hacks.
+2. **Go templates.** One source file can render differently per machine — the gitconfig's `core.editor` path and `autocrlf` setting, the OneDrive path on the work box, machine-specific PATH entries. Machine identity is derived from the OS, so there's nothing to prompt for.
+3. **`run_onchange_*` scripts.** Provisioning is declarative and idempotent: install packages before dotfiles are written, replay editor extension manifests when they change. Re-running is safe.
+
+## The repo layout
+
+```text
+.chezmoi.toml.tmpl                 generates per-machine config on `chezmoi init`
+.chezmoiignore                     per-OS exclusions (target paths, not source names)
+.chezmoitemplates/                 shared content included by several targets
+  vscode-settings.json             the real VS Code settings
+  positron-settings.json           the real Positron settings
+dot_bashrc.tmpl                    -> ~/.bashrc     (Windows)
+dot_zshrc.tmpl                     -> ~/.zshrc      (Ubuntu)
+dot_gitconfig.tmpl                 -> ~/.gitconfig
+dot_config/shell/aliases.sh.tmpl   -> ~/.config/shell/aliases.sh   (both shells)
+dot_config/shell/env.sh.tmpl       -> ~/.config/shell/env.sh       (both shells)
+dot_config/ghostty/config          -> ~/.config/ghostty/config     (Ubuntu)
+dot_claude/                        -> ~/.claude     (Claude Code config)
+AppData/Roaming/Code|Positron/     -> editor config (Windows)
+dot_config/Code|Positron/          -> editor config (Ubuntu)
+*-extensions.txt                   extension manifests, replayed by run_onchange_
+run_onchange_*                     provisioning scripts
+```
+
+A few things worth calling out:
+
+- **The `dot_` prefix is chezmoi's convention** — a source file called `dot_zshrc.tmpl` becomes `~/.zshrc`.
+- **Editor settings live in exactly one place.** VS Code reads from `%APPDATA%\Code\User` on Windows and `~/.config/Code/User` on Linux, so both trees exist in the repo — but each is a one-line file that includes the same shared template from `.chezmoitemplates/`. `.chezmoiignore` excludes the irrelevant tree per OS.
+- **What's templated is only what actually diverges** — aliases (OneDrive paths, `start msedge`, winpty wrappers are work-only), env (R/rv paths), gitconfig (`autocrlf` `false` vs `input`, the gh credential helper on Linux only). VS Code keys with `.windows` / `.linux` suffixes are left untemplated because VS Code selects those at runtime.
+- **`~/.claude` is the biggest subtree** — ten agents, thirty-plus skills, hooks, commands and rules. That's the AI-testing payload riding along with the shell config.
+
+## Bootstrapping the Ubuntu laptop
+
+The whole point of a dotfiles repo is that a new machine gets set up without you remembering anything. The laptop bootstrap is three commands:
+
+```bash
+sh -c "$(curl -fsLS get.chezmoi.io)" -- -b "$HOME/.local/bin"
+export PATH="$HOME/.local/bin:$PATH"
+chezmoi init --apply --source="$HOME/projects/dotfiles" https://github.com/stevecrawshaw/dotfiles.git
+```
+
+`chezmoi init` generates `~/.config/chezmoi/chezmoi.toml` from `.chezmoi.toml.tmpl`, deriving `machine = "personal"` from the OS (the work box gets `machine = "work"` from Windows). Because the `run_onchange_before_00-ubuntu-packages.sh` script runs *before* any dotfiles are written, the shells and tools the rc files expect already exist:
+
+- apt packages — zsh, git, fzf, ripgrep, build tooling, R, `gh` (from GitHub's own apt repo, because Ubuntu's build lags)
+- `uv`, radian (the R console VS Code uses), oh-my-posh, and the JetBrainsMono Nerd Font the prompt theme needs
+- chezmoi itself, plus reminders to run `gh auth login` and `chsh -s zsh`
+
+The script is honest about what it can't do: VS Code, Positron and Ghostty need manual downloads (it prints the links). Install those, run `cza` again, and the extension-sync script picks up the editor CLIs and replays the manifests.
+
+## Daily workflow
+
+The aliases make the loop short enough to be habit:
+
+```bash
+czd     # chezmoi diff     -- what would change on this machine
+cza     # chezmoi apply    -- write source -> $HOME
+czu     # chezmoi update   -- git pull + apply. The everyday sync.
+czs     # chezmoi status
+czr     # chezmoi re-add   -- pull edits you made directly in $HOME back to source
+czcd    # cd to this repo
+aka     # edit the shared aliases file
+```
+
+The typical loop after changing something:
+
+```bash
+czr && czcd && git add -A && git commit -m "feat: ..." && git push
+# then on the other machine
+czu
+```
+
+<div class="callout warning">
+**The one rule:** do not edit a managed file in `$HOME` and then run `cza` — apply overwrites `$HOME` from source. Run `czr` first to capture the edit. `czd` tells you which direction you're out of sync in.
+</div>
+
+`czr` is the alias I use most, because the AI harnesses edit config too. When Claude Code adds a skill or tweaks a rule under `~/.claude`, that edit starts life in `$HOME` — `czr` pulls it back into source so the next `czu` on the other machine picks it up.
+
+## Secrets
+
+Nothing in the repo is encrypted, so nothing secret goes in it. Per-machine secrets live in `~/.env.local`, which is untracked and sourced by both `.bashrc` and `.zshrc` if present:
+
+```bash
+# ~/.env.local
+export SOME_API_TOKEN="..."
+```
+
+Also deliberately excluded by `.chezmoiignore`: `~/.claude/.credentials.json`, `settings.local.json` (per-machine permission grants), and every Claude Code runtime directory (`projects/`, `sessions/`, `tasks/`, `plugins/`, `history.jsonl`). Those are machine state, not configuration — they'd conflict on every sync. If a real secret ever needs to live in the repo, the escape hatch is `chezmoi add --encrypt` with age.
+
+## Gotchas
+
+- **`~/.claude` is no longer its own git repo.** It was previously tracked at `github.com/stevecrawshaw/.claude`, now archived (read-only) with the full pre-chezmoi history. This repo is the only source of truth — editing a skill now needs `czr` like any other managed file.
+- **`alias bash="code ~/bash.sh"` had to go.** It shadowed the `bash` binary, which is the kind of footgun you only notice at the worst moment.
+- **`R_HOME` costs ~0.5s per interactive shell** because the env script invokes R to discover it. That's the tradeoff for never hardcoding a versioned path; the env file documents how to hardcode it if startup drags.
+- **`chezmoi init` regenerates `~/.config/chezmoi/chezmoi.toml`.** Never hand-edit that file — edit `.chezmoi.toml.tmpl` instead.
+- **The old Git-for-Windows alias file is stubbed out** (original kept as `.pre-chezmoi.bak` beside it). A Git upgrade may restore the stock version — harmless, since `~/.bashrc` is sourced afterwards and wins.
+
+## Learnings
+
+The migration paid off in the first month, mostly in ways I didn't predict:
+
+- **Templates earn their keep at the edges.** 90% of the config is identical on both machines; the templating handles the 10% that isn't (paths, autocrlf, credential helpers) without forking the files.
+- **Copy-not-symlink removes an entire class of Windows problems.** I never once thought about symlink privileges after switching. That alone justified chezmoi over the alternatives.
+- **Provisioning as code makes "nuke and reinstall" a legitimate strategy.** The bootstrap script is idempotent and re-runnable, so the AI-testing laptop can be rebuilt without fear — which is exactly the property you want on a machine whose whole job is running experimental software.
+- **AI tooling is the most valuable thing in the repo.** The Claude Code skills and agents took months to accumulate. Version-controlling them was the real motivation, and the shell config was the vehicle.
+
+If you're running more than one machine — and especially if one of them exists to break things on purpose — a chezmoi repo is worth the afternoon it takes to set up. The `czu` ritual is now the single best habit in my tooling.
+
+## Resources
+
+- [chezmoi](https://chezmoi.io)
+- [stevecrawshaw/dotfiles](https://github.com/stevecrawshaw/dotfiles)
+- [chezmoi quick start](https://www.chezmoi.io/quick-start/)