Initial upload: DotMigrate dotfiles migration tool with CI/CD
This commit is contained in:
326
README.md
326
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
|
||||
|
||||
Reference in New Issue
Block a user