Skip to content

Repository Structure

Overview

The repo uses .chezmoiroot to separate chezmoi's source state from repo-level files. The home/ directory is the chezmoi source root; everything outside it (tests, hooks, docs) lives at the repo root without being deployed to $HOME.

.
├── .chezmoiroot              # Contains "home" — tells chezmoi where source state lives
├── home/                     # Chezmoi source state (deployed to $HOME)
│   ├── .chezmoi.toml.tmpl    # Per-machine config (platform flags, brew prefix)
│   ├── .chezmoidata/         # Shared template data (data.yaml, packages.yaml)
│   ├── .chezmoiexternals/    # External archives (Oh My Zsh, plugins, Nerd Fonts)
│   ├── .chezmoiignore        # Modular ignore (includes chezmoiignore.d/ templates)
│   ├── .chezmoiscripts/      # Lifecycle scripts (run_once_, run_onchange_, run_after_)
│   ├── .chezmoitemplates/    # Reusable templates (chezmoiignore.d/, init-brew, etc.)
│   ├── Brewfile.tmpl         # Rendered from packages.yaml
│   ├── Justfile.tmpl         # Just module registration
│   ├── dot_config/           # App configs (Ghostty, Fastfetch, Oh My Posh, nvim)
│   ├── dot_just/             # Justfile recipes and module help files
│   ├── dot_zshenv.tmpl       # Environment variables and PATH setup
│   ├── dot_zshrc.d/          # Modular shell configuration
│   └── private_dot_ssh/      # SSH config and sockets directory
├── tests/                    # Test suites
│   ├── bats/                 # Shell script tests (git hooks, statusline)
│   ├── docker/               # Dockerfile + entrypoint templates for smoke tests
│   └── just/                 # Pytest suite for just module contracts
├── hooks/lib/                # Project-specific hook scripts invoked by the pre-commit framework
├── .pre-commit-config.yaml   # Pre-commit framework config (betterleaks, conventional commits, policy hooks)
├── docs/                     # Documentation site (zensical)
├── README.md                 # Project overview and quick start
└── LLM.md                   # AI agent instructions (→ CLAUDE.md)

Chezmoi Special Directories

Directory Purpose
.chezmoidata/ Shared template data: data.yaml (status, repo, just modules),
packages.yaml (all package declarations — brew and OS)
.chezmoiexternals/ External archives managed by chezmoi with configurable refresh
intervals (Oh My Zsh, zsh plugins, Nerd Fonts)
.chezmoiscripts/ Lifecycle scripts executed during chezmoi apply — see Script Lifecycle
.chezmoitemplates/ Reusable template snippets included via includeTemplate
(e.g., init-brew.tmpl, confirmation.tmpl, chezmoiignore.d/)

Key Files

File Purpose
.chezmoi.toml.tmpl Chezmoi configuration: user prompts, platform detection
(.isBluefin, .isMacos, .isLinux), template data
.chezmoiignore Modular ignore — includes per-platform templates
from .chezmoitemplates/chezmoiignore.d/
Brewfile.tmpl Rendered from .chezmoidata/packages.yaml — see Package Data Convention