cachyos/docs/chezmoi/README.md

How it works

Source layout, naming conventions, symlink mode, and the day-to-day chezmoi workflow for this repo.

The repo is a chezmoi source directory. It lives at ~/.local/share/chezmoi and its remote is env/cachyos (https://prad.codes/env/cachyos.git, branch main). A checkout elsewhere (~/Code/prad.codes/env/cachyos) works the same way when chezmoi is pointed at it with --source. chezmoi apply renders it into $HOME. The Installation page covers first-time setup.

Pages in this section

Page	Covers
Config and roles	.chezmoi.toml.tmpl: prompts, machine role, symlink mode, age encryption, template data
Packages and aliases	.chezmoidata/packages.yaml and .chezmoidata/aliases.yaml, and how they render
Apply scripts	Every run_* script: when it runs, what triggers it, what it does per OS and role
Externals and ignore rules	.chezmoiexternal.toml git clones and every .chezmoiignore.tmpl rule

Source layout

- .chezmoi.toml.tmpl
- .chezmoidata/
  - aliases.yaml
  - packages.yaml
  - skills.yaml
- .chezmoiexternal.toml
- .chezmoiexternals/
  - agent-root.toml
  - ghostty.toml
  - herdr.toml
  - kitty.toml
  - noctalia.toml
  - omp.toml
  - television.toml
  - tmux.toml
  - tmux-palette.toml
  - yazi.toml
- .chezmoiignore.tmpl
- .gitmodules
- .chezmoiscripts/
  - run_onchange_before_10-packages.sh.tmpl
  - run_onchange_after_15-tools.sh.tmpl
  - run_onchange_after_20-gh-extensions.sh.tmpl
  - run_onchange_after_25-skills.sh.tmpl
  - run_once_after_30-user-services.sh.tmpl
  - run_onchange_after_40-post.sh.tmpl
- run_onchange_after_build-bat-cache.sh.tmpl
- run_onchange_after_install-yazi-plugins.sh.tmpl
- dot_bashrc
- dot_zshrc
- dot_gitconfig.tmpl
- dot_config/
  - atuin/
  - bash/
  - bat/
  - drydock/
  - fish/
  - fontconfig/
  - gh/
  - gh-dash/
  - go/
  - herdr-nvim/
  - hunk/
  - lazydocker/
  - lazygit/
  - mimeapps.list
  - shell/
  - starship.toml
  - systemd/
  - topgrade.toml
  - umbriel/
  - xdg-terminals.list
  - yazi.toml.tmpl
  - zsh/
- dot_local/
  - bin/
- dot_leetcode/
- docs/
- README.md
- AGENTS.md

Path	Target	Purpose
.chezmoi.toml.tmpl	~/.config/chezmoi/chezmoi.toml	Config template rendered by chezmoi init. See Config and roles.
.chezmoidata/	—	YAML merged into template data (.packages, .aliases, .skills). See Packages and aliases and Skills.
.chezmoiexternal.toml	—	Git repos cloned into $HOME (nvim config, a bat syntax, tpm).
.chezmoiexternals/	—	One git-repo external per app: ghostty, kitty, tmux, tmux-palette, television, yazi, herdr, omp, noctalia, agent-root. Plain config repos cloned into ~/.config/<app>. See Externals and ignore rules.
.gitmodules	—	dot_config/fish is the only git submodule. See Submodules.
.chezmoiignore.tmpl	—	Target paths chezmoi skips; gates the Linux desktop layer by role.
.chezmoiscripts/, root run_*	—	Install and housekeeping scripts. See Apply scripts.
dot_config/	~/.config/	Per-tool config. Documented under Shell, Terminal, Tools, Desktop.
dot_local/bin/	~/.local/bin/	Standalone scripts shared by every shell.
dot_leetcode/	~/.leetcode/	leetcode CLI workspace state.
docs/, README.md, AGENTS.md	—	These docs, the repo README, and the agent rules. Listed in .chezmoiignore.tmpl, never applied.

Entries whose source name starts with . (.claude/, .crush/, .gitignore) are ignored by chezmoi automatically and stay repo-only. The docs are plain Markdown that Gitea renders; there is no site build.

Naming conventions

chezmoi encodes target names and attributes in source file names. These are the prefixes and suffixes the repo uses:

Source form	Meaning	Examples here
dot_	Target name starts with .	dot_config → ~/.config, dot_zshrc → ~/.zshrc
private_	Target has group/world permissions cleared (0600/0700)	dot_config/atuin/private_config.toml, dot_config/gh/private_config.yml, dot_config/hunk/private_state.json
executable_	Target gets the executable bit	Every script in dot_local/bin/
exact_	Directory is exact: entries in the target that are not in the source are deleted	None currently
empty_	File is kept even when empty	None currently
symlink_	Target is a symlink; file content is the link destination	None currently
.tmpl	Rendered with Go templates and chezmoi data	dot_gitconfig.tmpl, dot_config/shell/aliases.sh.tmpl, all scripts, the config and ignore files
run_once_ / run_onchange_ + before_ / after_	Script, with run frequency and phase	See Apply scripts

Prefixes stack in chezmoi's fixed order, e.g. private_dot_foo, executable_dot_bar. No source file currently uses encrypted_, even though age encryption is configured.

Symlink mode

.chezmoi.toml.tmpl sets mode = "symlink". chezmoi apply then makes each managed dotfile a symlink into the source tree instead of a copy, as long as the file is a plain regular file. Files that are templates, private_, executable_, or encrypted are still written as real files.

What that means in practice:

• Editing a plain file in $HOME (for example ~/.config/umbriel/binds.toml) edits ~/.local/share/chezmoi/dot_config/umbriel/binds.toml directly. The change is live and shows up in git status of the repo with no chezmoi add step.
• Templates are rendered copies. Editing ~/.gitconfig or ~/.config/shell/aliases.sh changes only the copy; the next chezmoi apply overwrites it. Edit the .tmpl source (chezmoi edit ~/.gitconfig) instead.
• private_ and executable_ targets are real files too. After editing one in place, run chezmoi re-add <path> to copy it back into the source.
• Tools that rewrite their own config write through the symlink into the repo. The runtime state that would otherwise pollute the source (plugin dirs, lock files, fish_variables, __pycache__) is excluded in .chezmoiignore.tmpl and .gitignore; see Externals and ignore rules.

Note

Several fish aliases (e.f, e.k, ,,) open the chezmoi source paths directly. Symlink mode makes that equivalent to editing the live config. e.y and e.t open the yazi and tmux external checkouts in ~/.config.

Daily workflow

Command	What it does here
chezmoi apply	Runs before_ scripts (package install), writes symlinks/files/templates into $HOME, clones missing externals, then runs after_ scripts.
chezmoi update	git pull in the source directory, then apply.
chezmoi diff	Shows what apply would change, including rendered templates and scripts that would run.
chezmoi add <path>	Moves a new file into the source tree under the right name. In symlink mode the target becomes a symlink on the next apply. Use --template or --encrypt for templated or secret files.
chezmoi re-add <path>	Copies edits made to non-symlinked targets (private, executable) back into the source.
chezmoi edit <path>	Opens the source file for a target, the right way to change templates.
chezmoi cd	Opens a shell in ~/.local/share/chezmoi for git work. The fish alias ,, opens yazi there instead.
chezmoi init --prompt	Re-asks name, email, and role and regenerates ~/.config/chezmoi/chezmoi.toml.

Commit and push from the source directory with plain git; the remote pushes over SSH (git@prad.codes:env/cachyos.git).