Dotfiles Best Practices
Reference knowledge for modern dotfiles configuration, organization, and tooling. Serves as the knowledge base for the dotfiles-optimizer orchestrator.
User-Specific Decisions
Theme: Catppuccin Macchiato across all tools (set via $THEME_FLAVOUR=macchiato)
Shell structure: Modular zsh.d/ with numeric prefix load ordering:
zsh/zsh.d/
├── 00-env.zsh # Environment variables, PATH
├── 10-options.zsh # Shell options (setopt)
├── 20-completions.zsh # Completion system
├── 30-plugins.zsh # Plugin loading
├── 40-lazy.zsh # Lazy loading functions
├── 50-keybindings.zsh # Key bindings
├── 60-aliases.zsh # Command aliases
├── 70-functions.zsh # Custom functions
├── 80-integrations.zsh # External tool integrations
└── 99-local.zsh # Local overrides (NOT committed)
Main .zshrc sources all modules:
export ZSH="$HOME/.dotfiles/zsh"
for config_file in "$ZSH/zsh.d"/*.zsh(N); do
source "$config_file"
done
Reference Files
| File | Contents |
|---|---|
| modern-cli-tools.md | eza, bat, fd, rg, zoxide, starship, delta, lazygit |
| shell-performance.md | Startup optimization, lazy loading pattern, profiling |
| security-patterns.md | Credentials, file permissions, history security, .gitignore |
| git-config.md | Multi-identity includeIf, aliases |
| terminal-config.md | Kitty, Ghostty, tmux, neovim, Catppuccin theming |
Gotchas
- Claude tends to suggest Powerlevel10k over Starship -- this setup uses Starship for cross-shell compat and speed
- NVM lazy loading is critical -- eagerly sourcing nvm.sh adds 200-400ms to startup
- Never alias over system commands unconditionally -- check tool exists first with
command -v - The
99-local.zshpattern means local overrides are NOT committed -- don't suggest editing them as shared config - File permissions on
.envand git config files must be 600, not 644
Quick Reference
Performance: Shell startup <500ms, lazy load version managers, cache completions
Security: Never commit secrets, use .env + .env.example pattern, sensitive files chmod 600
Organization: Modular numeric-prefix structure, separate concerns, local overrides in 99-local.zsh
Modern Tools: eza (ls), bat (cat), fd (find), rg (grep), z (cd) -- check existence before aliasing
Git: Multi-config with includeIf, separate personal/work identities, commit signing recommended
Themes: Consistent Catppuccin Macchiato across all tools, single $THEME_FLAVOUR variable
Converted and distributed by TomeVault — claim your Tome and manage your conversions.