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

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

Clone the repository:

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

Review the install script:

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

Install:

# Standard installation (with backups)
./install.sh

# Or force overwrite without backups
./install.sh --force

# Or verbose output
./install.sh --verbose

Configure macOS services:

# Start yabai and skhd
yabai --start-service
skhd --start-service

# Start sketchybar
brew services start sketchybar

Change default shell to zsh:
```
chsh -s $(which zsh)
```
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:

Edit colors.sh with your preferred colors
Reload sketchybar: brew services restart sketchybar
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:

System Preferences → Security & Privacy → Privacy
Accessibility → Add Terminal/iTerm2
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:

Check the Troubleshooting section
Search existing GitHub issues
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.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
btop		btop
neofetch		neofetch
ranger		ranger
sketchybar		sketchybar
skhd		skhd
yabai		yabai
zellij		zellij
.zprofile		.zprofile
.zshenv		.zshenv
.zshrc		.zshrc
LICENSE		LICENSE
README.md		README.md
colors.sh		colors.sh
icons.sh		icons.sh
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

Dotfiles

Features

Table of Contents

Screenshots

Quick Start

Installation

Prerequisites

Required Dependencies

Optional Dependencies

Installation Steps

Uninstallation

Components

Shell Configuration

Window Management

Yabai

skhd

Status Bar

Sketchybar

Terminal Tools

Zellij

Ranger

btop

Neofetch

Theme System

Keybindings

Yabai + skhd

Window Focus

Window Movement

Window Resize

Window Actions

Workspace/Space Management

Application Launching

Zellij

Ranger

Shell (Zsh)

Customization

Adding Machine-Specific Configuration

Changing the Theme

Customizing Keybindings

Customizing the Status Bar

Projects Directory

Dependencies

Core Tools

macOS Specific

Optional

Fonts

Troubleshooting

Sketchybar not showing

Yabai not tiling windows

Skhd keybindings not working

Icons not showing

Colors not working

Permission issues on macOS

File Structure

Contributing

License

Acknowledgments

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages