Packages

Package Documentation

Complete overview of all available dotfiles packages and their configurations.

All packages live at the repo root as flat directories. Each package is stowed directly with --no-folding --target=$HOME, creating file-level symlinks (not directory-level).

Shell Packages

Bash

• Location: bash/
• Config: ~/.config/bash/
• Features: Gruvbox colors, smart tool detection, cross-platform support (macOS + Linux), enhanced history, git integration in prompt
• Key files: dir_colors (gruvbox theme), darwin (macOS-specific), aliases (adaptive aliases), colors, exports, history, prompt, shopt
• Installation: make bash

Zsh

• Location: zsh/
• Config: ~/.config/zsh/
• Features: Modern shell with enhanced completion, git integration, custom prompt
• Installation: make zsh

Editor Packages

Emacs

• Location: emacs/
• Config: ~/.config/emacs/
• Features: XDG-compliant, MELPA packages, modular configuration
• Installation: make emacs
• Documentation: Emacs

Nano

• Location: nano/
• Config: ~/.config/nano/
• Features: Enhanced syntax highlighting, improved key bindings
• Installation: make nano

Visual Studio Code

• Location: vscode/
• Config: ~/.config/Code/User/
• Features: Settings sync, extension management, custom themes
• Installation: make vscode

Development Packages

Git

• Location: git/
• Config: ~/.config/git/
• Features: Aliases, enhanced diff tools, proper user configuration, macOS-specific gitconfig, global gitignore
• Installation: make git

Desktop Packages

i3 Window Manager

• Location: i3/
• Config: ~/.config/i3/
• Features: Tiling window management, custom key bindings
• Installation: make i3
• Documentation: i3 Tiles
• Platform: Linux only

Terminal

• Location: terminal/
• Config: ~/.config/terminal/
• Features: Terminal emulator configurations with gruvbox themes
• Installation: make terminal

Tool Packages

Tmux

• Location: tmux/
• Config: ~/.config/tmux/
• Features: Backtick prefix key, emacs-style bindings, mouse support, gruvbox colors, 50,000 line history
• Installation: make tmux
• Documentation: Tmux

FZF

• Location: fzf/
• Config: ~/.config/fzf/
• Features: Fuzzy finder for files, command history, and more
• Installation: make fzf

Ripgrep

• Location: ripgrep/
• Config: ~/.config/ripgrep/
• Features: Fast recursive grep with smart defaults
• Installation: make ripgrep

Inputrc (Readline)

• Location: inputrc/
• Config: ~/.config/readline/
• Features: Readline configuration for enhanced line editing
• Installation: make inputrc

Curlrc

• Location: curlrc/
• Config: ~/.config/curl/
• Features: Default curl settings
• Installation: make curlrc

EditorConfig

• Location: editorconfig/
• Features: Consistent coding styles across editors
• Installation: make editorconfig

Htop

• Location: htop/
• Config: ~/.config/htop/
• Features: System monitor with custom display settings
• Installation: make htop

GnuPG

• Location: gnupg/
• Config: ~/.gnupg/
• Features: GPG configuration for encryption and signing
• Installation: make gnupg

Package Groups

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

XDG Compliance

All packages follow the XDG Base Directory Specification where possible:

Directory	Purpose	Examples
~/.config/	Configuration files	emacs/, git/, tmux/, bash/
~/.local/share/	Data files	emacs/packages/
~/.cache/	Cache files	emacs/auto-saves/
~/.local/state/	State files	bash/history

Stow Behavior

Packages are stowed with --no-folding, which creates individual file symlinks rather than directory-level symlinks. This means your ~/.config/bash/ directory will contain symlinks to individual files, not be a symlink itself. This is safer when multiple packages or manual files share a parent directory.

Installation Methods

Individual Packages

make tmux
make git
make bash

By Group

make shell editors tools

All Packages

make install

Adopt Existing Files

make adopt

This adopts existing files into stow management, then restows. Useful for first-time setup when you already have config files in place.

Dry Run (preview)

make plan

Customization

Local Overrides

Each package supports local customization files that won't be tracked by git:

# Shell configurations
~/.config/zsh/zshrc.local
~/.config/bash/bashrc.local

# Git configuration
~/.config/git/config.local

# Emacs configuration
~/.config/emacs/user/user-setup.el

Maintenance

Health Check

make doctor

Checks required/optional tools, XDG directories, broken symlinks, config validation, shell environment, and GPG setup.

Sync After Updates

git pull origin main
make sync

Backup & Restore

make backup          # Create timestamped backup
make restore         # Restore from latest backup
make list-backups    # List available backups
make prune-backups   # Remove old backups (keep last 5)

Remove Packages

make rm-tmux         # Remove specific package
make rm-bash

Clean Broken Symlinks

make prune