omarchy/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 ~/Code/prad.codes/env/omarchy and chezmoi uses it as its source, either through chezmoi init --source ~/Code/prad.codes/env/omarchy or by cloning it into ~/.local/share/chezmoi; both are the same checkout model chezmoi expects. Its remote is env/omarchy (branch main). 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 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
  omarchy.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/
  hypr/
  lazydocker/
  lazygit/
  mimeapps.list
  shell/
  starship.toml
  systemd/
  topgrade.toml
  uwsm/
  waybar/
  xdg-terminals.list
  yazi.toml.tmpl
  zsh/
dot_local/
  bin/
dot_leetcode/
docs/
AGENTS.md
README.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 external per app or tool: agent-root, ghostty, herdr, kitty, omarchy, omp, television, tmux, tmux-palette, yazi. Plain config repos cloned into ~/.config/<app>. See Externals and ignore rules.
.gitmodules	—	dot_config/hypr and dot_config/fish are git submodules. 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/	37 standalone scripts shared by every shell, plus the omarchy-* helpers.
dot_leetcode/	~/.leetcode/	leetcode CLI workspace state.
docs/, AGENTS.md, README.md	—	These docs, the repo agent rules, and the repo README. Listed in .chezmoiignore.tmpl, never applied.

Entries whose source name starts with . (.claude/, .gitignore) are ignored by chezmoi automatically and stay repo-only.

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/
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/waybar/config.jsonc) edits the matching file in the source tree 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.h, 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 the source directory 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/omarchy.git).