docs: Revamp README and add architecture documentation
This commit is contained in:
Eric Turner
64
README.md
Executable file
64
README.md
Executable file
@@ -0,0 +1,64 @@
|
|||||||
|
# Modern Dotfiles Management System
|
||||||
|
|
||||||
|
A comprehensive and intelligent system for managing your terminal configurations (dotfiles) across diverse machines, ensuring a consistent and optimized environment tailored to each machine's purpose.
|
||||||
|
|
||||||
|
## ✨ Why Use This?
|
||||||
|
|
||||||
|
Maintaining a consistent and efficient terminal environment across multiple machines (e.g., development laptops, servers, personal workstations) can be challenging. This dotfiles system simplifies that by offering:
|
||||||
|
|
||||||
|
* **🤖 Machine-Aware Configuration:** Automatically adapts your environment based on the machine type (server, development, personal), installing only what's needed.
|
||||||
|
* **⚡ Efficient Syncing:** Keeps your dotfiles updated with minimal overhead, syncing intelligently without blocking your workflow.
|
||||||
|
* **📦 Automated Package Management:** Installs and updates essential tools and applications from various sources (system packages, npm, GitHub releases) based on your machine's profile.
|
||||||
|
* **🌍 Consistent Experience:** Enjoy the same aliases, functions, and command-line tools everywhere you work.
|
||||||
|
* **🛡️ Easy Reset & Recovery:** Quickly restore your system to a clean state or revert changes with robust reset capabilities.
|
||||||
|
|
||||||
|
## 🚀 Quick Start
|
||||||
|
|
||||||
|
Get your consistent terminal environment up and running in minutes!
|
||||||
|
|
||||||
|
### One-Line Installation (Recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://raw.githubusercontent.com/your-username/dotfiles/main/install-web.sh | bash
|
||||||
|
```
|
||||||
|
*Replace `your-username/dotfiles` with the actual GitHub path to this repository.*
|
||||||
|
|
||||||
|
### Manual Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~
|
||||||
|
git clone <repository-url> .dotfiles
|
||||||
|
cd .dotfiles
|
||||||
|
./install.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
After installation, restart your shell (`exec $SHELL`) or open a new terminal session.
|
||||||
|
|
||||||
|
## 🎮 Core Commands
|
||||||
|
|
||||||
|
Once installed, you'll have access to powerful commands to manage your dotfiles:
|
||||||
|
|
||||||
|
* `dotstatus`: Check the current sync status and system health.
|
||||||
|
* `dotsync`: Manually trigger a sync to pull the latest dotfiles.
|
||||||
|
* `dotprofile`: Display your current machine profile and its detected type.
|
||||||
|
* `dotpkgs`: List packages installed for your current profile.
|
||||||
|
* `dotupdate`: Check for and install updates for your managed packages.
|
||||||
|
* `dotreset`: Interactively reset your dotfiles to a clean state.
|
||||||
|
|
||||||
|
## 🛠️ Customization
|
||||||
|
|
||||||
|
* **Add New Packages:** Define new packages and their installation methods in `packages.yaml`.
|
||||||
|
* **Custom Aliases/Functions:** Add your personal aliases and shell functions to files within the `shared/` directory.
|
||||||
|
* **Machine Profiles:** Adjust or add new machine profiles in `machine-profiles.yaml` to fine-tune auto-detection and configurations.
|
||||||
|
|
||||||
|
## 📚 Further Documentation
|
||||||
|
|
||||||
|
For more in-depth information on architecture, advanced configuration, troubleshooting, and contributing, please refer to the `docs/` directory:
|
||||||
|
|
||||||
|
* [Installation Guide](docs/INSTALLATION.md)
|
||||||
|
* [Technical Architecture](docs/ARCHITECTURE.md)
|
||||||
|
* [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Your new terminal experience is just a paste away.*
|
||||||
143
docs/ARCHITECTURE.md
Normal file
143
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,143 @@
|
|||||||
|
# Architecture Overview
|
||||||
|
|
||||||
|
This document details the technical architecture and implementation specifics of the Modern Dotfiles Management System.
|
||||||
|
|
||||||
|
## 🏗️ System Structure
|
||||||
|
|
||||||
|
The core components of the dotfiles system are organized as follows:
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.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 using a scoring algorithm:
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
## 🔧 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
|
||||||
Reference in New Issue
Block a user