chezmoi

Files (8)

• SKILL.md
• bootstrap.md · references/
• docs-index.md · references/
• partial-files.md · references/
• pitfalls.md · references/
• scripts.md · references/
• secrets.md · references/
• templating.md · references/

SKILL.md (first lines)

# chezmoi

Manage dotfiles across machines with [chezmoi](https://chezmoi.io/): source-state semantics, Go templates, and at-rest encryption.

## Mental model

chezmoi maps a **source directory** (`~/.local/share/chezmoi`, a git repo) to a **target directory** (the user's home).
Source filenames carry attribute prefixes that set the target name and behavior.
chezmoi renders a source file with a `.tmpl` suffix as a Go `text/template`.
Files under `.chezmoitemplates/` are reusable fragments; they produce no target files.
A per-machine config file holds machine variables.

In this repo, the source tree is `$DOTFILES/chezmoi`. Edit its plain
and `.tmpl` files directly, then run `dots sync` to deploy (see
`AGENTS.md`). Only `encrypted_` files need `chezmoi edit`.

Most trouble has two causes:

1. Editing an `encrypted_` source file directly instead of `chezmoi edit $TARGET`. This breaks the decrypt round-trip. Editing a plain or `.tmpl` source file directly is normal; `chezmoi edit` only adds editor convenience there.
2. Committing plaintext secrets "because the repo is private". Repos leak, forks leak, and history is permanent.

## Config file vs. config template

Both accept `toml`, `yaml`, `json`, or `jsonc`, detected by extension.
Two formats present at the same time is an error, not "first one wins".

| File | Path | Who writes it |
|---|---|---|
| `chezmoi.<fmt>` (the *config*) | `$XDG_CONFIG_HOME/chezmoi/`, default `~/.config/chezmoi/`. **Not** in the source repo. | `chezmoi init` (or `apply --init`) generates it from the template. Per-machine. Holds tokens and machine settings; never commit it. |
| `.chezmoi.<fmt>.tmpl` (the *config template*) | Source-state root. **Committed** to the dotfiles repo. | You write it. Use `promptBoolOnce` / `promptChoiceOnce` / `promptStringOnce` so a fresh machine answers once on first init. |

Override the location with `--config <path>`; add `--config-format <fmt>` for an unusual extension.
Inspect effective values with `chezmoi cat-config` and `chezmoi dump-config`.

## Protocol

### 1. Route the request

| User says | Go to |
|---|---|
| "set up chezmoi from scratch" / "new machine" | §2, then `references/bootstrap.md` |
| "add this file to my dotfiles" | §3 |
| "make this dotfile depend on OS / host" | `references/templating.md` |
| "encrypt this" / "store this token" | `references/secrets.md` |
| "run a script on first apply" / script order | `references/scripts.md` |
| "only manage part of this file" | `references/partial-files.md` |
| "chezmoi did something weird" | `references/pitfalls.md` |

### 2. Bootstrap a new machine

This one-liner clones, renders templates, and applies:

```bash
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB_USERNAME
```

### 3. Add a file

```bash
chezmoi add ~/.zshrc                  # plain copy
chezmoi add --template ~/.gitconfig   # add as a template (.tmpl suffix added)
chezmoi add --encrypt ~/.ssh/config   # encrypted at rest
chezmoi chattr +template ~/.zshrc     # turn a managed file into a template
chezmoi edit ~/.zshrc                 # edit the SOURCE; handles decrypt + .tmpl
```

Then run the safe-apply ritual (§5).

### 4. File-naming reference

Prefixes must appear in a fixed order, and the allowed set depends on the target type.
The canonical source is `/reference/source-state-attributes/`.

| Prefix | Effect on target |
|---|---|
| `dot_` | Add a leading `.` (`dot_zshrc` → `~/.zshrc`) |
| `private_` | Remove group and world permissions (0600 / 0700) |
| `readonly_` | Remove all write bits |
| `executable_` | Add the executable bit |
| `empty_` | Keep an empty file (the default removes it) |
| `encrypted_` | Decrypt the source with age/gpg before writing the target |
| `symlink_` | Create a symlink; the file content is the link target |
| `exact_` (dirs) | Delete target entries that the source does not have |
| `create_` | Create the target only when it is missing; never overwrite |
| `modify_` | The source is a script or template that produces the target content |
| `run_` | The source is a script to run, not a target file |
| `before_` / `after_` | Order scripts relative to file updates |
| `once_` (scripts) | Run only when these contents never ran successfully |
| `onchange_` (scripts) | Run only when the contents change for this filename |
| `remove_` | Remove the target if it exists |
| `external_` (dirs) | Mark an external directory (pairs with `.chezmoiexternal.<fmt>`); child attributes are ignored |
| `literal_` (anywhere) | Stop parsing attributes from this point |

Allowed order per target type (another order is a parse error):

| Target type | Allowed prefixes (in order) | Optional suffix |
|---|---|---|
| Directory | `remove_`, `external_`, `exact_`, `private_`, `readonly_`, `dot_` | — |
| Regular file | `encrypted_`, `private_`, `readonly_`, `empty_`, `executable_`, `dot_` | `.tmpl` |
| Create file | `create_`, `encrypted_`, `private_`, `readonly_`, `empty_`, `executable_`, `dot_` | `.tmpl` |
| Modify file | `modify_`, `encrypted_`, `private_`, `readonly_`, `executable_`, `dot_` | `.tmpl` |
| Remove file | `remove_`, `dot_` | — |
| Script | `run_`, `once_` or `onchange_`, `before_` or `after_` | `.tmpl` |
| Symlink | `symlink_`, `dot_` | `.tmpl` |

chezmoi strips `.age` / `.asc` when the matching encryption is configured.

### 5. Safe-apply ritual

Before an apply that touches important files, inspect the plan:

```bash
chezmoi status              # one line per changed file
chezmoi diff                # unified diff of pending changes
chezmoi apply --dry-run -v  # full plan, including scripts that would run
chezmoi apply               # only after the above looks right
```

For routine pulls on a trusted machine:

From paulnsorensen/dotfiles, MIT.

More from paulnsorensen/dotfiles