A comprehensive, modular dotfiles repository using GNU Stow for symlink management, designed for macOS development environments with security and maintainability in mind.

# Clone the repository
cd $HOME
git clone https://github.com/RickCogley/dotfiles.git .dotfiles
cd .dotfiles

# Apply configurations
stow git zsh vim

# Set up your private configuration
cp ~/.gitconfig.local.template ~/.gitconfig.local
$EDITOR ~/.gitconfig.local  # Add your GPG key and other secrets

• Git: Comprehensive git configuration with secure secret management
• Zsh: Modern shell setup with Znap plugin manager and Starship prompt
• Vim: Editor configuration and plugins
• Security: GPG signing, SSH key management, and secret handling patterns
• Documentation: Complete guides following industry standards

• 🔒 Security-first design - Secrets never committed to the repository
• 🧩 Modular structure - Apply only the configurations you need
• 📖 Comprehensive documentation - Tutorials, guides, and references
• 🔄 Cross-machine compatibility - Consistent setup across multiple systems
• 🛡️ Split configuration - Public configs in repo, private configs local-only

📚 Full Documentation

• 🎓 Getting Started Tutorial - Step-by-step setup guide
• 🏗️ Architecture Overview - How it all works
• 🔐 Security Guide - Keeping your secrets safe
• ⚙️ Configuration Reference - Detailed configuration docs

• Tutorials - Learning-oriented guides for beginners
• How-to Guides - Task-oriented solutions for specific problems
• Reference - Technical specifications and configuration details
• Explanations - Conceptual discussions and design decisions

After trying various dotfile management methods, GNU Stow emerged as the ideal solution:

• Simple and reliable - Just creates standard symlinks
• No dependencies - Works anywhere git and stow are available
• Transparent - Easy to understand and debug
• Flexible - Apply configurations selectively

For systems without git/stow, rsync provides a reliable fallback option.

These dotfiles prioritize:

• Security over convenience
• Simplicity over features
• Documentation over assumptions
• Modularity over monolithic configs

This is a personal configuration repository, but the documentation and patterns may be useful for others building their own dotfile systems. Feel free to:

• Use any patterns or documentation for your own setup
• Submit issues for documentation improvements
• Share feedback on the architecture approach

This repository is shared under the MIT License. See LICENSE for details.

📖 For complete setup instructions and detailed documentation, visit rickcogley.github.io/dotfiles