Initial upload: DotMigrate dotfiles migration tool with CI/CD

README.md

@@ -1,3 +1,325 @@
-# dotmigrate
+# DotMigrate
 
-A Rust-based CLI tool that automatically migrates dotfiles and configurations between machines with intelligent conflict resolution, cross-platform support, and multiple sync backends.
+A Rust-based CLI tool that automatically migrates dotfiles and configurations between machines with intelligent conflict resolution, cross-platform support, and multiple sync backends.
+
+## Overview
+
+DotMigrate helps you manage and synchronize your dotfiles (configuration files) across multiple machines. It provides:
+
+- **Automatic detection** of existing dotfiles in your home directory
+- **Three-way merge strategy** for intelligent conflict resolution
+- **Multiple sync backends**: Git, S3, and Direct transfer
+- **Cross-platform support**: Linux, macOS, and WSL
+- **Safe preview mode** with `--dry-run` flag
+- **Shell completions** for bash, zsh, and fish
+
+## Installation
+
+### From Source
+
+```bash
+cargo install --features full dotmigrate
+```
+
+### Building
+
+```bash
+git clone https://github.com/yourusername/dotmigrate
+cd dotmigrate
+cargo build --release --features full
+```
+
+### Using Features
+
+- `git` - Enable Git backend (default)
+- `s3` - Enable S3 backend
+- `direct` - Enable Direct backend
+- `dialoguer` - Enable interactive prompts (default)
+- `full` - Enable all features
+
+```bash
+cargo build --features full
+```
+
+## Quick Start
+
+### 1. Initialize Configuration
+
+```bash
+dotmigrate init
+```
+
+This creates a default configuration file at `~/.dotmigrate/config.yml`.
+
+### 2. Detect Existing Dotfiles
+
+```bash
+dotmigrate detect
+```
+
+DotMigrate will scan your home directory for known configuration files.
+
+### 3. Create a Backup
+
+```bash
+dotmigrate backup
+```
+
+Creates a timestamped backup of your detected dotfiles.
+
+### 4. Sync Your Dotfiles
+
+```bash
+dotmigrate sync --remote https://github.com/yourusername/dotfiles
+```
+
+## Configuration
+
+DotMigrate uses YAML configuration files. The default location is `~/.dotmigrate/config.yml`.
+
+### Example Configuration
+
+```yaml
+version: "1.0"
+sync:
+  backend: Git
+  remote: https://github.com/username/dotfiles
+  branch: main
+  path: dotfiles
+merge:
+  strategy: ask
+  keep_backup: true
+  auto_resolve: false
+detect:
+  patterns:
+    - ".*"
+    - ".config/*"
+    - ".local/*"
+  exclude_patterns:
+    - ".git"
+    - ".gitignore"
+    - node_modules
+  include_hidden: true
+  scan_depth: 5
+backup:
+  directory: ~/.dotmigrate/backups
+  max_backups: 10
+```
+
+## Commands
+
+### init
+
+Initialize a new DotMigrate configuration.
+
+```bash
+dotmigrate init --backend git
+```
+
+Options:
+- `--backend <git|s3|direct>` - Choose sync backend
+
+### detect
+
+Scan for dotfiles in your home directory.
+
+```bash
+dotmigrate detect --output detected.yml
+```
+
+Options:
+- `--output <path>` - Save detected dotfiles to file
+- `--include-system` - Include system configuration files
+
+### backup
+
+Create a backup of your dotfiles.
+
+```bash
+dotmigrate backup --backup-dir /path/to/backups
+```
+
+Options:
+- `--output <path>` - Save backup manifest
+- `--backup-dir <path>` - Custom backup directory
+
+### sync
+
+Synchronize dotfiles with remote storage.
+
+```bash
+dotmigrate sync --remote https://github.com/user/dotfiles --branch main
+```
+
+Options:
+- `--remote <url>` - Remote repository/bucket URL
+- `--branch <name>` - Branch name (Git) or path (S3)
+- `--strategy <diff3|ours|theirs|ask>` - Merge strategy
+
+### merge
+
+Perform three-way merge on specific files.
+
+```bash
+dotmigrate merge --base base.txt --local local.txt --remote remote.txt --output merged.txt
+```
+
+Options:
+- `--base <path>` - Base/common ancestor file
+- `--local <path>` - Local version
+- `--remote <path>` - Remote version
+- `--output <path>` - Output file path
+- `--strategy <diff3|ours|theirs|ask>` - Merge strategy
+
+### status
+
+Show current status and configuration.
+
+```bash
+dotmigrate status
+```
+
+Options:
+- `--detailed` - Show detailed information
+
+### diff
+
+Compare local and remote files.
+
+```bash
+dotmigrate diff --local ~/.vimrc --remote dotfiles/.vimrc
+```
+
+### completions
+
+Generate shell completions.
+
+```bash
+dotmigrate completions bash > ~/.bash_completion.d/dotmigrate
+dotmigrate completions zsh > ~/.zsh/completion/_dotmigrate
+```
+
+## Sync Backends
+
+### Git
+
+Sync dotfiles using a Git repository.
+
+```bash
+dotmigrate sync --backend git --remote https://github.com/user/dotfiles
+```
+
+Requirements:
+- Git installed
+- SSH key or credentials for private repos
+
+### S3
+
+Sync dotfiles using S3-compatible storage.
+
+```bash
+dotmigrate sync --backend s3 --remote s3://my-bucket/dotfiles
+```
+
+Environment variables:
+- `AWS_REGION` - AWS region
+- `AWS_ACCESS_KEY_ID` - AWS access key
+- `AWS_SECRET_ACCESS_KEY` - AWS secret key
+
+### Direct
+
+Direct file transfer for local backups.
+
+```bash
+dotmigrate sync --backend direct --remote /path/to/backup
+```
+
+## Conflict Resolution
+
+DotMigrate uses three-way merging when both local and remote changes exist.
+
+### Merge Strategies
+
+- **diff3** - Standard three-way merge with conflict markers
+- **ours** - Keep local version
+- **theirs** - Keep remote version
+- **ask** - Interactive prompt for each conflict
+
+### Conflict Markers
+
+When conflicts occur, they are marked like this:
+
+```
+<<<<<<< LOCAL
+local content
+=======
+remote content
+>>>>>>> REMOTE
+```
+
+## Cross-Platform Support
+
+DotMigrate automatically detects your platform and adjusts paths accordingly:
+
+| Platform | Config Directory | Data Directory |
+|----------|-----------------|----------------|
+| Linux | `~/.config` | `~/.local/share` |
+| macOS | `~/Library/Application Support` | `~/Library/Application Support` |
+| WSL | `~/.config` | `~/.local/share` |
+
+## Dry Run Mode
+
+Use `--dry-run` to preview operations without making changes:
+
+```bash
+dotmigrate sync --dry-run --verbose
+dotmigrate backup --dry-run
+```
+
+## Examples
+
+### Basic Setup
+
+```bash
+# Initialize with Git backend
+dotmigrate init --backend git
+
+# Detect and show dotfiles
+dotmigrate detect
+
+# Create initial backup
+dotmigrate backup
+
+# Push to remote
+dotmigrate sync --remote https://github.com/user/dotfiles
+```
+
+### Syncing Between Machines
+
+```bash
+# On machine A
+dotmigrate sync --remote https://github.com/user/dotfiles --push
+
+# On machine B
+dotmigrate sync --remote https://github.com/user/dotfiles
+```
+
+### Resolving Conflicts
+
+```bash
+# When conflicts occur
+dotmigrate merge --base base.txt --local local.txt --remote remote.txt --output merged.txt --strategy ask
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `cargo test --features full`
+5. Run linter: `cargo clippy --features full`
+6. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details