Zsh Configuration - Gentleman.Dots

Zsh (Z Shell) combines powerful scripting capabilities with excellent interactive features. The Gentleman.Dots configuration uses Oh-My-Zsh for plugin management and Powerlevel10k for a beautiful, fast prompt.

Overview

The Gentleman.Dots Zsh configuration provides:

Oh-My-Zsh framework for plugins and themes
Powerlevel10k prompt with instant loading
Gentleman LS_COLORS for beautiful file listings
Zsh plugins: autocomplete, syntax highlighting, autosuggestions
Starship, Zoxide, Atuin, FZF, and Carapace integrations
Automatic tmux session management
POSIX compatibility for script portability

Installation

Install Zsh

# Zsh comes pre-installed on macOS
# Or update to latest version
brew install zsh

Install Oh-My-Zsh

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Install Zsh Plugins

# Install via Homebrew (recommended)
brew install zsh-autocomplete
brew install zsh-syntax-highlighting
brew install zsh-autosuggestions
brew install powerlevel10k

# Or manually clone to Oh-My-Zsh custom folder
git clone https://github.com/zsh-users/zsh-autosuggestions \
    ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

Install Core Tools

# CLI enhancements
brew install starship zoxide atuin fzf carapace bat

# GNU ls for colors (macOS only)
brew install coreutils

Deploy Configuration

# Backup existing configs
mv ~/.zshrc ~/.zshrc.backup 2>/dev/null
mv ~/.p10k.zsh ~/.p10k.zsh.backup 2>/dev/null

# Copy Zsh configurations
cp GentlemanZsh/.zshrc ~/
cp GentlemanZsh/.p10k.zsh ~/

# Copy Starship config
cp starship.toml ~/.config/starship.toml

Set as Default Shell

# Verify Zsh is in /etc/shells
grep -q "$(which zsh)" /etc/shells || echo "$(which zsh)" | sudo tee -a /etc/shells

# Set as default
chsh -s $(which zsh)

Configure Powerlevel10k

# Start new Zsh session
zsh

# Powerlevel10k configuration wizard will run
# Or manually trigger:
p10k configure

Configuration Breakdown

Main Config (.zshrc)

Powerlevel10k Instant Prompt

Enables instant prompt for zero-lag startup:

.zshrc:1-6

if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

Instant prompt makes Zsh start in ~40ms. Keep slow-loading commands after this block.

Oh-My-Zsh Setup

.zshrc:8

export ZSH="$HOME/.oh-my-zsh"

Path Configuration

Comprehensive PATH for various package managers:

.zshrc:9

export PATH="$HOME/.local/bin:$HOME/.opencode/bin:$HOME/.cargo/bin:$HOME/.volta/bin:$HOME/.bun/bin:$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/usr/local/bin:$HOME/.config:$HOME/.cargo/bin:/usr/local/lib/*:$PATH"

Environment Variables

.zshrc:11-13

export EDITOR="nvim"
export VISUAL="nvim"

Gentleman LS_COLORS

Custom file type colors:

.zshrc:19

export LS_COLORS="di=38;5;67:ow=48;5;60:ex=38;5;132:ln=38;5;144:*.tar=38;5;180:*.zip=38;5;180:*.jpg=38;5;175:*.png=38;5;175:*.mp3=38;5;175:*.wav=38;5;175:*.txt=38;5;223:*.sh=38;5;132"

Homebrew Setup

Cross-platform Homebrew initialization:

.zshrc:20-35

if [[ "$(uname)" == "Darwin" ]]; then
    BREW_BIN="/opt/homebrew/bin"
else
    BREW_BIN="/home/linuxbrew/.linuxbrew/bin"
fi

eval "$($BREW_BIN/brew shellenv)"

Zsh Plugin Loading

.zshrc:37-40

source $(dirname $BREW_BIN)/share/zsh-autocomplete/zsh-autocomplete.plugin.zsh
source $(dirname $BREW_BIN)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
source $(dirname $BREW_BIN)/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source $(dirname $BREW_BIN)/share/powerlevel10k/powerlevel10k.zsh-theme

FZF Configuration

.zshrc:42-45

export PROJECT_PATHS="/home/alanbuscaglia/work"
export FZF_DEFAULT_COMMAND="fd --hidden --strip-cwd-prefix --exclude .git"
export FZF_DEFAULT_T_COMMAND="$FZF_DEFAULT_COMMAND"
export FZF_ALT_COMMAND="fd --type=d --hidden --strip-cwd-prefix --exclude .git"

Automatic Tmux Startup

.zshrc:47-56

WM_VAR="/$TMUX"
WM_CMD="tmux"

function start_if_needed() {
    if [[ $- == *i* ]] && [[ -z "${WM_VAR#/}" ]] && [[ -t 1 ]]; then
        exec $WM_CMD
    fi
}

start_if_needed

Aliases

.zshrc:58-60

alias fzfbat='fzf --preview="bat --theme=gruvbox-dark --color=always {}"'
alias fzfnvim='nvim $(fzf --preview="bat --theme=gruvbox-dark --color=always {}")'

Oh-My-Zsh Plugins

.zshrc:62-65

plugins=(
  command-not-found
)

source $ZSH/oh-my-zsh.sh

Tool Integrations

.zshrc:69-78

export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense'
zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m'
source <(carapace _carapace)

eval "$(fzf --zsh)"
eval "$(zoxide init zsh)"
eval "$(atuin init zsh)"

[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh

Oh-My-Zsh Plugins

Oh-My-Zsh includes 300+ plugins. Here are recommended additions:

Essential Plugins

plugins=(
  # Git
  git
  git-extras
  gitignore
  
  # Development
  docker
  docker-compose
  kubectl
  npm
  yarn
  
  # Utilities
  command-not-found
  colored-man-pages
  extract
  sudo
  
  # Languages
  node
  python
  rust
)

Plugin Highlights

git

Aliases like gst (status), gco (checkout), gp (push)

docker

Completions and aliases for Docker commands

kubectl

Kubernetes completions and k alias

extract

Universal extract command for all archive types

sudo

Press Esc twice to prefix command with sudo

colored-man-pages

Colorized man pages for better readability

Powerlevel10k Prompt

Powerlevel10k is configured via .p10k.zsh.

Configuration Wizard

Run the interactive wizard anytime:

p10k configure

The wizard lets you choose:

Prompt style (lean, classic, rainbow, etc.)
Character set (Unicode, ASCII)
Prompt colors
Prompt elements
Instant prompt mode

Key Features

Instant prompt: Appears in ~40ms
Git status: Shows branch, commits ahead/behind, stashes
Exit code: Displays if last command failed
Execution time: Shows duration of long commands
Context awareness: Adapts to Python venv, Node version, etc.

Customization

Edit .p10k.zsh directly or use wizard. Common customizations:

# Show time in prompt
typed -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(time)

# Change Git icons
typed -g POWERLEVEL9K_VCS_BRANCH_ICON=''

# Disable instant prompt
typed -g POWERLEVEL9K_INSTANT_PROMPT=off

Zsh Plugins (External)

Zsh-Autosuggestions

Fish-like command suggestions:

Suggests based on history and completions
Press → to accept suggestion
Press Alt+→ to accept one word
Customize color:
```
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=8'
```

Zsh-Syntax-Highlighting

Real-time syntax validation:

Green: Valid command
Red: Invalid command
Yellow: Alias
Blue: Built-in
Magenta: Command options

Zsh-Autocomplete

Enhanced completions:

Real-time suggestions as you type
Fuzzy matching
History substring search

Configurable:

zstyle ':autocomplete:*' min-input 2
zstyle ':autocomplete:*' max-lines 10

Key Features

POSIX Compatibility

Zsh can run most Bash scripts:

# Run Bash script in Zsh
zsh script.sh

# Enable strict Bash emulation
emulate bash -c 'source script.sh'

Powerful Globbing

# All .js files in subdirectories
ls **/*.js

# All files modified today
ls *(.m0)

History Features

Advanced history capabilities:

# Share history across sessions
setopt SHARE_HISTORY

# Don't save duplicates
setopt HIST_IGNORE_ALL_DUPS

# Search history
Ctrl+R              # Atuin/FZF search
history | grep foo  # Grep history
!foo               # Run last command starting with 'foo'

Directory Stack

# Push directory to stack
cd ~/project && pushd

# Switch between directories
cd ~/other
popd  # Back to ~/project

# View stack
dirs -v

# Jump to stack entry
cd ~3

Customization

Custom Aliases

Add to .zshrc:

# Git shortcuts
alias gs='git status'
alias gaa='git add -A'
alias gcm='git commit -m'
alias gp='git push'
alias gl='git pull'

# Directory shortcuts
alias ..='cd ..'
alias ...='cd ../..'
alias ll='ls -alFh'
alias la='ls -A'

# Safety nets
alias rm='rm -i'
alias mv='mv -i'
alias cp='cp -i'

Custom Functions

mkproj() {
    mkdir -p "$1"
    cd "$1"
    git init
    touch README.md
    echo "# $1" > README.md
}

Key Bindings

Custom key bindings:

# Ctrl+F for FZF file search
bindkey '^F' fzf-file-widget

# Ctrl+G for git status
bindkey -s '^G' 'git status\n'

# Alt+. insert last argument
bindkey '\e.' insert-last-word

Integration with Tools

Starship Prompt

You can use either Powerlevel10k or Starship, not both. The default config uses Powerlevel10k.

To switch to Starship:

# Comment out Powerlevel10k in .zshrc
# source $(dirname $BREW_BIN)/share/powerlevel10k/powerlevel10k.zsh-theme

# Enable Starship
eval "$(starship init zsh)"

Zoxide (Smart CD)

# Jump to directory
z dotfiles

# Interactive
zi

# Stats
zoxide query --stats

Atuin History

# Search (Ctrl+R)
atuin search

# Statistics  
atuin stats

# Import existing history
atuin import auto

FZF Integration

# File search
Ctrl+T

# Directory search
Alt+C

# History search
Ctrl+R

# Custom FZF commands
fzfbat     # Preview with bat
fzfnvim    # Open in neovim

Tips & Tricks

Global aliases work anywhere in command:

alias -g G='| grep'
alias -g L='| less'
alias -g J='| jq'

# Usage
ps aux G docker
cat file.json J '.data'

Suffix aliases for file types:

alias -s txt=nvim
alias -s {yml,yaml}=nvim
alias -s json=jq

# Usage (just type filename)
config.txt     # Opens in nvim
data.json      # Opens with jq

Parameter expansion:

file="document.txt"
echo ${file%.txt}        # document
echo ${file/doc/PDF}     # PDFument.txt
echo ${file:u}           # DOCUMENT.TXT

Oh-My-Zsh plugins can slow down shell startup. Use only what you need:

# Check startup time
time zsh -i -c exit

# Profile plugins
zsh -xv 2>&1 | less

Troubleshooting

Slow Startup

# Profile startup
zsh -xv 2>&1 | ts -i "%.s" | tee zsh-startup.log

# Disable instant prompt if causing issues
# Comment out in .zshrc:
# if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt...

Plugin Conflicts

# Disable all plugins temporarily
plugins=()

# Re-enable one at a time to find conflict

Completions Not Working

# Rebuild completion cache
rm -rf ~/.zcompdump*
autoload -U compinit && compinit

# Fix permissions
chmod 755 /usr/local/share/zsh
chmod 755 /usr/local/share/zsh/site-functions

Oh-My-Zsh Update Issues

# Manual update
omz update

# Or reinstall
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Learning Resources

Zsh Manual

Official Zsh documentation

Oh-My-Zsh Wiki

Plugin documentation and guides

Powerlevel10k

Prompt customization guide

Awesome Zsh

Curated plugins and themes

Next Steps

Explore Oh-My-Zsh plugins
Configure Tmux for session management
Set up Neovim as your editor
Learn FZF advanced usage

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Overview

​Installation

​Configuration Breakdown

​Main Config (.zshrc)

​Powerlevel10k Instant Prompt

​Oh-My-Zsh Setup

​Path Configuration

​Environment Variables

​Gentleman LS_COLORS

​Homebrew Setup

​Zsh Plugin Loading

​FZF Configuration

​Automatic Tmux Startup

​Aliases

​Oh-My-Zsh Plugins

​Tool Integrations

​Oh-My-Zsh Plugins

​Essential Plugins

​Plugin Highlights

git

docker

kubectl

extract

sudo

colored-man-pages

​Powerlevel10k Prompt

​Configuration Wizard

​Key Features

​Customization

​Zsh Plugins (External)

​Zsh-Autosuggestions

​Zsh-Syntax-Highlighting

​Zsh-Autocomplete

​Key Features

​POSIX Compatibility

​Powerful Globbing

​History Features

​Directory Stack

​Customization

​Custom Aliases

​Custom Functions

​Key Bindings

​Integration with Tools

​Starship Prompt

​Zoxide (Smart CD)

​Atuin History

​FZF Integration

​Tips & Tricks

​Troubleshooting

​Slow Startup

​Plugin Conflicts

​Completions Not Working

​Oh-My-Zsh Update Issues

​Learning Resources

Zsh Manual

Oh-My-Zsh Wiki

Powerlevel10k

Awesome Zsh

​Next Steps

Build docs developers (and LLMs) love

Overview

Installation

Configuration Breakdown

Main Config (.zshrc)

Powerlevel10k Instant Prompt

Oh-My-Zsh Setup

Path Configuration

Environment Variables

Gentleman LS_COLORS

Homebrew Setup

Zsh Plugin Loading

FZF Configuration

Automatic Tmux Startup

Aliases

Oh-My-Zsh Plugins

Tool Integrations

Oh-My-Zsh Plugins

Essential Plugins

Plugin Highlights

Powerlevel10k Prompt

Configuration Wizard

Key Features

Customization

Zsh Plugins (External)

Zsh-Autosuggestions

Zsh-Syntax-Highlighting

Zsh-Autocomplete

Key Features

POSIX Compatibility

Powerful Globbing

History Features

Directory Stack

Customization

Custom Aliases

Custom Functions

Key Bindings

Integration with Tools

Starship Prompt

Zoxide (Smart CD)

Atuin History

FZF Integration

Tips & Tricks

Troubleshooting

Slow Startup

Plugin Conflicts

Completions Not Working

Oh-My-Zsh Update Issues

Learning Resources

Next Steps