From 06faf3929b80dd316c7ef9832fd79752e0f97a98 Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Wed, 4 Feb 2026 09:52:56 +0000 Subject: [PATCH] Initial upload: DotMigrate dotfiles migration tool with CI/CD --- README.md | 326 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 324 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2ab5a68..a79ce74 100644 --- a/README.md +++ b/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. \ No newline at end of file +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 ` - Choose sync backend + +### detect + +Scan for dotfiles in your home directory. + +```bash +dotmigrate detect --output detected.yml +``` + +Options: +- `--output ` - 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 ` - Save backup manifest +- `--backup-dir ` - Custom backup directory + +### sync + +Synchronize dotfiles with remote storage. + +```bash +dotmigrate sync --remote https://github.com/user/dotfiles --branch main +``` + +Options: +- `--remote ` - Remote repository/bucket URL +- `--branch ` - Branch name (Git) or path (S3) +- `--strategy ` - 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 ` - Base/common ancestor file +- `--local ` - Local version +- `--remote ` - Remote version +- `--output ` - Output file path +- `--strategy ` - 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