Dotfiles

A comprehensive macOS dotfiles configuration featuring a tiling window manager, customized status bar, and productivity-focused terminal environment.

Features

• Window Management: Yabai (tiling WM) + skhd (hotkey daemon)
• Status Bar: Sketchybar with custom widgets
• Terminal Tools: Zellij (multiplexer), Ranger (file manager), btop (system monitor)
• Shell: Zsh with custom configuration and Gruvbox theming
• Unified Theme: Gruvbox dark theme across all tools

Table of Contents

• Screenshots
• Quick Start
• Installation
• Components
• Keybindings
• Customization
• Dependencies
• Troubleshooting
• Contributing

Screenshots

Add screenshots of your setup here

Quick Start

# Clone the repository
git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
cd ~/dotfiles

# Preview what will be installed (dry run)
./install.sh --dry-run

# Install dotfiles
./install.sh

# Restart your terminal
source ~/.zshrc

Installation

Prerequisites

macOS Only:

• macOS 12.0 (Monterey) or later
• Homebrew package manager

Required Dependencies

# Core tools
brew install git zsh

# Terminal tools
brew install neofetch ranger btop zellij

# Window management (macOS only)
brew install koekeishiya/formulae/yabai
brew install koekeishiya/formulae/skhd
brew tap FelixKratz/formulae
brew install sketchybar

# Fonts (required for icons)
brew install --cask font-caskaydia-cove-nerd-font
brew install --cask font-hack-nerd-font

Optional Dependencies

# Enhanced functionality
brew install fzf              # Fuzzy finder
brew install bat              # Better cat with syntax highlighting
brew install lsd              # Better ls
brew install ripgrep          # Better grep
brew install fd               # Better find
brew install lolcat           # Rainbow text (for neofetch themes)

# Development tools
brew install nvim             # Neovim editor
brew install git-delta        # Better git diff

Installation Steps

1. Clone the repository:

   git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
   cd ~/dotfiles

2. Review the install script:

   # See what will be changed
   ./install.sh --dry-run

3. Install:

   # Standard installation (with backups)
   ./install.sh
   
   # Or force overwrite without backups
   ./install.sh --force
   
   # Or verbose output
   ./install.sh --verbose

4. Configure macOS services:

   # Start yabai and skhd
   yabai --start-service
   skhd --start-service
   
   # Start sketchybar
   brew services start sketchybar

5. Change default shell to zsh:

   chsh -s $(which zsh)

6. Restart your terminal

Uninstallation

Backups of your original configs are stored in ~/.dotfiles_backup_YYYYMMDD_HHMMSS/. To restore:

# Find your backup directory
ls -la ~ | grep dotfiles_backup

# Restore from backup
cp -r ~/.dotfiles_backup_YYYYMMDD_HHMMSS/.zshrc ~/
# ... restore other files as needed

# Remove symlinks
rm ~/.zshrc ~/.zshenv ~/.zprofile
rm ~/.config/colors.sh ~/.config/icons.sh
# ... etc

Components

Shell Configuration

Zsh - Primary shell with three configuration files:

• .zshrc - Interactive shell configuration (aliases, functions, prompt)
• .zprofile - Login shell configuration (PATH, environment setup)
• .zshenv - Environment variables for all shells

Features:

• Gruvbox-themed prompt with git integration
• Smart history management
• Directory navigation shortcuts
• Comprehensive aliases and functions
• XDG Base Directory compliance

Window Management

Yabai

Tiling window manager for macOS providing automatic window layout and management.

Configuration: yabai/

• init-spaces.sh - Workspace initialization
• apply-changes.sh - Apply configuration changes
• emergency-cleanup.sh - Recovery script

Features:

• BSP (Binary Space Partitioning) layout
• Multi-monitor support
• Floating window rules
• Workspace/space management

skhd

Hotkey daemon for macOS providing keyboard-driven window control.

Configuration: skhd/skhdrc

Key Features:

• Vim-style window navigation (hjkl)
• Window movement and resizing
• Workspace switching
• Application launching

See Keybindings section for complete reference.

Status Bar

Sketchybar

Highly customizable status bar replacement for macOS.

Configuration: sketchybar/

Widgets:

• Apple menu (system controls)
• Workspace indicators
• Window title
• Music player (Spotify/Apple Music)
• System stats (CPU, RAM)
• WiFi, Bluetooth
• Battery
• Date & Time
• Control Center

Colors & Icons:

• colors.sh - Gruvbox color definitions
• icons.sh - Nerd Font icon mappings

Terminal Tools

Zellij

Modern terminal multiplexer with tmux-like functionality.

Configuration: zellij/config.kdl

Features:

• Tmux-style keybindings (Ctrl+a prefix)
• Gruvbox theme
• Mouse support
• System clipboard integration

Ranger

Vim-inspired terminal file manager.

Configuration: ranger/

Features:

• Image preview support (Kitty protocol)
• Git integration
• Custom commands and keybindings
• Archive management
• Gruvbox color scheme

btop

Resource monitor with a beautiful interface.

Configuration: btop/btop.conf

Features:

• Real-time CPU, memory, disk, and network monitoring
• Process management
• TTY-compatible themes

Neofetch

System information display tool with ASCII art.

Configuration: neofetch/

Multiple themed variants available:

• gruvbox_simple.sh - Gruvbox colors
• rainbow_fetch.sh - Rainbow colors (requires lolcat)
• gruvbox_compact.sh - Compact ASCII art
• Various other themes

Theme System

Unified Gruvbox Theme across all components:

Colors (colors.sh):

• Background: #282828 (dark0)
• Foreground: #ebdbb2 (fg1)
• Red: #cc241d / #fb4934 (bright)
• Green: #98971a / #b8bb26 (bright)
• Yellow: #d79921 / #fabd2f (bright)
• Blue: #458588 / #83a598 (bright)
• Magenta: #b16286 / #d3869b (bright)
• Cyan: #689d6a / #8ec07c (bright)

Fonts:

• CaskaydiaCove Nerd Font
• Hack Nerd Font

Keybindings

Yabai + skhd

Window Focus

Keybinding	Action
Alt + H	Focus window west
Alt + J	Focus window south
Alt + K	Focus window north
Alt + L	Focus window east

Window Movement

Keybinding	Action
Shift + Alt + H	Move window west
Shift + Alt + J	Move window south
Shift + Alt + K	Move window north
Shift + Alt + L	Move window east

Window Resize

Keybinding	Action
Ctrl + Alt + H	Resize left
Ctrl + Alt + J	Resize down
Ctrl + Alt + K	Resize up
Ctrl + Alt + L	Resize right

Window Actions

Keybinding	Action
Alt + F	Toggle float
Alt + T	Toggle split type
Alt + E	Balance windows
Alt + R	Rotate windows 90°
Alt + M	Toggle fullscreen
Alt + P	Toggle picture-in-picture

Workspace/Space Management

Keybinding	Action
Alt + 1-9	Switch to workspace 1-9
Shift + Alt + 1-9	Move window to workspace 1-9
Alt + Tab	Switch to recent workspace
Alt + N	Create new workspace
Alt + D	Destroy current workspace

Application Launching

Keybinding	Action
Alt + Return	Launch Kitty terminal
Shift + Alt + B	Launch Arc browser

Zellij

Keybinding	Action
Ctrl + A	Prefix key (like tmux)
Prefix + C	New tab
Prefix + N	Next tab
Prefix + P	Previous tab
Prefix + "	Split horizontal
Prefix + %	Split vertical
Prefix + X	Close pane
Prefix + D	Detach session

Ranger

Keybinding	Action
h/j/k/l	Navigate (vim-style)
Space	Select file
yy	Copy
dd	Cut
pp	Paste
dD	Delete
zh	Toggle hidden files
gp	Go to projects directory
S	Open shell in current directory
/	Search

Shell (Zsh)

Alias	Command	Description
..	cd ..	Go up one directory
...	cd ../..	Go up two directories
proj	cd $PROJECTS_DIR	Go to projects directory
ll	ls -lah	List all files with details
v	nvim	Open Neovim
g	git	Git shortcut
gs	git status	Git status
r	ranger	Open Ranger
z	zellij	Open Zellij
nf	neofetch	Show system info

Customization

Adding Machine-Specific Configuration

Create local config files that won't be tracked by git:

# Shell-specific config
touch ~/.zshrc.local
touch ~/.zprofile.local
touch ~/.zshenv.local

# Add your machine-specific settings
echo 'export CUSTOM_VAR="value"' >> ~/.zshrc.local

Changing the Theme

The theme is controlled by colors.sh. To use a different color scheme:

1. Edit colors.sh with your preferred colors
2. Reload sketchybar: brew services restart sketchybar
3. Restart your terminal

Customizing Keybindings

Edit skhd/skhdrc to change keybindings:

# Edit the file
vim ~/.config/skhd/skhdrc

# Reload skhd
skhd --reload

Customizing the Status Bar

Edit sketchybar components in sketchybar/:

# Edit items
vim ~/.config/sketchybar/items/

# Edit plugins
vim ~/.config/sketchybar/plugins/

# Reload sketchybar
sketchybar --reload

Projects Directory

By default, configs use ~/projects. To change:

# Add to ~/.zshrc.local
export PROJECTS_DIR="$HOME/path/to/your/projects"

Dependencies

Core Tools

• git - Version control
• zsh - Shell
• neofetch - System information
• ranger - File manager
• btop - System monitor
• zellij - Terminal multiplexer

macOS Specific

• yabai - Window manager
• skhd - Hotkey daemon
• sketchybar - Status bar

Optional

• fzf - Fuzzy finder
• bat - Better cat
• lsd - Better ls
• ripgrep - Better grep
• fd - Better find
• nvim - Text editor
• lolcat - Rainbow text (for colorful neofetch themes)

Fonts

• CaskaydiaCove Nerd Font - Primary font
• Hack Nerd Font - Alternative font

Troubleshooting

Sketchybar not showing

# Check if running
brew services list | grep sketchybar

# Restart
brew services restart sketchybar

# Check logs
tail -f /opt/homebrew/var/log/sketchybar.log

Yabai not tiling windows

# Check if running
yabai --check-sa

# Restart
yabai --restart-service

# Check logs
tail -f /tmp/yabai_$USER.out.log

Skhd keybindings not working

# Check if running
pgrep -fl skhd

# Restart
skhd --restart-service

# Check logs
tail -f /tmp/skhd_$USER.out.log

Icons not showing

Make sure you have a Nerd Font installed and set in your terminal:

# Install fonts
brew install --cask font-hack-nerd-font
brew install --cask font-caskaydia-cove-nerd-font

# Set font in your terminal settings to "Hack Nerd Font" or "CaskaydiaCove Nerd Font"

Colors not working

# Check if colors.sh is sourced
source ~/.config/colors.sh

# Verify in sketchybar
echo $COLOR_WHITE

Permission issues on macOS

Yabai and skhd may require accessibility permissions:

1. System Preferences → Security & Privacy → Privacy
2. Accessibility → Add Terminal/iTerm2
3. Screen Recording → Add yabai (for window borders)

File Structure

dotfiles/
├── .zshrc                      # Zsh interactive config
├── .zshenv                     # Zsh environment variables
├── .zprofile                   # Zsh login config
├── colors.sh                   # Color definitions
├── icons.sh                    # Icon definitions
├── install.sh                  # Installation script
├── README.md                   # This file
│
├── btop/
│   └── btop.conf              # btop configuration
│
├── neofetch/
│   ├── config.conf            # Main neofetch config
│   ├── gruvbox_simple.sh      # Gruvbox theme
│   ├── rainbow_fetch.sh       # Rainbow theme
│   └── ...                    # Other theme variants
│
├── ranger/
│   ├── rc.conf                # Main config
│   ├── rifle.conf             # File associations
│   ├── commands.py            # Custom commands
│   ├── colorschemes/          # Color schemes
│   └── plugins/               # Plugins
│
├── sketchybar/
│   ├── sketchybarrc           # Main config
│   ├── globalstyles.sh        # Global styles
│   ├── items/                 # Bar item definitions
│   ├── plugins/               # Update scripts
│   └── setting/               # Settings
│
├── skhd/
│   ├── skhdrc                 # Hotkey config
│   └── scripts/               # Helper scripts
│
├── yabai/
│   ├── init-spaces.sh         # Space initialization
│   ├── apply-changes.sh       # Apply changes
│   └── emergency-cleanup.sh   # Cleanup script
│
└── zellij/
    └── config.kdl             # Zellij config

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Acknowledgments

• Gruvbox - Color scheme
• Nerd Fonts - Iconic font aggregator
• Yabai - Window manager
• Sketchybar - Status bar
• The dotfiles community for inspiration

Support

If you have questions or run into issues:

1. Check the Troubleshooting section
2. Search existing GitHub issues
3. Open a new issue with details about your problem

---

Note: This configuration is primarily designed for macOS. Some components (yabai, skhd, sketchybar) are macOS-only, but the shell and terminal tool configurations are cross-platform.