Dotfiles

Modern, modular dotfiles for macOS and Linux with fast shell startup, Lua-based Neovim, and automated installation.

Features

• Fast Shell: Zsh with Zinit plugin manager and Starship prompt (~150ms startup)
• Modern Neovim: Lua configuration with lazy.nvim, LSP, and Treesitter
• Tmux: Session persistence with tmux-resurrect/continuum
• Git: Delta diffs, 60 aliases, and productivity enhancements
• Theme System: Light/dark mode with auto-detection on macOS
• Portable: Works on macOS and Linux with platform detection
• Automated: One-command installation with backup and rollback

Quick Start

Fresh Installation

# Clone and install
git clone https://github.com/tyrocca/dotfiles.git ~/dotfiles
cd ~/dotfiles
./scripts/install.sh

Installation Options

# Full installation (recommended)
./scripts/install.sh --full

# Minimal (shell + git only, for servers)
./scripts/install.sh --minimal

# Dry run (preview changes)
./scripts/install.sh --dry-run

# Interactive selection
./scripts/install.sh --custom

# Specific components
./scripts/install.sh --shell --git --no-nvim --no-tmux

Components

Component	Location	Description
Zsh	config/zsh/	Shell with Zinit, aliases, functions
Starship	config/starship/	Cross-shell prompt with git info
Neovim	config/nvim/	Lua config with lazy.nvim
Tmux	config/tmux/	Modern tmux 3.3+ with TPM
Git	config/git/	Delta, aliases, SSH URL rewrites

Directory Structure

dotfiles/
├── config/                 # XDG-style configurations
│   ├── zsh/               # Zsh configuration
│   │   ├── zshrc          # Main config (Zinit, completions)
│   │   ├── zshenv         # Environment variables
│   │   ├── theme.zsh      # Theme system (light/dark switching)
│   │   ├── aliases.zsh    # Shell aliases
│   │   ├── functions.zsh  # Utility functions
│   │   ├── path.zsh       # PATH management
│   │   └── platform/      # OS-specific configs
│   ├── nvim/              # Neovim configuration
│   │   ├── init.lua       # Entry point
│   │   └── lua/           # Lua modules
│   ├── tmux/              # Tmux configuration
│   │   └── tmux.conf      # Main config
│   ├── starship/          # Starship prompt
│   │   └── starship.toml  # Prompt config
│   ├── git/               # Git configuration
│   │   ├── config         # Main gitconfig
│   │   └── ignore         # Global gitignore
│   └── bat/               # Bat syntax highlighter
│       └── config         # Bat configuration
├── scripts/               # Installation scripts
│   ├── install.sh         # Main installer
│   ├── dotfiles           # Management CLI
│   ├── setup-shell.sh     # Shell setup
│   ├── setup-nvim.sh      # Neovim setup
│   ├── setup-tmux.sh      # Tmux setup
│   └── setup-git.sh       # Git setup
├── tests/                 # Configuration tests
└── docs/                  # Documentation

Management

After installation, use the dotfiles command:

dotfiles status      # Show installation status
dotfiles update      # Update repo and plugins
dotfiles health      # Run health checks
dotfiles doctor      # Diagnose and fix issues
dotfiles backup      # Create backup
dotfiles edit        # Open in editor

Theme System

Switch between light and dark themes across all tools:

theme light    # Solarized Light
theme dark     # Gruvbox/Catppuccin Dark
theme auto     # Auto-detect from macOS appearance
theme status   # Show current theme
theme doctor   # Verify configuration

Affected tools: Neovim, Tmux, FZF, Bat, Delta

On macOS, theme auto-detects from system appearance on new shells.

Dependencies

Required

• Git
• Zsh

Recommended (auto-detected)

• Starship - Prompt
• Neovim 0.9+ - Editor
• Tmux 3.3+ - Multiplexer
• Delta - Git diffs
• fzf - Fuzzy finder
• ripgrep - Fast search
• eza - Modern ls

Install on macOS

brew install starship neovim tmux git-delta fzf ripgrep eza

Install on Linux

# Ubuntu/Debian
sudo apt install zsh neovim tmux fzf ripgrep

# Starship
curl -sS https://starship.rs/install.sh | sh

# Delta
# Download from https://github.com/dandavison/delta/releases

Environment Variables

Set these before installation or in your environment:

# Machine type (affects loaded configs)
export DOTFILES_ENV=personal  # personal, work, remote

# Dotfiles location (default: ~/dotfiles)
export DOTFILES=~/dotfiles

Customization

Adding Local Overrides

Create these files for machine-specific settings (not tracked by git):

• ~/.zshrc.local - Local shell config
• ~/.gitconfig.local - Local git config

Work Configuration

Set DOTFILES_ENV=work to load work-specific aliases and configurations from config/zsh/work.zsh.

Troubleshooting

Slow Shell Startup

# Check startup time
time zsh -i -c exit

# Profile startup
zsh -xv 2>&1 | head -100

# Common fixes:
# - Ensure Zinit turbo loading is working
# - Check for slow completions
# - Disable unused plugins

Neovim Issues

# Check health
nvim --headless "+checkhealth" "+qa"

# Reset plugins
rm -rf ~/.local/share/nvim/lazy
nvim  # Will reinstall plugins

Tmux Issues

# Reinstall plugins
~/.tmux/plugins/tpm/bin/install_plugins

# Reset tmux
tmux kill-server

Git Delta Not Working

# Check delta is installed
which delta

# Test delta
echo "test" | delta

# Check git config
git config --get core.pager

Migration from Legacy Setup

If you have the old oh-my-zsh based configuration:

1. Backup existing configs: ./scripts/install.sh --dry-run
2. Install: ./scripts/install.sh
3. Restore any custom aliases from backup
4. Remove old oh-my-zsh: rm -rf ~/.oh-my-zsh

Contributing

1. Fork the repository
2. Create a feature branch
3. Run tests: ./tests/run-tests.sh
4. Submit a pull request

License

MIT