Skip to content

CONFIGURATION.md

Latest commit

 

History

History
251 lines (201 loc) · 6.97 KB

CONFIGURATION.md

File metadata and controls

251 lines (201 loc) · 6.97 KB
Raw

🔧 Configuration Documentation

This document provides detailed information about the Zsh configuration structure, components, and customization options.

📁 File Structure

zsh/
├── .zshrc              # Main configuration file
├── .zshenv             # Environment setup (sourced for all shells)
├── keybindings.zsh     # Custom keybindings and vi-mode enhancements
├── recovery.zsh        # Error recovery and validation system
├── setup.sh            # Installation and setup script
├── alias/              # Modular alias and function files
│   ├── core            # Basic aliases, modern tool integration
│   ├── git             # Git aliases and functions
│   ├── navigation      # Directory navigation helpers
│   ├── productivity    # System utilities and workflows
│   ├── fzf-enhancements # Enhanced FZF functions
│   ├── benchmark       # Performance testing tools
│   └── help            # Built-in help system
├── scripts/            # Shell scripts (zsh/, shell/)
├── README.md           # Main documentation
├── CONFIGURATION.md    # This file
└── .gitignore         # Version control exclusions

⚙️ Configuration Components

Core Configuration (.zshrc)

The main configuration file is organized into these sections:

  1. Startup Timing - Optional performance profiling
  2. Alias Loading - Sources all files from alias/ directory
  3. Keybindings - Loads custom key mappings
  4. Recovery System - Error handling and validation
  5. Zsh Options - Shell behavior settings
  6. History Configuration - Command history settings
  7. Completion System - Auto-completion setup
  8. Plugin Management - Zinit plugin loader
  9. Tool Integration - Starship, zoxide, lazy-loading
  10. Environment Variables - FZF, paths, tool settings

Modular Alias System

Each file in alias/ serves a specific purpose:

alias/core

  • Personal aliases (so, vim, navigation shortcuts)
  • Modern tool integration with fallbacks
  • Conditional loading based on tool availability

alias/git

  • Comprehensive git aliases (g* series)
  • Interactive git functions (glog, gcheck)
  • Git workflow shortcuts

alias/navigation

  • Directory traversal shortcuts (.., ..., etc.)
  • Enhanced directory functions (take, ff, edit)
  • Zoxide integration shortcuts

alias/productivity

  • System utilities (sysinfo, port, weather)
  • File operations (backup, archive, extract)
  • Process management (pgrep, pkill-pattern)
  • Note-taking system

alias/fzf-enhancements

  • Enhanced file/content search (search, f)
  • Interactive history search (h)
  • Process management (pkill)
  • Directory navigation (j)
  • Environment browsing (env-search)

alias/benchmark

  • Performance testing (zsh-benchmark)
  • Startup timing (zsh-time, zsh-profile)

alias/help

  • Built-in documentation (zsh-help)
  • Function discovery (list-functions)
  • Quick help (help, tips)

🔌 Plugin Management

Zinit Configuration

  • Plugin Manager: Zinit for fast, parallel loading
  • Essential Plugins:
    • deja - Predictive command suggestions
    • fzf-tab - Fuzzy completion selection
    • zsh-autopair - Automatic delimiter pairing
    • zsh-syntax-highlighting - Command highlighting
    • zsh-vi-mode - Enhanced vi mode
  • Workflow Plugins:
    • zsh-alias-finder - Suggest aliases for commands
    • colored-man-pages-plus - Colorized manual pages
  • Annexes: Additional functionality modules

Plugin Organization

# Plugin loading in .zshrc
zinit light "jeffreytse/zsh-vi-mode"
zinit light "Aloxaf/fzf-tab"
zinit light "hlissner/zsh-autopair"
zinit light "Giammarco-Ferranti/deja"
zinit light "zsh-users/zsh-syntax-highlighting"

🛠 Tool Integration

Modern CLI Tools

Traditional Modern Alternative Alias Fallback
ls eza ls, ll, la, lt ✅
cat bat view, less ✅
grep ripgrep grep ✅
find fd find ✅

Enhanced Tools

  • FZF: Fuzzy finder with custom previews and keybindings
  • Starship: Fast, customizable prompt
  • Zoxide: Smart directory jumping with frecency
  • Atuin: Enhanced shell history

🚀 Performance Optimizations

Lazy Loading

Work that is not needed to render the initial prompt is deferred:

  • carapace - Advanced completion
  • luarocks - Lua environment initialization
  • Nonessential Zinit plugins, including syntax highlighting

Compilation

Configuration files are compiled with zcompile for faster loading.

Completion Caching

  • Daily cache refresh for completion system
  • Smart completion initialization

Benchmarking

Built-in tools to measure and monitor performance:

zsh-benchmark    # Comprehensive analysis
zsh-time         # Quick timing
zsh-profile      # Detailed profiling

🎨 Customization

Adding Custom Aliases

Create new files in alias/ directory:

# alias/custom
alias myalias="my command"

my_function() {
  echo "Custom function"
}

Environment Variables

  • Global: Add to .zshenv
  • Interactive: Add to .zshrc
  • Tool-specific: Add to relevant alias file

Keybindings

Modify keybindings.zsh or add to custom alias files.

Plugin Management

# Add new plugin
zinit light "user/plugin-name"

# Update all plugins
zinit update

# Remove plugin
zinit delete "user/plugin-name"

🚑 Recovery System

Health Monitoring

config-health     # Check configuration status
validate_config   # Test syntax

Backup System

backup_config     # Create timestamped backup
restore_config    # Restore from backup
cleanup_backups   # Remove old backups

Emergency Recovery

emergency_recovery  # Reset to minimal working config
safe_reload        # Validate before reloading

📊 Monitoring & Debugging

Performance Monitoring

  • Startup time tracking with zprof
  • Plugin load time analysis
  • Function execution profiling

Configuration Validation

  • Syntax checking before reload
  • Dependency verification
  • Health status reporting

Error Handling

  • Graceful fallbacks for missing tools
  • Error recovery mechanisms
  • Safe configuration loading

🔒 Security Considerations

Path Management

  • Careful PATH modifications
  • No automatic execution of local files
  • Secure tool installation checks

Function Safety

  • Input validation in custom functions
  • Safe parameter handling
  • Error condition management

📝 Development Guidelines

Code Organization

  • One responsibility per file
  • Clear function naming
  • Comprehensive error handling
  • Fallback mechanisms

Documentation

  • Inline help for all functions
  • Usage examples
  • Clear parameter descriptions

Testing

  • Configuration syntax validation
  • Function testing
  • Performance regression checks

For implementation details, see individual files. For usage help, run zsh-help.