Zvi's Dotfiles

Personal configuration files for zsh, git, and various development tools, managed with dotbot.

Features

• Modular zsh configuration - Clean, organized structure that's easy to maintain
• Portable across machines - Machine-specific settings separated from shared config
• Security-focused - Secrets never committed to git
• Well-documented - Comments and examples throughout
• Easy installation - One command setup on new machines
• Modern CLI tools - Integration with bat, eza, fd, ripgrep, delta, and more
• Enhanced productivity - 40+ useful aliases and 15+ utility functions
• FZF integration - Fuzzy finding for files, directories, git branches, and commits
• Smart completion - Case-insensitive, colored, with menu selection
• GitHub CLI power-user - 35+ gh aliases for efficient PR and workflow management

Structure

.dotfiles/
├── zsh/
│   ├── zshrc.history        # History configuration
│   ├── zshrc.functions      # Utility functions (pathadd, etc.)
│   ├── zshrc.aliases        # Common portable aliases
│   ├── zshrc.conditionals   # Optional tool configs (pyenv, nvm, colorls, etc.)
│   ├── zshrc.company        # Work-specific configuration
│   └── zshrc.local.example  # Template for machine-specific settings
├── gh/
│   └── config.yml           # GitHub CLI configuration with custom aliases
├── config/
│   └── git/
│       └── ignore           # Global git ignore patterns
├── gitconfig                # Git configuration
├── zshrc                    # Main zsh config (sources modular files)
├── p10k.zsh                 # Powerlevel10k theme configuration
├── install.conf.yaml        # Dotbot installation configuration
└── README.md                # This file

Installation

First-Time Setup (New Machine)

1. Install prerequisites:

   # macOS
   brew install zsh git
   
   # Ubuntu/Debian
   sudo apt update && sudo apt install zsh git

2. Clone this repository:

   git clone --recursive https://github.com/zvi-quantivly/dotfiles.git ~/.dotfiles
   cd ~/.dotfiles

3. Run the installer:

   ./install

4. Customize machine-specific settings:

   The installer creates ~/.zshrc.local from the template. Edit it to add:

   • API keys and tokens
   • Machine-specific PATH additions
   • SSH key configuration
   • Custom aliases for this machine

   vim ~/.zshrc.local  # or your preferred editor
   chmod 600 ~/.zshrc.local  # Ensure it's only readable by you

5. Install optional dependencies (see below)

Updating Existing Installation

cd ~/.dotfiles
git pull
./install

Utility Scripts

The scripts/ directory contains helpful tools for managing your dotfiles installation:

install-modern-tools.sh

Automated installation script for modern CLI tools (25+ tools). This script makes it easy to install optional enhancement tools without tracking down installation commands.

Usage:

./scripts/install-modern-tools.sh

Features:

• Interactive menu with installation categories:
  1. Essential tools (bat, eza, fd, ripgrep, zoxide, btop, etc.)
  2. Development tools (lazygit, just, hyperfine, difftastic, etc.)
  3. All tools (complete setup)
  4. Install specific tool
  5. Show tool status
• Automatically detects your package manager (apt, cargo, pip)
• Skips already-installed tools
• Provides fallback installation methods

When to use:

• After initial dotfiles installation to enhance your CLI experience
• When setting up a new machine
• To check what modern tools are available

verify-tools.sh

Checks installation status of all tools referenced in the dotfiles configuration.

Usage:

./scripts/verify-tools.sh

Shows:

• Required tools (zsh, git) with versions
• Strongly recommended tools (fzf, gh)
• Modern CLI replacements (bat, eza, fd, ripgrep, htop, delta)
• Version managers (nvm, pyenv)
• Optional tools (direnv, autojump, poetry, docker)
• Oh-My-Zsh plugins status

When to use:

• After installation to see what's missing
• Before reporting issues
• To verify your environment is set up correctly
• When troubleshooting configuration problems

Example output:

=== Dotfiles Tool Installation Status ===

Required Tools:
  ✓ zsh: zsh 5.8
  ✓ git: git version 2.34.1

Strongly Recommended:
  ✓ fzf: 0.42.0
  ✗ gh: not installed

Modern CLI Replacements:
  ✓ bat (replaces cat): bat 0.22.1
  ✓ eza (replaces ls): eza 0.17.0
  ...

Dependencies

Required

• zsh - Shell
• git - Version control
• oh-my-zsh - Zsh framework

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

• Powerlevel10k - Zsh theme

  git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Optional (Recommended)

Install these for the best experience:

• colorls - Colorized ls with icons

  # Requires Ruby
  gem install colorls

• autojump - Fast directory navigation

  # macOS
  brew install autojump
  
  # Ubuntu/Debian
  sudo apt install autojump

• direnv - Per-directory environment variables

  # macOS
  brew install direnv
  
  # Ubuntu/Debian
  sudo apt install direnv

• pyenv - Python version management

  curl https://pyenv.run | bash

• nvm - Node.js version management

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

• zsh-autosuggestions - Fish-like command suggestions

  git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

• zsh-syntax-highlighting - Fish-like syntax highlighting

  git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

• zsh-fzf-history-search - Fuzzy history search

  git clone https://github.com/joshskidmore/zsh-fzf-history-search ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-fzf-history-search

Work-Specific (Quantivly)

• quantivly plugin - Custom oh-my-zsh plugin for Quantivly development
  • Located at ~/.oh-my-zsh/custom/plugins/quantivly/
  • Provides qn, qg, qh, qp commands and other utilities
  • Not required for basic dotfiles functionality

Configuration Modules

zshrc.history

Comprehensive history settings including:

• 50,000 commands stored
• Timestamps recorded
• Duplicate removal
• Shared history across sessions

zshrc.functions

Utility functions:

• pathadd - Safely add directories to PATH

zshrc.aliases

Common aliases that work across all systems:

• Navigation shortcuts (.., ..., ....)
• Safe file operations (rm -i, cp -i, mv -i)
• Git aliases (gst, gco, gcb, etc.)
• Docker shortcuts (dps, dlog, dex, etc.)
• Python utilities (py, pip, venv)

zshrc.conditionals

Conditional loading of optional tools:

• colorls (if installed)
• pyenv (if installed)
• nvm (if installed)
• Editor configuration (prefers VS Code, falls back to vim)
• SSH agent setup
• Locale settings

zshrc.company

Work-specific configuration:

• Quantivly environment variables (Q_MODE, Q_DEV_CODE_ROOT, etc.)
• Only loads if quantivly plugin is available
• Can be overridden in ~/.zshrc.local

~/.zshrc.local (Not in Git)

Machine-specific settings that should NEVER be committed:

• API keys and tokens
• SSH key configuration
• Machine-specific PATH additions
• Local overrides of work variables
• Custom aliases for this machine only

Security Best Practices

1. Never commit secrets - All sensitive data goes in ~/.zshrc.local
2. Protect your local config - ~/.zshrc.local should have mode 600
3. Review before committing - Always check what you're committing to git
4. Rotate exposed tokens - If you accidentally commit secrets, rotate them immediately
5. Use .gitignore - The included .gitignore prevents common secret files from being committed

Key Features

Shell Enhancements

Navigation:

• AUTO_CD - Type directory name without cd command
• Smart directory stack with duplicate prevention
• Fuzzy directory search with fcd

Completion:

• Case-insensitive tab completion
• Colored completion matching your LS_COLORS
• Menu selection with arrow keys
• Complete from within a word/phrase

History:

• 50,000 commands stored with timestamps
• Smart duplicate removal
• Shared across all sessions
• Ignores common commands (ls, cd, pwd)

Key Bindings:

• Ctrl/Alt + Arrow keys for word movement
• Proper Home/End/Delete key support

Utility Functions

File & Directory:

• mkcd <dir> - Create directory and cd into it
• backup <file> - Create timestamped backup
• extract <file> - Universal archive extractor
• dirsize [dir] - Show directory sizes sorted

Network:

• myip - Display public IP
• localip - Display local IP

Development:

• note <msg> - Quick timestamped notes
• psgrep <pattern> - Find processes
• killnamed <name> - Kill processes by name
• gwt <branch> - Git worktree wrapper

Modern CLI Tool Integration

The configuration automatically detects and uses modern alternatives:

Standard	Modern Alternative	Benefit
cat	bat	Syntax highlighting, line numbers
ls	eza/exa	Colors, icons, better formatting
find	fd	Faster, respects .gitignore
grep	ripgrep	Much faster recursive search
top	htop	Better process viewer
git diff	delta	Syntax highlighting in diffs

Tools are only used if installed. Use \command to bypass aliases (e.g., \cat, \ls).

FZF Integration

Fuzzy finding for:

• Files and directories (Ctrl+T, Alt+C)
• Command history (Ctrl+R)
• Git branches: fbr
• Git commits: fco
• Git commit browser: fshow

Enhanced Aliases

Git shortcuts:

gaa    # git add --all
gcam   # git commit -am
glogp  # Pretty git log with colors
gundo  # Undo last commit (soft)
gwip   # Quick WIP commit

Docker shortcuts:

dps    # docker ps
dex    # docker exec -it
dcup   # docker compose up -d
dclogs # docker compose logs -f
dclean # docker system prune

System shortcuts:

zshreload  # Reload zsh config
localrc    # Edit ~/.zshrc.local
c          # clear
..         # cd ..
...        # cd ../..

GitHub CLI Aliases

This dotfiles includes extensive GitHub CLI aliases (see gh/config.yml):

PR Management:

• gh mypr - List your open PRs
• gh prs - List all open, non-draft PRs
• gh prs! - List PRs excluding dependency updates
• gh prmerge - Merge PR with squash and delete branch
• gh prchecks - View PR checks
• gh prready / gh prdraft - Toggle PR ready state

Review Workflow:

• gh review - List PRs where you're requested to review
• gh reviewed - PRs you've already reviewed
• gh approve - Approve PR
• gh request-changes - Request changes on PR

CI/CD:

• gh runs - List workflow runs for current branch
• gh runwatch - Watch workflow run in real-time
• gh rerun - Rerun failed workflow

And 25+ more! See gh/config.yml for the complete list.

Workflow Examples

Comprehensive workflow guides are available in the examples/ directory:

Git Workflows

Step-by-step guides for:

• Feature branch development
• Pull request review workflow
• Merge conflict resolution
• Quick WIP commits (gwip/gunwip)
• Branch cleanup and maintenance
• Advanced operations (rebase, cherry-pick, stash)

Docker Workflows

Practical Docker workflows for:

• Starting and monitoring services
• Container debugging and inspection
• Image management and cleanup
• Networking and volumes
• Troubleshooting common issues

FZF Integration Recipes

Power user tips for:

• Interactive fuzzy finding (Ctrl+T, Ctrl+R, Alt+C)
• Custom functions (fcd, fbr, fco, fshow)
• Process management
• Advanced file operations
• Git and Docker integration

See examples/README.md for the complete index.

For tool installation and verification, see the Utility Scripts section.

Customization

Adding New Modules

To add a new configuration module:

1. Create the file in ~/.dotfiles/zsh/zshrc.newmodule
2. Add it to the loading section in ~/.dotfiles/zshrc:

   [ -f ~/.dotfiles/zsh/zshrc.newmodule ] && source ~/.dotfiles/zsh/zshrc.newmodule

3. Commit and push changes

Disabling Modules

Comment out the source line in ~/.dotfiles/zshrc:

# [ -f ~/.dotfiles/zsh/zshrc.company ] && source ~/.dotfiles/zsh/zshrc.company

Or disable specific plugins by removing them from the plugins=() array.

Troubleshooting

Slow Shell Startup

1. Profile your startup time:

   time zsh -i -c exit

2. Disable unnecessary plugins in ~/.zshrc.local:

   plugins=(${plugins:#poetry})  # Remove poetry plugin

3. Check for slow commands - Add timing to your zshrc temporarily:

   PS4='+ %D{%s.%.} %N:%i> '
   set -x
   # ... your config ...
   set +x

Missing Commands

If commands like pathadd are undefined:

• Ensure ~/.dotfiles/zsh/zshrc.functions is being sourced
• Check that ~/.zshrc is properly symlinked to ~/.dotfiles/zshrc
• Run ./install again

SSH Agent Issues

If SSH keys aren't loading automatically:

1. Check that your key exists (default: ~/.ssh/id_ed25519)
2. Add SSH configuration to ~/.zshrc.local (see template)
3. Verify SSH_AUTH_SOCK is set: echo $SSH_AUTH_SOCK

Contributing

This is a personal dotfiles repository, but feel free to:

• Fork it and adapt it for your own use
• Suggest improvements via issues
• Share your own dotfiles approach

License

MIT License - Feel free to use and modify as needed.

Resources

• Dotbot Documentation
• oh-my-zsh Documentation
• Powerlevel10k Documentation
• GitHub CLI Documentation