git-migrator

Git-Migrator

Migrate version control repositories with full history preservation

Git-Migrator is an open-source tool for migrating repositories from legacy version control systems (CVS, SVN) to Git while preserving complete history, including commits, branches, tags, and author information. It can also keep repositories synchronized bidirectionally after migration.

✨ Features

• 🔄 Full History Migration - Preserve all commits, branches, tags, and metadata
• 🔌 Plugin Architecture - Support for multiple VCS systems (CVS, SVN, and more)
• 🐳 Dual Runtime - Run locally or in Docker with equal functionality
• 🖥️ Dual Interface - Command-line tool and web UI for monitoring
• ⏸️ Resume Capability - Resume interrupted migrations from where they left off
• 📊 Progress Reporting - Real-time progress via terminal or web dashboard
• 🎯 Author Mapping - Map CVS/SVN usernames to Git authors
• ✅ Dry Run Mode - Preview migrations without making changes
• 🔒 Verification - Validate migrated repositories match source

🚀 Quick Start

Using Docker (Recommended)

# Pull the image
docker pull adamf123docker/git-migrator:latest

# Run migration
docker run --rm \
  -v /path/to/cvs/repo:/source \
  -v /path/to/git/repo:/target \
  -v $(pwd)/config.yaml:/config.yaml \
  adamf123docker/git-migrator migrate --config /config.yaml

# Or start web UI
docker run -d \
  -p 8080:8080 \
  -v /path/to/repos:/repos \
  adamf123docker/git-migrator web

Using Binary

# Download latest release
curl -sL https://github.com/adamf123git/git-migrator/releases/latest/download/git-migrator-linux-amd64 -o git-migrator
chmod +x git-migrator

# Run migration
./git-migrator migrate --config config.yaml

📦 Installation

Pre-built Binaries

Download from Releases page:

Platform	Architecture	Download
Linux	amd64	git-migrator-linux-amd64
Linux	arm64	git-migrator-linux-arm64
macOS	amd64	git-migrator-darwin-amd64
macOS	arm64	git-migrator-darwin-arm64
Windows	amd64	git-migrator-windows-amd64.exe

Homebrew (macOS/Linux)

brew tap adamf123git/git-migrator
brew install git-migrator

From Source

git clone https://github.com/adamf123git/git-migrator.git
cd git-migrator
go build -o git-migrator ./cmd/git-migrator

Docker

docker pull adamf123docker/git-migrator:latest

📖 Usage

CLI Commands

# Migrate CVS repository to Git
git-migrator migrate --config config.yaml

# Analyze source repository
git-migrator analyze --source-type cvs --source /path/to/cvs/repo

# Validate configuration
git-migrator validate --config config.yaml

# Extract author list from source repository
git-migrator authors extract --source-type cvs --source /path/to/cvs/repo > authors.txt

# Start web UI
git-migrator web --port 8080

Configuration

Create a config.yaml file:

source:
  type: cvs                    # cvs, svn (future)
  path: /path/to/cvs/repository
  module: mymodule             # CVS module name
  cvsMode: auto                # rcs, binary, auto

target:
  type: git
  path: /path/to/output/git/repository
  remote: git@github.com:user/repo.git  # Optional: push after migration

mapping:
  authors:
    cvsuser1: "John Doe <john@example.com>"
    cvsuser2: "Jane Smith <jane@example.com>"
  
  branches:
    "MAIN": "main"
    "RELEASE_1_0": "release/1.0"
  
  tags:
    "V1_0": "v1.0"
    "V2_0": "v2.0"

options:
  dryRun: false                # Preview without making changes
  preserveEmptyCommits: false  # Keep commits with no file changes
  chunkSize: 100               # State save interval
  verbose: false               # Detailed output
  resume: false                # Resume interrupted migration

CLI Flags

Override configuration with flags:

git-migrator migrate \
  --source /path/to/cvs \
  --target /path/to/git \
  --source-type cvs \
  --dry-run \
  --resume \
  --verbose

Web UI

Start the web interface:

# Local
git-migrator web --port 8080

# Docker
docker run -d -p 8080:8080 -v /path/to/repos:/repos adamf123docker/git-migrator web

Then open http://localhost:8080 in your browser.

Features:

• Migration wizard
• Real-time progress dashboard
• Configuration editor
• Log viewer

🔧 Advanced Usage

Resume Interrupted Migration

If a migration is interrupted (network issue, Ctrl+C, crash):

# Resume from last checkpoint
git-migrator migrate --config config.yaml --resume

State is saved every N commits (configurable via chunkSize).

Dry Run

Preview migration without making changes:

git-migrator migrate --config config.yaml --dry-run --verbose

Author Mapping

Extract authors from CVS repository and generate mapping template:

# Extract unique authors
git-migrator authors extract --source /path/to/cvs > authors.txt

# Edit authors.txt, then use in config:
# mapping:
#   authors:
#     cvsuser1: "Full Name <email@example.com>"

Branch and Tag Mapping

Map CVS branch/tag names to Git equivalents:

mapping:
  branches:
    "MAIN": "main"
    "DEV": "develop"
  
  tags:
    "release-1-0": "v1.0.0"

Verification

After migration, verify repository integrity:

# Check commit count
git rev-list --all --count

# Verify all branches exist
git branch -a

# Verify all tags exist
git tag -l

🏗️ Architecture

Git-Migrator uses a plugin-based architecture for maximum extensibility:

┌─────────────────────────────────────────┐
│      Git-Migrator Core                  │
│                                         │
│  ┌──────────┐      ┌──────────┐        │
│  │ CVS      │      │ SVN      │        │
│  │ Plugin   │      │ Plugin   │ (Soon) │
│  └──────────┘      └──────────┘        │
│                                         │
│  ┌──────────────────────────────────┐  │
│  │      VCS Plugin Interface        │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

Key Components:

• VCS Interface - Standardized API for version control operations
• Migration Orchestrator - Coordinates the migration workflow
• State Manager - Persists progress for resume capability
• Progress Reporter - Real-time updates (CLI + Web UI)

🤝 Contributing

We welcome contributions! Git-Migrator follows Test-Driven Development (TDD).

Development Setup

# Clone repository
git clone https://github.com/adamf123git/git-migrator.git
cd git-migrator

# Install dependencies
go mod download

# Run tests
make test

# Run linter
make lint

# Build
make build

Development Workflow

1. Write test first (TDD)
2. Implement feature
3. Ensure tests pass: make test
4. Check coverage: make test-coverage (must be ≥ 80%)
5. Run linter: make lint
6. Submit PR

See CONTRIBUTING.md for detailed guidelines.

Running Tests

# Unit tests
make test-unit

# Integration tests
make test-integration

# Full regression suite
make test-regression

# Test coverage
make test-coverage

# All tests
make test

📚 Documentation

• Getting Started - Detailed tutorial
• Configuration Guide - All configuration options
• Migration Guide - Step-by-step migration
• Architecture - System design
• API Reference - REST API documentation

🐛 Troubleshooting

Common Issues

Issue: CVS binary not found

Solution: Install CVS or use RCS mode (cvsMode: rcs in config)

Issue: Permission denied

Solution: Ensure read access to source, write access to target

Issue: Migration interrupted

Solution: Resume with --resume flag

Issue: Empty commits not preserved

Solution: Set preserveEmptyCommits: true in config

Debug Mode

Enable verbose logging:

git-migrator migrate --config config.yaml --verbose

Getting Help

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🗺️ Roadmap

Current Version (v1.0)

• ✅ CVS to Git migration
• ✅ Full history preservation
• ✅ Branch and tag migration
• ✅ Author mapping
• ✅ Resume capability
• ✅ Web UI for monitoring
• ✅ Docker support

Coming Soon (v2.0)

• 🔜 Git ↔ CVS bidirectional sync
• 🔜 SVN to Git migration
• 🔜 Mercurial support

Future

• 📋 Git LFS support
• 📋 Monorepo splitting
• 📋 Multi-repository batch migration
• 📋 Advanced conflict resolution

See Roadmap for detailed timeline.

📄 License

Git-Migrator is open-source software licensed under the MIT License.

🙏 Acknowledgments

Inspired by and built upon the shoulders of:

• cvs2git - CVS to Git migration
• git-svn - Git SVN bridge
• go-git - Pure Go Git implementation

📊 Project Status

• Development Status: Production Ready
• Current Version: v1.0.0
• Sprint Progress: Sprint 6 complete - Ready for release
• Release Date: Q1 2025

Completed Sprints

• ✅ Sprint 1: Foundation & Testing Infrastructure
• ✅ Sprint 2: CVS Reading & RCS Parsing
• ✅ Sprint 3: Git Writing & Commit Application
• ✅ Sprint 4: Migration Integration
• ✅ Sprint 5: Web UI & Docker
• ✅ Sprint 6: Testing, Polish & Release

Recent Accomplishments (Sprint 6)

• ✅ All linter warnings resolved with proper error handling
• ✅ Comprehensive documentation (2,680+ lines)
• ✅ Release automation configured
• ✅ Production-ready codebase

See Roadmap for detailed timeline.

---

Made with ❤️ by Adam Farrell

Star ⭐ this repository if you find it useful!