Shell Modules (.zshrc.d/)¶

This repo uses a modular .zshrc.d/ pattern instead of managing ~/.zshrc directly. This allows chezmoi to coexist with system tools (like Bluefin's ublue-bling) that also modify ~/.zshrc. Environment variables ($PATH, Homebrew, etc.) are set in ~/.zshenv so they are available to all shell types. See Shell Initialisation for the full zsh loading order and the rationale behind this approach.

How It Works¶

A bootstrap script (run_once_before_01-setup-zshrc-sourcing.sh.tmpl) appends a sourcing block to ~/.zshrc if not already present. It uses a marker comment (# >>> chezmoi zshrc.d >>>) for idempotent operation. This block loops over ~/.zshrc.d/*.zsh and sources each file in order — the numeric prefix controls the loading sequence.

Module Catalogue¶

Module	Purpose
`00-init.zsh`	Shell initialisation (Oh My Zsh path, fastfetch)
`10-ohmyzsh.zsh`	Oh My Zsh plugins and sourcing
`20-prompt.zsh`	Starship/Oh-My-Posh initialisation
`30-tools.zsh`	Tool evals (direnv, atuin, zoxide)
`40-aliases.zsh`	CLI aliases (eza, bat, chezmoi)
`50-functions.zsh`	Shell functions (yazi wrapper)
`60-macos.zsh`	macOS-specific (VS Code helper, prompt toggle)
`99-local.zsh`	Machine-specific overrides (`create_` — never overwritten)

Adding Modules¶

Create numbered files (e.g., 45-myconfig.zsh.tmpl) to control load order. The numeric prefix determines when the module is sourced relative to others.

Tool Guards¶

Always guard tool initialisation with command -v:

if command -v zoxide &> /dev/null; then
    eval "$(zoxide init zsh)"
fi

Bluefin Compatibility¶

Use [{- if not .isBluefin }] to skip tools provided by ublue-bling.

Local Overrides¶

Use 99-local.zsh for machine-specific changes. The source uses create_ prefix so chezmoi only seeds an empty file — it will never overwrite your local edits, and chezmoi diff won't nag about changes you make. The trade-off is that your edits are local to that machine and not persisted in the repo.