dotfiles

name	dotfiles
description	Use when creating scripts for dotfiles, adding files to dotfiles, working in any DOTFILES path, or when user says "dotfiles" or "my scripts" - covers script placement, PATH setup, full-update system, and dotfiles structure

Dotfiles Layout

Environment Variables

Variable	Path	Description
DOTFILES	~/.dotfiles/public	Main public dotfiles repo
DOTFILES_*	varies	Additional dotfiles repos (pattern: DOTFILES_FOO)

How they're set:

• DOTFILES: derived in zsh/.zshenv from symlink target of ~/.zshrc
• Additional repos: export DOTFILES_NAME=/path in their zsh/.zshenv (sourced via ~/.zshenv.local)

Directory Structure

${DOTFILES}/
  .bin/                    # Symlinks to scripts (auto-generated)
  full-update/             # Update scripts (numbered for ordering)
  non-user/                # System files (requires sudo)
    _archlinux/            # Arch Linux specific
    ${HOST_DOTFILES}/      # Host-specific system files
  scripts/
    terminal/              # Always in PATH
    commands/${CMD}/       # Only in PATH if ${CMD} exists
    hosts/${HOST}/         # Only in PATH on matching host
    media/                 # Only on mars/phobos/sol
  zsh/
    .zshenv                # Sets DOTFILES, sources plugins
    .zshrc                 # Shell config, sources plugins
    functions/             # zsh functions (fpath)
    plugins/${NAME}/       # Plugin .zshenv/.zshrc files
    hosts/${HOST}/         # Host-specific zsh config

PATH Setup

Order (first wins):

1. ~/.local/bin - user-local binaries
2. "${DOTFILES}/.bin" - auto-generated symlinks to scripts
3. System PATH

Script Linking (dotfiles-link-bin)

"${DOTFILES}/.bin/" contains symlinks generated by "${DOTFILES}/scripts/terminal/dotfiles-link-bin":

Always linked:

• "${DOTFILES}/scripts/terminal/*"
• "${DOTFILES_*}/scripts/terminal/*" (all DOTFILES_ repos)

Conditionally linked:

• "scripts/commands/${CMD}/*" - only if ${CMD} is in PATH
• "scripts/hosts/${HOST}/*" - only on matching hostname
• "scripts/media/*" - only on mars/phobos/sol hosts

full-update System

full-update runs numbered scripts from "${DOTFILES}/full-update/" and all "${DOTFILES_*}/full-update/":

full-update              # Run all scripts
full-update 60-zsh       # Run specific script from all repos

Numbering convention:

• 00-* - dotfiles sync (runs first, with --system flag)
• 10-* - OS-level updates (arch-linux, macos, termux, pikvm)
• 20-* - package managers (flatpak)
• 30-* - language toolchains (nvm, rust)
• 35-* - language tools (uv)
• 40-* - compiled tools (rust-tools)
• 50-* - container tools (podman)
• 60-* - application configs (most things)
• 65-* - derived configs (kde-color-schemes)
• 70-* - config files (ruff-config)
• 99-* - host-specific or finalization

How it works:

1. Runs 00-dotfiles --system first (git pull + non-user sync)
2. Runs all other scripts in numeric order
3. Processes ${DOTFILES} first, then each ${DOTFILES_*} alphabetically

non-user System Files

Files in non-user/ are synced to system paths with sudo:

${DOTFILES}/non-user/
  _archlinux/etc/...      # Synced on Arch Linux systems
  ${HOST_DOTFILES}/etc/...  # Synced on matching host only

Sync happens during full-update when --system flag is passed to 00-dotfiles.

zsh Plugin System

Plugins in "${DOTFILES}/zsh/plugins/${NAME}/" with optional:

• .zshenv - sourced early (env vars, PATH additions)
• .zshrc - sourced later (aliases, functions, completions)

Loading order:

1. "${DOTFILES}/zsh/.zshenv" - core setup, DOTFILES var
2. ~/.zshenv.local - sources private dotfiles zsh/.zshenv
3. "${DOTFILES}/zsh/plugins/*/.zshenv" - all plugin env files
4. "${DOTFILES}/zsh/hosts/${HOST}/.zshenv" - host-specific env
5. (later) .zshrc follows same pattern

Host-Specific Configuration

HOST_DOTFILES determines host identity:

• Default: ${HOST} (hostname)
• Override: set in ~/.zshenv.local

Used for:

• "${DOTFILES}/zsh/hosts/${HOST_DOTFILES}/" - shell config
• "${DOTFILES}/scripts/hosts/${HOST_DOTFILES}/" - host scripts
• "${DOTFILES}/non-user/${HOST_DOTFILES}/" - system files
• "${DOTFILES}/full-update/99-host-${HOST_DOTFILES}" - host update scripts

Adding New Scripts

Location	When to use
"${DOTFILES}/scripts/terminal/"	General tools, always available
"${DOTFILES}/scripts/commands/${CMD}/"	Tools requiring ${CMD} installed
"${DOTFILES}/scripts/hosts/${HOST}/"	Host-specific tools
"${DOTFILES}/scripts/media/"	Media tools (mars/phobos/sol only)

After adding, run dotfiles-link-bin to update symlinks.

Common Tasks

Add a terminal script:

# Create script
nvim "${DOTFILES}/scripts/terminal/my-script"
chmod +x "${DOTFILES}/scripts/terminal/my-script"
dotfiles-link-bin

Add command-dependent script:

# Only linked if 'kubectl' exists
mkdir -p "${DOTFILES}/scripts/commands/kubectl"
nvim "${DOTFILES}/scripts/commands/kubectl/my-k8s-tool"
chmod +x "${DOTFILES}/scripts/commands/kubectl/my-k8s-tool"
dotfiles-link-bin

Add full-update script:

nvim "${DOTFILES}/full-update/60-myapp"
chmod +x "${DOTFILES}/full-update/60-myapp"

Add system file (non-user):

# For all Arch systems:
mkdir -p "${DOTFILES}/non-user/_archlinux/etc/foo"
cp /etc/foo/config "${DOTFILES}/non-user/_archlinux/etc/foo/"

# For specific host:
mkdir -p "${DOTFILES}/non-user/${HOST_DOTFILES}/etc/foo"
cp /etc/foo/config "${DOTFILES}/non-user/${HOST_DOTFILES}/etc/foo/"

# Sync:
full-update 00-dotfiles  # with --system