dotfiles

Zsh Configuration Reference

Overview

Zsh shell configuration using Znap plugin manager, Starship prompt, and extensive customizations for a productive terminal environment.

Synopsis

~/.zshenv              # Environment variables (always sourced)
~/.zshrc               # Interactive shell configuration
~/.config/zsh/         # Additional configuration files
├── functions/         # Custom shell functions
└── completion/        # Custom completions

File Loading Order

graph TD
    A[Terminal Start] --> B{Login Shell?}
    B -->|Yes| C[/etc/zshenv]
    B -->|No| C
    C --> D[~/.zshenv]
    D --> E{Login Shell?}
    E -->|Yes| F[/etc/zprofile]
    E -->|No| H
    F --> G[~/.zprofile]
    G --> H{Interactive?}
    H -->|Yes| I[/etc/zshrc]
    H -->|No| L
    I --> J[~/.zshrc]
    J --> K{Login Shell?}
    K -->|Yes| L[/etc/zlogin]
    K -->|No| M[Shell Ready]
    L --> M

Configuration Files

`~/.zshenv`

Sourced for all Zsh instances. Keep minimal for performance.

Current Contents:

# This file is sourced by all instances of Zsh, and thus should be kept as
# small as possible and should only define environment variables.

Purpose:

Set PATH modifications
Export environment variables
Set ZDOTDIR if using XDG structure

`~/.zshrc`

Main configuration for interactive shells.

Structure:

Znap plugin manager setup
Environment variables
Plugin loading
Starship prompt initialization
Aliases and functions
Completions setup
Key bindings

Key Components

Znap Plugin Manager

Installation Path: ~/znap/zsh-snap

Loaded Plugins:

ohmyzsh/ohmyzsh - Framework for configurations
zsh-users/zsh-autosuggestions - Fish-like suggestions
zsh-users/zsh-completions - Additional completions
marlonrichert/zsh-autocomplete - Real-time completions

Environment Variables

Path Configuration

Path additions in order:

$HOME/bin                    # Personal scripts
$HOME/.local/bin            # User installations
/opt/homebrew/bin           # Homebrew (Apple Silicon)
/usr/local/bin              # Traditional installs
$GOPATH/bin                 # Go binaries
$HOME/.cargo/bin            # Rust binaries
$DVM_DIR/bin                # Deno versions
$HOME/.claude/local         # Claude CLI
$HOME/.dotnet/tools         # .NET tools

Aliases

File Management: | Alias | Command | Description | |——-|———|————-| | ll | ls -la | Long listing with hidden files | | la | ls -A | List all except . and .. | | l | ls -CF | Classify file types |

Directory Navigation: | Alias | Command | Description | |——-|———|————-| | .. | cd .. | Parent directory | | ... | cd ../.. | Two levels up | | .... | cd ../../.. | Three levels up |

Git Shortcuts: | Alias | Command | Description | |——-|———|————-| | g | git | Git shorthand | | gst | git status | Status shorthand | | gco | git checkout | Checkout shorthand |

Development: | Alias | Command | Description | |——-|———|————-| | py | python3 | Python 3 | | pip | pip3 | Pip 3 | | serve | python3 -m http.server | Simple HTTP server |

Functions

Custom functions are stored in ~/.config/zsh/functions/:

Available Functions:

mkcd - Create directory and cd into it
extract - Universal archive extractor
backup - Create timestamped backups
fzf-git-branch - Fuzzy find git branches

Example Function:

# mkcd - Make directory and change to it
mkcd() {
    mkdir -p "$1" && cd "$1"
}

Completion System

Initialization:

autoload -Uz compinit && compinit

Settings:

Case-insensitive matching
Partial word completion
Menu selection with arrow keys
Colored completion listings

Custom Completions: Located in ~/.config/zsh/completion/

Key Bindings

Starship Prompt

Configuration: ~/.config/starship.toml

Features:

Git status integration
Language version display
Command execution time
Exit code indicators
Directory truncation

Customization Example:

[directory]
truncation_length = 3
truncate_to_repo = false

[git_branch]
symbol = "🌱 "
truncation_length = 20

Performance Optimization

Lazy Loading

Commands evaluated on first use:

znap eval rbenv 'rbenv init -'
znap eval pyenv 'pyenv init -'

Compilation

Zsh compiles scripts to .zwc files for faster loading:

zcompile ~/.zshrc
zcompile ~/.config/zsh/functions/*

Debugging

Profiling Startup

# Add to beginning of .zshrc
zmodload zsh/zprof

# Add to end of .zshrc
zprof

Verbose Loading

# Start shell with verbose output
zsh -xv

Check Load Order

# Print each file as it's sourced
export ZSH_TRACE=1

Environment Detection

OS Detection

case "$OSTYPE" in
    darwin*)  # macOS specific
        export HOMEBREW_PREFIX="/opt/homebrew"
        ;;
    linux*)   # Linux specific
        export HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
        ;;
esac

Machine-Specific Config

# Load machine-specific settings
[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local