clone-config

Files (1)

• SKILL.md

SKILL.md (first lines)

# clone-config — chezmoi dotfile workflow

chezmoi gives dotfiles a single source of truth: one Git repo, applied to every
machine with one command. Files in the source dir are named with prefixes
(`dot_`, `private_`) that map to locations in `$HOME`. You edit the source,
apply to `$HOME`; the target is always derived, never the authority.

The patterns below reflect the actual setup in `~/projects/dotfiles`:
`.zshrc`, `.zprofile`, `.p10k.zsh`, `.tmux.conf`, Yazi config, Kaku config,
Ghostty config, a `Brewfile`, and an install script that re-runs whenever
the Brewfile hash changes.

---

## Bootstrap a fresh machine

```bash
# 1. Install Homebrew (if missing)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install chezmoi and apply the dotfiles repo
brew install chezmoi
chezmoi init --apply git@github.com:YOUR_USER/dotfiles.git
```

One `chezmoi init --apply` does everything:

1. Writes all tracked source files to `$HOME`
2. Clones externals (oh-my-zsh, fzf-tab) declared in `.chezmoiexternal.toml`
3. Runs `run_onchange_install-packages.sh` → `brew bundle`, uv tools, npm globals, yazi plugins

After that the machine is fully provisioned. No separate install scripts to
remember, no manual symlinks.

---

## Layout conventions

| Source path | Applied to `$HOME` | Notes |
|---|---|---|
| `dot_zshrc` | `~/.zshrc` | `dot_` prefix → leading `.` |
| `dot_config/yazi/` | `~/.config/yazi/` | Nested `dot_config` works recursively |
| `private_Library/` | `~/Library/` | `private_` → chmod 0700 on the dir, 0600 on files |
| `.chezmoiexternal.toml` | — | Declares upstream repos cloned on apply (oh-my-zsh, fzf-tab) |
| `.chezmoiignore` | — | Paths inside source that chezmoi skips at apply time |
| `run_onchange_<name>.sh.tmpl` | — | Re-runs whenever file content (post-template) changes |
| `run_once_<name>.sh.tmpl` | — | Runs only on the very first apply |
| `Brewfile` | — | Consumed by the install script; not applied to `$HOME` directly |

**Key convention**: `dot_` → leading dot, `private_` → restricted permissions.
Both prefixes can be combined: `private_dot_ssh/` → `~/.ssh/` (mode 0700).

---

## Daily workflow

| Task | Command | Notes |
|---|---|---|
| Preview pending changes | `chezmoi diff` | Read-only; see what would change in `$HOME` |
| Apply pending changes | `chezmoi apply` | Write source state to `$HOME` |
| Edit a tracked file | `chezmoi edit ~/.zshrc` | Opens the **source**, not the target — critical |
| Jump into source repo | `chezmoi cd` | Drops you in `~/.local/share/chezmoi` |
| Pull remote + apply | `chezmoi update` | Equivalent to `git pull` + `chezmoi apply` |
| Reconcile after target edit | `chezmoi re-add ~/.zshrc` | Rescue: pulls target back into source |
| Track a new file | `chezmoi add ~/path/to/file` | Copies file into source with correct prefix |

The source repo lives at `~/.local/share/chezmoi` by default. `chezmoi cd`
is the fastest way in; treat it like any Git repo once there.

---

## Adding a new file

```bash
# 1. Tell chezmoi to track the file (copies it into source)
chezmoi add ~/some/config

# 2. Commit from inside the source repo
chezmoi cd
git add -A && git commit -m "track some/config"
git push  # or: open a PR if the dotfiles repo enforces review
```

After `git push`, any other machine running `chezmoi update` picks up the file.

---

## The run_onchange installer pattern

This is the high-leverage part of the setup. A single templated script
orchestrates all package management and re-runs automatically whenever its
content changes — including whenever the embedded Brewfile hash changes.

Actual content of `run_onchange_install-packages.sh.tmpl`:

```bash
#!/usr/bin/env bash
# Re-runs whenever this file changes (including Brewfile hash below).
# Manages: homebrew, uv tools, npm globals, yazi plugins.
set -euo pipefail

# Brewfile hash: {{ include "Brewfile" | sha256sum }}

echo "==> brew bundle"
brew bundle --no-lock --file="{{ joinPath .chezmoi.sourceDir "Brewfile" }}"

echo "==> uv tools"
for tool in claude-code-telegram fb-idb specify-cli; do
    uv tool install --quiet "$tool" || true
done

echo "==> npm globals (requires an fnm-managed node on PATH)"
if command -v npm >/dev/null 2>&1; then
    npm install -g --silent \
        @cometix/ccline \
        @openai/codex \
        agent-browser \
        clawhub \
        eas-cli \

From danmestas/wardrobe, MIT.

More from danmestas/wardrobe