dotfiles/docs/README.md

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

Core Commands

# Installation and setup
./install.sh                # Initial setup with profile detection
dotstatus                   # Show sync status and last update
dotsync                     # Manual sync now
dotprofile                  # Show current machine profile

# Package management  
dotpkgs                     # Show package status for current profile
dotinstall                  # Install all packages for current profile
dotupdatecheck              # Check for package updates (fast)
dotupdate                   # Install pending updates

# Profile management
dotprofileset server        # Switch to server profile
dotprofiledetect            # Re-detect machine type
dotprofile                  # Show current profile status

# Reset and cleanup
dotreset                    # Interactive reset menu
dotresetsoft                # Remove configs, restore originals
dotresethard                # Soft reset + uninstall packages
dotresetnuke                # Complete removal (back to vanilla)

Universal Aliases (Available on All Machines)

# 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

# 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:

# 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:

# 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:

# 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

# 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

# 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

# Clone the repository
cd ~
git clone <repository-url> .dotfiles
cd .dotfiles

# Run installation (will auto-detect machine type)
chmod +x install.sh
./install.sh

# Restart shell or source configs
exec $SHELL

Customization

# Change machine profile
dotprofileset dev-lite
dotinstall

# Add custom aliases
vim ~/.dotfiles/shared/aliases

# Sync changes across machines
git add -A && git commit -m "Custom aliases"
git push

Advanced Configuration

# Disable auto-sync
dotsoff

# Force profile re-detection
dotprofiledetect

# Check what packages would be installed
dotpkgs

# Reset to clean state
dotreset

🤝 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
• Configuration Reference
• Troubleshooting Guide
• API Reference

---

This dotfiles system represents a modern approach to configuration management, balancing automation with flexibility, and efficiency with comprehensive functionality.