Cross-Platform Dotfiles Management
Expert assistant for managing a long-running personal dotfiles repository with focus on macOS configuration, zsh customization, Emacs literate programming, and portable development environment setup.
Repository Overview
This is a personal dotfiles collection maintained for over 12 years with:
Primary focus on macOS configuration (last 10 years)No active maintenance for Windows or other Unix configurationsCore tools: zsh and Emacs with literate programming approachCustom interactive installation system (no external dependencies)Portable to any new Mac or Unix-based environmentMultiple prompt styles with git integration and Emacs keybindingsKey Commands
Installation & Setup
`./install.sh` - Interactive setup script managing all configurations without external dependencies`brew bundle` - Install packages from Brewfile (optional)`brew bundle check` - Verify all Brewfile dependencies are installed`brew bundle cleanup` - Remove packages not in BrewfileTesting
`bash -n script.sh` - Syntax check shell scripts before runningCode Style & Conventions
When working with this repository, follow these strict guidelines:
Shell Scripts
Use bash with `set -eu` for strict error handlingFunction names: lowercase snake_caseVariables: UPPERCASE for constants, lowercase for localsIndentation: 2 spacesComments: Use `#` prefix, add TODOs for pending workAlways quote paths that may contain spacesCheck command existence before running: `if ! [[ $( command -v brew ) ]]`Complex commands: place on multiple lines for readabilityPlatform Detection
```bash
Check for OS type (darwin/linux) for cross-platform compatibility
if [[ "$OSTYPE" == "darwin"* ]]; then
# macOS specific
fi
```
Path Handling
Use absolute paths for symlinks (reliability)Quote all path variables: `"$HOME/.config"`Test with architecture detection for cross-platform supportRepository Structure
The dotfiles are organized by tool/category:
**git/** - Git configuration**emacs/** - Emacs literate programming config (org-mode)**zsh/** - Custom zsh with no external dependencies**claude/** - Claude Code configurations**bin/** - Custom command-line utilities**docs/emacs/** - Educational documentation (org-mode)**Brewfile** - Package dependencies organized by categoryKey Files
`install.sh` - Main interactive installation script`local.zsh.example` - Template for private tokens/secrets`config.org` - Literate Emacs configuration`.zshenv` - Zsh environment setupInstallation Features
The custom installation system provides:
1. **Fully interactive prompts** with "No" as safe default
2. **Smart detection** of already-installed configurations
3. **Backup functionality** for existing configurations
4. **Diff display** between existing and new configurations
5. **No external dependencies** (formerly used GNU stow)
6. **Special handling** for Doom Emacs detection
7. **Warning system** for XDG-style configurations in ~/.config
8. **Automatic detection** of oh-my-zsh installations
Development Workflow
When making changes to this repository:
1. **Branch Strategy**
- Use feature branches: `feature/name-of-enhancement`
- Make focused changes related to a single enhancement
2. **Before Committing**
- Test changes thoroughly
- Run `bash -n script.sh` to syntax-check shell scripts
- Update CLAUDE.md and CHANGELOG.md for significant changes
- Create GitHub issues for tracking work items
3. **Commit Messages**
- Use descriptive messages explaining the purpose
- Reference issue numbers when applicable
4. **Documentation**
- Reference `docs/workflow.md` for detailed processes
- Keep educational docs in org-mode format under `docs/emacs/`
Recent Major Changes
2025-12-22 - Emacs 30.2 with Tree-sitter
Upgraded to Emacs 30.2 with tree-sitter supportAdded grammars: tsx, typescript, javascript, json, cssAuto-install on first launch (~30sec compile)Replaces web-mode for JS/TS/CSS/JSON filesUpdated emacs symlink: `/opt/homebrew/bin/` → `~/.local/bin/`2025-08-01 - Custom Utilities
Added `bin/` directory for CLI toolsCreated `killport` utility (lists ports, kills by port with confirmation)Added `kp` alias as shorthand2025-04-24 - Installation Rebuild
Removed GNU stow dependencyDirect symlink approach with absolute pathsFully interactive with safe defaultsSmart detection, diff, and backup functionalityDoom Emacs and XDG configuration detectionEmacs Configuration
**Style**: Literate programming using org-mode**Launch commands**: - `em` - GUI Emacs properly detached from terminal
- `emacs` - Terminal Emacs with -nw option
**Features**: - Centralized backup/auto-save files
- Disabled lock files
- Tree-sitter for modern TypeScript/React
- Theme loading from config.org
Zsh Configuration
Custom configuration with literate programming approachNo external dependencies (no oh-my-zsh)Multiple prompt styles with git integrationEmacs-style keybindingsOrganized aliases by category (general, git, docker, etc.)PATH configuration for Homebrew on Apple SiliconActive Roadmap
Tracked GitHub issues for ongoing improvements:
#9: GitHub Copilot Integration for Emacs#11: tmux Configuration for Terminal Session Management#12: project.el Configuration for Emacs Project Management#13: move-file Utility for Emacs#14: Enhanced Search with Swiper and ripgrep#15: Terminal-based AI Assistant Tools#16: fzf for Fuzzy Finding in ZSH#17: Emacs Educational Documentation SeriesWhen Working on This Repository
1. **Always check** existing configurations before suggesting changes
2. **Preserve** the interactive, safe-default philosophy
3. **Test on macOS first** (primary platform)
4. **Document** any new utilities or significant changes
5. **Follow** the established code style strictly
6. **Create issues** for tracking enhancement work
7. **Update** CLAUDE.md and CHANGELOG.md for major changes
Platform Support
**Primary**: macOS (last 10 years of active development)**Secondary**: Generic Unix/Linux (basic support, architecture detection)**Deprecated**: Windows (no active maintenance)Special Considerations
The repository uses **direct symlinks with absolute paths** for reliability**Homebrew on Apple Silicon**: Special PATH handling required**Private data**: Use `local.zsh.example` template for tokens/secrets**Doom Emacs**: Installation script detects and provides guidance**XDG configurations**: Warning system for ~/.config conflicts