# Modern Dotfiles Management System A comprehensive, intelligent dotfiles management system that provides consistent terminal environments across multiple machines while adapting to different machine types (servers vs development machines). ## 🎯 Project Overview This dotfiles system solves the common problem of maintaining consistent development environments across multiple machines with different purposes. Whether you're working on a minimal server, a full development machine, or anything in between, this system adapts to provide exactly what you need without bloat. ### Key Problems Solved 1. **Machine Type Awareness**: Servers don't need Claude AI or Docker, but development machines do 2. **Sync Efficiency**: Updates only when needed, not every terminal session 3. **Package Management**: Automatically installs and updates tools from multiple sources 4. **Configuration Consistency**: Same aliases and shortcuts everywhere 5. **Easy Reset**: Can completely restore system to vanilla state ## 🏗️ Architecture ``` ~/.dotfiles/ ├── install.sh # Main installation script ├── sync.sh # Auto-sync with git repository ├── reset.sh # Reset to vanilla state ├── machine-profiles.yaml # Machine type definitions ├── packages.yaml # Package definitions ├── bash/ # Bash-specific configurations ├── zsh/ # Zsh-specific configurations ├── shared/ # Universal configurations ├── git/ # Git configuration ├── vim/ # Vim configuration ├── lib/ # Core libraries └── docs/ # Documentation ``` ## 🤖 Machine Profiles The system automatically detects and configures based on machine type: ### Server Profile - **Purpose**: Minimal server setup - **Packages**: `curl`, `git`, `vim`, `sshuttle`, `ripgrep`, `fd` - **Use Case**: Production servers, minimal VMs - **Auto-detection**: SSH connections, systemd services, no GUI ### Development Profile - **Purpose**: Full development environment - **Packages**: All tools including Claude AI, Gemini CLI, Docker, modern CLI tools - **Use Case**: Primary development machines - **Auto-detection**: Code editors, development directories, Node.js/Python ### Development Lite Profile - **Purpose**: Development without heavy packages - **Packages**: Development tools but no Docker/containers - **Use Case**: Lightweight VMs, resource-constrained machines - **Auto-detection**: Development tools present but limited resources ### Personal Profile - **Purpose**: Personal machines with all conveniences - **Packages**: Everything including task management tools - **Use Case**: Personal laptops, home workstations - **Auto-detection**: Personal directories, browsers, GUI environment ### Minimal Profile - **Purpose**: Absolute bare bones - **Packages**: `curl`, `git`, `vim` only - **Use Case**: Emergency access, extremely limited environments ## 🔄 Intelligent Sync System ### Auto-Sync Features - **Daily sync**: Automatically syncs once per day maximum - **Background operation**: Non-blocking terminal startup - **Smart timing**: Won't sync more than once per 24 hours - **Manual override**: Force sync anytime with `dotsync` ### Update Management - **Efficient checking**: Fast update detection without expensive operations - **Selective updates**: Only updates packages that actually need it - **Cross-source support**: npm, GitHub releases, system packages - **Profile-aware**: Only checks packages relevant to current machine type ## 📦 Package Management ### Supported Package Sources 1. **System packages**: apt/yum/brew (curl, git, vim, sshuttle) 2. **npm packages**: Claude AI, Gemini CLI, Task Master 3. **GitHub releases**: Modern CLI tools (bat, ripgrep, fzf, fd, delta) 4. **Repository clones**: Tools requiring custom installation 5. **Oh My Zsh plugins**: Shell enhancements ### Installation Methods - **Automatic detection**: OS and package manager detection - **Fallback strategies**: Multiple installation methods per package - **Error handling**: Graceful failures with helpful messages - **Logging**: Detailed installation logs for troubleshooting ## 🎮 Command Interface The system uses an intuitive `dot [subaction] [flags]` command structure: ```bash # Installation and setup ./install.sh # Initial setup with profile detection dot help # Show all available commands dot version # Show version information # Sync Management dot sync # Manual sync now dot sync --force # Force sync (ignore timing limits) dot sync status # Show sync status and last update dot sync on # Enable automatic syncing dot sync off # Disable automatic syncing # Package Management dot packages # Show package status for current profile dot packages install # Install all packages for current profile dot packages check # Check package installation status dot packages update # Install pending updates dot packages check-updates # Check for package updates (fast) dot packages status # Show update status # Profile Management dot profile # Show current machine profile dot profile set # Switch to specified profile (server/dev/personal) dot profile detect # Re-detect machine type # Reset and Cleanup dot reset # Interactive reset menu dot reset --soft # Remove configs, restore originals dot reset --hard # Soft reset + uninstall packages dot reset --nuclear # Complete removal (back to vanilla) ``` ### Universal Aliases (Available on All Machines) ```bash # Navigation .. # cd .. ... # cd ../.. ~ # cd ~ # File operations l # ls -lah ll # ls -l la # ls -la # Git shortcuts g # git ga # git add gc # git commit gp # git push gs # git status # System monitoring df # df -h free # free -h ps # ps aux # Network ports # netstat -tuln myip # curl ifconfig.me # Package management (Debian/Ubuntu) apt-update # sudo apt update && sudo apt upgrade apt-install # sudo apt install ``` ### Profile-Specific Aliases ```bash # Development machines only tm # task-master claude # Claude AI CLI gemini # Gemini CLI # SSH tunneling (server + dev) sshuttle-vpn # Base VPN command sshuttle-txtwire # Specific VPN connection ``` ### Git Remote URL Conversion The system includes convenient functions to convert git remote URLs between SSH and HTTPS formats: ```bash # Automatic conversion (detects current format and converts to opposite) git-remote-toggle # Toggle between SSH/HTTPS for origin git-remote-toggle upstream # Toggle for specific remote # Convert to specific format git-remote-ssh # Convert origin to SSH format git-remote-https # Convert origin to HTTPS format git-remote-ssh upstream # Convert specific remote to SSH # Advanced usage with confirmation prompts git-convert origin ssh # Convert origin to SSH with confirmation git-convert origin https # Convert origin to HTTPS with confirmation ``` **Supported URL formats:** - SSH: `git@github.com:user/repo.git` - HTTPS: `https://github.com/user/repo.git` - HTTPS (no .git): `https://github.com/user/repo` **Example usage:** ```bash # Check current remote git remote -v # origin https://github.com/user/repo.git (fetch) # origin https://github.com/user/repo.git (push) # Convert to SSH git-remote-ssh # 🔄 Converting git remote 'origin' # From (https): https://github.com/user/repo.git # To (ssh): git@github.com:user/repo.git # Proceed with conversion? [y/N]: y # ✅ Successfully converted remote 'origin' # Toggle back to HTTPS git-remote-toggle # 🔄 Converting git remote 'origin' # From (ssh): git@github.com:user/repo.git # To (https): https://github.com/user/repo.git ``` ## 🔧 Technical Implementation ### Profile Detection Algorithm The system uses a scoring algorithm to detect machine type: ```bash # Server indicators (weight) - systemd active (30 points) - SSH connection (25 points) - Multi-user target (20 points) - No logged users (10 points) # Development indicators - Development tools present (30 points) - Code editor available (25 points) - Dev directories exist (20 points) - GUI environment (15 points) # Personal indicators - Personal directories (20 points) - Browser available (25 points) - Personal home path (15 points) ``` ### Update Checking Strategy ```bash # Fast check methods npm outdated -g --json # No installs, just version comparison GitHub API calls # Latest release info Local version parsing # Current installed versions # Selective updates Only outdated packages # Skip up-to-date ones Profile filtering # Server won't check Claude/Gemini Batch operations # Update multiple efficiently ``` ### Sync Optimization ```bash # Timing controls 24-hour auto-sync limit # Prevent excessive git operations 5-minute manual override # Allow frequent manual syncing Background execution # Non-blocking terminal startup # Change detection Git fetch + compare # Check for remote changes Local diff detection # Handle local modifications Automatic stash/restore # Preserve local changes ``` ## 🛡️ Safety Features ### Backup System - **Pre-installation backup**: All existing configs saved - **Timestamped backups**: Never overwrites previous backups - **Symlink detection**: Preserves existing dotfiles setups - **Restoration capability**: Can restore original configs ### Reset Capabilities - **Soft reset**: Remove dotfiles, restore originals - **Hard reset**: Also uninstall packages - **Nuclear reset**: Complete removal - **Safety prompts**: Confirmation for destructive operations ### Error Handling - **Graceful failures**: Continue on non-critical errors - **Detailed logging**: All operations logged with timestamps - **Rollback capability**: Can undo changes if needed - **Dependency checking**: Verify requirements before installation ## 📈 Performance Characteristics ### Startup Time - **Cold start**: ~2 seconds (first terminal of day with sync) - **Warm start**: ~0.1 seconds (subsequent terminals) - **Background sync**: Non-blocking, invisible to user ### Update Efficiency - **Traditional approach**: `npm update -g` (30-60 seconds) - **Smart checking**: `dotupdatecheck` (2-5 seconds) - **Selective updates**: Only outdated packages (10-20 seconds) ### Resource Usage - **Memory footprint**: Minimal (shell functions only) - **Disk usage**: ~50MB for full dev profile - **Network usage**: Efficient API calls, cached results ## 🎯 Use Cases ### Scenario 1: DevOps Engineer **Need**: Consistent tools across 20+ servers and 3 development machines **Solution**: - Servers get `server` profile (minimal, essential tools only) - Development machines get `dev` profile (full toolchain) - Same aliases and shortcuts everywhere - Auto-sync keeps everything updated ### Scenario 2: Full-Stack Developer **Need**: Rich development environment that's portable **Solution**: - `personal` profile on main machine (everything) - `dev-lite` profile on cloud VMs (no Docker overhead) - Universal shortcuts for Git, navigation, system monitoring - Automatic package updates ### Scenario 3: System Administrator **Need**: Minimal, secure server environments **Solution**: - `server` or `minimal` profiles - Essential tools only (no AI assistants, development tools) - Same navigation and system aliases - Easy reset to vanilla if needed ## 🚀 Getting Started ### Quick Start ```bash # Clone the repository cd ~ git clone .dotfiles cd .dotfiles # Run installation (will auto-detect machine type) chmod +x install.sh ./install.sh # Restart shell or source configs exec $SHELL ``` ### Customization ```bash # Change machine profile dot profile set dev-lite dot packages install # Add custom aliases vim ~/.dotfiles/shared/aliases # Sync changes across machines git add -A && git commit -m "Custom aliases" git push ``` ### Advanced Configuration ```bash # Disable auto-sync dot sync off # Force profile re-detection dot profile detect # Check what packages would be installed dot packages # Reset to clean state dot reset ``` ## 🤝 Contributing This system is designed to be easily extensible: 1. **Add new packages**: Update `packages.yaml` and profile definitions 2. **Create new profiles**: Add to `machine-profiles.yaml` 3. **Extend functionality**: Add functions to `shared/functions` 4. **Improve detection**: Enhance profile detection logic ## 📚 Additional Resources - [Installation Guide](INSTALLATION.md) - [Configuration Reference](CONFIGURATION.md) - [Troubleshooting Guide](TROUBLESHOOTING.md) - [API Reference](API.md) --- *This dotfiles system represents a modern approach to configuration management, balancing automation with flexibility, and efficiency with comprehensive functionality.*