dotfiles

Personal dotfiles for macOS and Linux (Ubuntu/Debian).

Features

• Modular Zsh configuration - Organized into separate files for easy maintenance
• Cross-platform support - Works on both macOS and Ubuntu/Debian Linux
• Automated installation - Single script to set up everything
• Version-controlled Neovim config - Maintained as a git submodule git submodule update --recursive
• Consistent theming - Catppuccin across all tools
• Development ready - Pre-configured for Python (pyenv) and Node (nvm)

Contents

Shell

• zsh - Modular configuration with custom prompt, aliases, and functions
  • Git-aware prompt with branch and status indicators
  • Custom git commands (ggpush, gcam, gst)
  • Tmux integration
  • Python and Node path configuration

Terminal

• ghostty - Primary terminal emulator (IBM Plex Mono, Catppuccin Mocha)
• tmux - Terminal multiplexer with vim-style keybindings

Editor

• neovim - Full-featured config with LSP, Treesitter, and Telescope
  • Maintained as separate git submodule at hhheath/nvim
  • Lazy.nvim for plugin management
  • Obsidian integration for note-taking

macOS Specific

• AeroSpace - i3-like tiling window manager
• Homebrew - Package management via Brewfile

Git

• .gitconfig - Common aliases and sensible defaults (template)

Quick Start

Installation

1. Clone this repository:

   git clone --recurse-submodules https://github.com/hhheath/dotfiles.git ~/.dotfiles
   cd ~/.dotfiles

2. Run the installation script:

   ./install.sh

3. Restart your terminal or source the new configuration:

   source ~/.zshrc

4. Update .gitconfig with your personal information:

   nvim ~/.gitconfig
   # Update name and email fields

What the Install Script Does

The install.sh script will:

• ✓ Detect your OS (macOS or Linux)
• ✓ Install base packages (git, zsh, curl, tmux, neovim, etc.)
• ✓ Install pyenv with Python build dependencies
• ✓ Install nvm (Node Version Manager)
• ✓ Install development tools (fzf, ripgrep, fd, jq, gh)
• ✓ macOS: Install Homebrew and packages from Brewfile
• ✓ Linux: Build/install tools from source where needed
• ✓ Set zsh as your default shell
• ✓ Backup existing configs to ~/.dotfiles_backup/
• ✓ Copy dotfiles to appropriate locations
• ✓ Initialize and link Neovim config

Post-Installation

1. Install Python version:

   pyenv install 3.12.0
   pyenv global 3.12.0

2. Install Node version:

   nvm install --lts
   nvm use --lts

3. Launch Neovim to auto-install plugins:

   nvim
   # Lazy.nvim will automatically install all plugins

Directory Structure

dotfiles/
├── config/
│   ├── nvim/              # Neovim config (git submodule)
│   ├── ghostty/
│   │   └── config         # Ghostty terminal config
│   └── aerospace/
│       └── aerospace.toml # AeroSpace window manager (macOS)
├── shell/
│   └── zsh/
│       ├── aliases.zsh    # Shell aliases
│       ├── completion.zsh # Completion setup
│       ├── env.zsh        # Environment variables
│       ├── functions.zsh  # Custom functions
│       ├── nvm.zsh        # NVM initialization
│       ├── path.zsh       # PATH configuration
│       ├── prompt.zsh     # Git-aware prompt
│       └── pyenv.zsh      # Pyenv initialization
├── .zshrc                 # Main zsh config (sources modules)
├── .tmux.conf             # Tmux configuration
├── .gitconfig             # Git configuration template
├── Brewfile               # macOS package definitions
├── install.sh             # Installation script
└── README.md              # This file

Configuration Highlights

Zsh

• Modular design - Easy to add/remove functionality
• Smart completion - Case-insensitive with automatic suggestions
• Git integration - Branch name and status in prompt
• Custom aliases - Shortcuts for common tasks

Tmux

• Prefix: Ctrl+Space (instead of Ctrl+B)
• Navigation: Alt+hjkl to move between panes
• Splits: \ for horizontal, - for vertical
• Mouse support enabled

AeroSpace (macOS)

• i3-style tiling - Automatic window management
• Keyboard-driven - Alt+hjkl for navigation
• Workspaces - Support for 1-9 and A-Z

Manual Installation (Alternative)

If you prefer to manually install without the script:

1. Install base tools:

   • macOS: brew install git zsh tmux neovim fzf ripgrep fd
   • Ubuntu: sudo apt install git zsh tmux build-essential

2. Install version managers:

   # pyenv
   curl https://pyenv.run | bash
   
   # nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

3. Copy configs:

   cd ~/.dotfiles
   cp .zshrc ~/.zshrc
   cp -r shell ~/.config/shell
   cp .tmux.conf ~/.tmux.conf
   cp -r config/ghostty ~/.config/ghostty
   cp .gitconfig ~/.gitconfig
   ln -s ~/.dotfiles/nvim ~/.config/nvim

4. Set zsh as default shell:

   chsh -s $(which zsh)

Maintenance

Update Neovim Config

The nvim config is a git submodule, so you can update it independently:

cd ~/.dotfiles/nvim
git pull origin main
cd ~/.dotfiles
git add nvim
git commit -m "Update nvim submodule"

Update Brewfile (macOS)

To capture currently installed packages:

cd ~/.dotfiles
brew bundle dump --force
git add Brewfile
git commit -m "Update Brewfile"

Add New Zsh Module

1. Create new file in shell/zsh/ (e.g., docker.zsh)
2. Add source "$ZSH_CONFIG_DIR/docker.zsh" to .zshrc
3. Commit both files

Troubleshooting

Zsh modules not loading

Make sure the paths in .zshrc are correct. The script automatically detects whether to use ~/.config/shell/zsh or the dotfiles directory.

Neovim plugins not installing

Run :Lazy sync inside Neovim to manually trigger plugin installation.

pyenv/nvm not found

Source your .zshrc again or restart your terminal:

source ~/.zshrc

Platform Support

OS	Status	Notes
macOS (Intel)	✅ Fully supported	Tested on macOS Sonoma
macOS (Apple Silicon)	✅ Fully supported	Homebrew handles architecture
Ubuntu 22.04+	✅ Fully supported	apt-based package installation
Debian 11+	✅ Fully supported	apt-based package installation
Other Linux	⚠️ Partial	May require manual package installation

License

Free to use, modify, and distribute. No warranty provided.

Credits

• Zsh prompt inspired by Oh-My-Zsh
• Neovim config structure based on modern Lua patterns
• Catppuccin theme by @catppuccin