dotfiles/docs/meta-configs.md

Meta-Configs Pattern

This repository uses a meta-config pattern for configuration files that drive imperative actions during chezmoi apply, rather than being deployed directly to the filesystem.

What are Meta-Configs?

Meta-configs are configuration files that:

1. Are NOT deployed to the target system
2. Drive scripts that perform imperative actions (downloads, installations, modifications)
3. Live in meta/ at the repository root (outside home/)
4. Trigger run_onchange_* scripts when their content changes

This pattern separates "what to configure" from "configuration files that get deployed."

Directory Structure

chezmoi/
├── meta/                    # Meta-configs (NOT deployed)
│   ├── fonts.toml           # Drives font installation
│   └── ...                  # Future meta-configs
├── home/                    # Deployed to $HOME
│   ├── .config/
│   ├── .local/
│   └── ...
└── docs/
    └── meta-configs.md      # This file

Current Meta-Configs

meta/fonts.toml

Drives the install-fonts.ts script to download and install fonts.

[ui]
primary = "Inter"
fallback = "Noto Sans"

[mono]
primary = "Geist Mono"
fallback = "JetBrains Mono"

[extras]
# Fonts to install without category assignment
fonts = ["ZedMono NF"]

Triggered by: run_onchange_after_install-fonts.sh.tmpl

Script: ~/.local/bin/install-fonts.ts

How It Works

1. Edit a meta-config in meta/ (e.g., meta/fonts.toml)
2. Run chezmoi apply
3. Chezmoi detects the file changed via {{ include "../meta/fonts.toml" | sha256sum }}
4. The corresponding run_onchange_* script executes
5. The script reads the meta-config and performs imperative actions

Why This Pattern?

Problem

Some configuration requires imperative actions:

• Downloading files from the internet
• Installing packages
• Modifying system state

These don't fit the declarative "deploy this file" model of chezmoi.

Solution

Meta-configs provide:

• Centralized configuration - Easy to edit, version-controlled
• Imperative execution - Scripts perform the actual work
• Change detection - run_onchange_* only runs when config changes
• Clear separation - Meta-configs are clearly not "files to deploy"

Adding a New Meta-Config

1. Create meta/<name>.toml with your configuration schema
2. Create a script in home/dot_local/bin/ to process the config
3. Create home/run_onchange_after_<name>.sh.tmpl that:
   • Includes a hash comment: # hash: {{ include "../meta/<name>.toml" | sha256sum }}
   • Calls your processing script
4. Document the meta-config in this file

Comparison with .managed/

Aspect	meta/	.managed/
Deployed	No	Yes (via symlinks)
Purpose	Drive imperative scripts	Source of truth for app configs
Consumed by	Chezmoi scripts	Applications (via symlinks)
Location	Repo root	Inside home/