dotmigrate/README.md

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

cargo install --features full dotmigrate

Building

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

cargo build --features full

Quick Start

1. Initialize Configuration

dotmigrate init

This creates a default configuration file at ~/.dotmigrate/config.yml.

2. Detect Existing Dotfiles

dotmigrate detect

DotMigrate will scan your home directory for known configuration files.

3. Create a Backup

dotmigrate backup

Creates a timestamped backup of your detected dotfiles.

4. Sync Your Dotfiles

dotmigrate sync --remote https://github.com/yourusername/dotfiles

Configuration

DotMigrate uses YAML configuration files. The default location is ~/.dotmigrate/config.yml.

Example Configuration

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.

dotmigrate init --backend git

Options:

• --backend <git|s3|direct> - Choose sync backend

detect

Scan for dotfiles in your home directory.

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.

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.

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.

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.

dotmigrate status

Options:

• --detailed - Show detailed information

diff

Compare local and remote files.

dotmigrate diff --local ~/.vimrc --remote dotfiles/.vimrc

completions

Generate shell completions.

dotmigrate completions bash > ~/.bash_completion.d/dotmigrate
dotmigrate completions zsh > ~/.zsh/completion/_dotmigrate

Sync Backends

Git

Sync dotfiles using a Git repository.

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.

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.

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:

dotmigrate sync --dry-run --verbose
dotmigrate backup --dry-run

Examples

Basic Setup

# 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

# 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

# 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