dotfiles setup

This project contains setup files for macOS and Linux (including GitHub Codespaces). The configurations are designed to be portable across different platforms and Homebrew installations.

To setup everything clone this repository into your home folder (cd ~), then run ./setup.sh to stow all folders.

Prerequisites

The dotfiles include availability checks, so missing optional tools won't cause errors. Install what you need based on your workflow.

Required Tools

• zsh - Shell (usually pre-installed on macOS/Linux)
• oh-my-zsh - Zsh framework for plugins and themes
• stow - Symlink manager for dotfiles
• git - Version control (usually pre-installed)

Core Development Tools

• neovim - Text editor (configured as primary $EDITOR)
• tmux - Terminal multiplexer
• WezTerm - Terminal emulator (configured to launch tmux)
• fzf - Fuzzy finder for command history and files
• ripgrep - Fast text search (rg command)

Shell Enhancements (Optional)

• zoxide - Smart directory jumper (z command)
• direnv - Automatic environment variable loading per directory
• lazygit - Terminal UI for git

Version Managers (Optional)

• nvm - Node.js version manager
• pyenv - Python version manager
• bun - JavaScript runtime and package manager

Package Managers (Optional)

• Homebrew - Package manager (macOS/Linux)
• nix - Declarative package manager
• pkgx - Package manager

macOS Specific (Optional)

• AeroSpace - Tiling window manager
• Rectangle - Window management
• Alt-Tab - Windows-style alt-tab
• MeetingBar - Calendar in menu bar

Other Optional Tools

• Fig - Terminal autocomplete and workflows
• LM Studio - Local LLM inference

oh-my-zsh Custom Plugins

The .zshrc expects these custom plugins in ~/.oh-my-zsh/custom/plugins/:

cd ~/.oh-my-zsh/custom/plugins
git clone https://github.com/zsh-users/zsh-autosuggestions.git
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git
git clone https://github.com/seebi/dircolors-solarized.git zsh-dircolors-solarized

Testing

This repository includes automated testing to validate configurations before deployment.

Run Tests Locally

./test.sh

The test script validates:

• Shell script syntax (setup.sh) using shellcheck
• Zsh configuration syntax
• Lua configurations (Neovim, WezTerm)
• TOML configurations (AeroSpace)
• Git configuration
• Tmux configuration

Install validation tools for complete testing:

# macOS
brew install shellcheck lua taplo

# Ubuntu/Debian
sudo apt-get install shellcheck lua5.4
curl -fsSL https://github.com/tamasfe/taplo/releases/latest/download/taplo-linux-x86_64.gz | gunzip -c > /usr/local/bin/taplo
sudo chmod +x /usr/local/bin/taplo

Continuous Integration

GitHub Actions automatically tests the dotfiles on every push:

• Syntax Validation: Checks all config files for syntax errors
• macOS Installation: Tests complete setup on macOS
• Linux Installation: Tests complete setup on Ubuntu
• Stow Symlinks: Validates symlink creation without conflicts

View test results in the Actions tab of the repository.