zsh-config-manager

name: zsh-config-manager description: Use when adding shell configuration for a new tool, creating zsh component files, configuring shell completions, using yadm alternates for OS-specific shell config, or troubleshooting modular zsh setup in conf.d structure.

Zsh Configuration Manager

Manage modular zsh configuration in the ~/.zshrcd/ directory structure with automatic sourcing, yadm tracking, and OS-specific alternates.

Configuration Structure

~/.zshrcd/
├── .zshrc              # Main config - loads conf.d/*.zsh
├── .zprofile           # Login shell profile
├── conf.d/             # Component files (auto-sourced)
│   ├── aliases.zsh
│   ├── docker.zsh
│   ├── homebrew.zsh##os.Darwin
│   └── kubectl-completion.zsh
├── completions/        # Custom completion functions
└── antigenrc           # Antigen plugin configuration

Adding New Tool Configuration

1. Create Component File

# ~/.zshrcd/conf.d/tool-name.zsh

# Environment setup
export TOOL_HOME="$HOME/.tool"
path+=("$TOOL_HOME/bin")

# Aliases
alias tool='tool-command'

# Completions (guard with command check)
if command -v tool >/dev/null 2>&1; then
    source <(tool completion zsh)
fi

2. Track with Yadm

yadm add ~/.zshrcd/conf.d/tool-name.zsh
yadm commit -m "Add tool-name zsh configuration"
yadm push

OS-Specific Configuration (Alternates)

For configurations that differ by OS:

# Create OS-specific versions
~/.zshrcd/conf.d/homebrew.zsh##os.Darwin    # macOS
~/.zshrcd/conf.d/homebrew.zsh##os.Linux     # Linux

# YADM creates symlink automatically:
# ~/.zshrcd/conf.d/homebrew.zsh → homebrew.zsh##os.Darwin

Environment or class-specific:

~/.zshrcd/.zprofile.local##class.Work
~/.zshrcd/.zprofile.local##class.Personal

Quick Reference

Best Practices

One component per file - Easier to maintain, can enable/disable by removing file

Guard commands:

if command -v kubectl >/dev/null 2>&1; then
    # kubectl-specific config
fi

Meaningful names:

• docker.zsh not docker-config.zsh
• kubectl-completion.zsh not k8s-stuff.zsh

Never source directly in .zshrc - The auto-sourcing loop handles it:

# In .zshrc (already configured)
for file in $ZDOTDIR/conf.d/*.zsh; do
    source $file
done

Common Mistakes