Home

XDG-Compliant Dotfiles

Personal dotfiles managed with GNU Stow, following the XDG Base Directory Specification for clean and organized configuration management.

Quick Start

git clone https://github.com/sunhick/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
make install

Enhanced Experience (Optional Dependencies)

macOS (Homebrew):

# Core enhancements
brew install coreutils fzf git

# Modern CLI tools
brew install bat eza fd ripgrep

# Terminal & Editor
brew install --cask iterm2
brew install emacs

Linux (Ubuntu/Debian):

# Core tools
sudo apt install git fzf coreutils

# Modern CLI tools
sudo apt install bat fd-find ripgrep

XDG Base Directory Specification

This dotfiles setup follows the XDG Base Directory Specification:

• ~/.config/ - Configuration files
• ~/.local/share/ - Data files
• ~/.cache/ - Cache files
• ~/.local/state/ - State files

Benefits

• Clean home directory - No more dot-file clutter
• Standardized locations - Follows Linux/Unix standards
• Better organization - Logical separation of config, data, cache
• Future-proof - Modern applications expect XDG compliance

Available Packages

Shell

• bash - Bash shell with gruvbox colors, smart tool detection, cross-platform support
• zsh - Zsh shell with modern features

Editors

• emacs - XDG-compliant Emacs configuration with MELPA packages
• nano - Enhanced nano editor settings
• vscode - Visual Studio Code configuration

Development Tools

• git - Git configuration and aliases

Desktop Environment

• i3 - i3 window manager configuration (Linux)
• terminal - Terminal emulator settings with gruvbox themes

System Tools

• tmux - Terminal multiplexer with custom key bindings and gruvbox theme
• fzf - Fuzzy finder configuration
• ripgrep - Fast grep alternative configuration
• inputrc - Readline configuration
• curlrc - Curl default settings
• editorconfig - EditorConfig settings
• gnupg - GPG configuration
• htop - System monitor configuration

Installation

Install Everything

make install

Safe Install (backup first)

make safe-install

Adopt Existing Files

make adopt

Preview Changes (dry run)

make plan

Install by Group

make shell       # bash, zsh
make editors     # emacs, nano, vscode
make development # git
make desktop     # i3, terminal
make tools       # tmux, fzf, ripgrep, inputrc, curlrc, editorconfig, gnupg, htop

Install Individual Packages

make tmux
make git
make bash

Management Commands

Command	Description
make install	Install all packages
make safe-install	Backup existing configs then install
make adopt	Install all, adopting existing files
make sync	Re-link all packages
make plan	Preview what would be installed (dry run)
make ls	List available packages by group
make doctor	Health check (tools, symlinks, configs)
make prune	Remove broken symlinks
make backup	Backup existing configuration files
make restore	Restore from latest backup
make list-backups	List available backups
make prune-backups	Remove old backups (keep last 5)
make rm-<pkg>	Remove a specific package

Color Theming

The dotfiles use a Gruvbox Dark Hard color scheme throughout:

• GNU dir_colors - Full gruvbox theme when coreutils installed
• BSD LSCOLORS - Gruvbox-inspired fallback for macOS
• Smart detection - Automatically chooses best color system

Install GNU coreutils for the best color experience:

# macOS
brew install coreutils

Requirements

Essential

• GNU Stow - Package management
• Git - Version control

Optional (Enhanced Experience)

• GNU coreutils - Better ls colors (gls, gdircolors)
• fzf - Fuzzy finder for command history
• Modern CLI tools - bat, eza, fd, ripgrep
• iTerm2 (macOS) - Enhanced terminal with better color support

macOS Installation

brew install stow

Linux Installation

# Ubuntu/Debian
sudo apt install stow

# Arch Linux
sudo pacman -S stow

Structure

dotfiles/
├── bash/               # bash shell (.config/bash/)
├── zsh/                # zsh shell (.config/zsh/)
├── git/                # git (.config/git/)
├── emacs/              # emacs (.config/emacs/)
├── nano/               # nano (.config/nano/)
├── vscode/             # vscode (.config/Code/)
├── tmux/               # tmux (.config/tmux/)
├── fzf/                # fzf (.config/fzf/)
├── ripgrep/            # ripgrep (.config/ripgrep/)
├── ...                 # and more
├── make/               # shared Makefile helpers (log.mk)
├── management/stow/    # stow configuration
└── Makefile            # one Makefile for everything

Adding a New Package

1. Create a directory at the repo root:

   mkdir -p mynewpackage/.config/mynewpackage

2. Add your config files following XDG structure.

3. Add it to ALL_PKGS and the appropriate group variable in the Makefile.

4. Install:

   make mynewpackage

Check out the screenshots and explore individual package documentation for detailed configuration information.