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

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