dotfiles

Configuration and packages for all my machines, managed with chezmoi (files) and metapac (packages).

Bootstrap a machine

sh -c "$(curl -fsLS https://git.nakama.town/fmartingr/dotfiles/raw/branch/main/install.sh)"

Then install the declared packages:

metapac sync

Docs

docs/ explains the decisions behind this setup — start there. Conventions for changing it are in AGENTS.md.

Layout

home/ maps into $HOME under chezmoi's usual naming (dot_, executable_, symlink_). Only the paths that are not self-evident:

.chezmoiroot                       -> "home"; keeps repo tooling out of $HOME
agents/knowledge/                  live ~/.agents/knowledge; outside home/ so chezmoi does not copy it
home/
  .chezmoidata/hosts.toml          the machine registry -- single source of truth
  .chezmoi.toml.tmpl               refuses to set up a host missing from it
  .chezmoitemplates/
    claude-settings.json           NOT applied; merged into settings.json
  dot_agents/
    symlink_knowledge.tmpl         ~/.agents/knowledge -> agents/knowledge
  dot_claude/
    modify_settings.json.tmpl      the script that merges it
  dot_config/metapac/groups/
    hosts/<hostname>.toml          per-host baseline; load-bearing, see docs
  private_Library/
    private_Application Support/
      symlink_metapac.tmpl         macOS: metapac's config dir -> ~/.config

Both Library levels are private_ so chezmoi leaves ~/Library at the mode macOS ships it with; see docs/config/metapac.md.

Everyday use

chezmoi edit ~/.config/foo	edit the source of a managed file
chezmoi diff	preview what would change in $HOME
chezmoi apply -v	apply changes
chezmoi add ~/.config/bar	start managing a new file
chezmoi cd	shell into the source repo
chezmoi update	git pull + apply
metapac sync	install packages missing from this host's groups
metapac unmanaged	list installed packages no group declares
metapac clean	uninstall unmanaged packages

Bootstrapping onto an existing checkout

install.sh clones into chezmoi's default source directory, ~/.local/share/chezmoi. If the repo is already checked out somewhere else, symlink it rather than keeping two copies — chezmoi init --source is not persisted, and the generated chezmoi.toml has nowhere to record a per-machine path:

ln -sfn ~/Code/dotfiles ~/.local/share/chezmoi

Pending work

Tracked in the tq queue under .tasks/; run tq ready to see what is unblocked.