🚀 Git Migration Tool v2.1.0

Universal Git platform migration with flexible author handling

Created by Dev Kraken | https://devkraken.com | [email protected]

📋 Table of Contents

Overview
Quick Start
Installation
Features
Usage
Author Modes
Platform Support
Configuration
Examples
Troubleshooting
Contributing
License

🌟 Overview

The Git Migration Tool v2.1.0 is a comprehensive solution for migrating repositories between any Git platforms with advanced author handling capabilities. Whether you're moving from GitLab to GitHub, GitHub to BitBucket, or any combination of Git platforms, this tool provides a seamless, safe, and feature-rich migration experience.

Key Highlights:

🌐 Universal Platform Support: GitHub ↔ GitLab ↔ BitBucket ↔ Any Git Platform
👥 Three Flexible Author Modes: Preserve, Selective, or Unified authorship
🛡️ Safety First: Comprehensive dry-run mode and validation
🧹 Repository Optimization: Automatic cleanup and optimization
📊 Detailed Logging: Full audit trail of migration process
🎯 Interactive Mode: User-friendly guided setup

⚡ Quick Start

For the fastest setup, use interactive mode:

# Clone the repository
git clone https://github.com/dev-kraken/git-migration-tool.git
cd git-migration-tool

# Make executable and run
chmod +x git-migration-tool.sh
./git-migration-tool.sh --interactive

For global installation:

# Install globally (recommended)
chmod +x install-global.sh
./install-global.sh

# Use from anywhere
git-migration-tool --interactive

🔧 Installation

Method 1: Local Installation

# Clone the repository
git clone https://github.com/dev-kraken/git-migration-tool.git
cd git-migration-tool

# Make scripts executable
chmod +x git-migration-tool.sh install-global.sh
chmod +x examples/*.sh

Method 2: Global Installation (Recommended)

# Install globally with automatic setup
./install-global.sh

# Verify installation
git-migration-tool --help

Method 3: Direct Download

# Download main script only
curl -O https://raw.githubusercontent.com/dev-kraken/git-migration-tool/main/git-migration-tool.sh
chmod +x git-migration-tool.sh

# Run in standalone mode
./git-migration-tool.sh --help

Dependencies

The tool automatically installs required dependencies:

Git (required)
Python 3 (required)
git-filter-repo (auto-installed)

✨ Features

🌐 Universal Platform Support

GitHub ↔ GitLab ↔ BitBucket
AWS CodeCommit ↔ Azure DevOps
SourceForge ↔ Generic Git servers
Auto-platform detection from URLs

👥 Author Handling Modes

Preserve Mode (Default): Keep all original commit authors
Selective Mode: Change specific author only
Unified Mode: Convert all commits to single author

🛡️ Safety & Validation

Dry Run Mode: Test migrations without changes
URL Validation: Comprehensive repository URL checking
Platform Validation: Ensure compatible source/target
Backup Integration: Automatic backup creation

🎯 User Experience

Interactive Mode: Guided setup with auto-detection
Verbose Logging: Detailed progress tracking
Progress Indicators: Real-time migration status
Error Recovery: Robust error handling and recovery

🧹 Repository Optimization

Large File Cleanup: Remove/reduce oversized files
History Optimization: Streamline commit history
Gitignore Enhancement: Improved ignore patterns
Branch Management: Handle multiple branches and tags

📚 Usage

Basic Syntax

git-migration-tool [OPTIONS] COMMAND

Commands

migrate - Full migration between platforms
sync - Synchronize changes between repositories
help - Show detailed help information

Global Options

Option	Description	Example
`-i, --interactive`	Interactive mode (recommended)	`--interactive`
`-d, --dry-run`	Test run without changes	`--dry-run`
`-f, --force`	Skip confirmations	`--force`
`-v, --verbose`	Detailed logging	`--verbose`
`--max-size SIZE`	Maximum file size	`--max-size 50M`
`--main-branch-only`	Migrate only main branch	`--main-branch-only`

Repository Options

Universal Syntax (Recommended):

--source-url URL    # Source repository URL
--target-url URL    # Target repository URL  
--from URL          # Source URL (short form)
--to URL            # Target URL (short form)

Legacy Syntax (Still Supported):

--gitlab-url URL    # GitLab repository URL
--github-url URL    # GitHub repository URL

Author Options

Mode	Options	Description
`--preserve`	None	Keep original authors (default)
`--selective`	`--source-name`, `--source-email` `--target-name`, `--target-email`	Change specific author only
`--unified`	`--target-name`, `--target-email`	Convert all to single author

👥 Author Modes

1. 🔒 Preserve Mode (Default)

Keep all original commit authors unchanged

git-migration-tool --preserve \
    --from "https://gitlab.com/user/repo.git" \
    --to "https://github.com/user/repo.git" \
    migrate

Use Case: Standard migrations where author history is important

2. 🎯 Selective Mode

Change commits from one specific author only

git-migration-tool --selective \
    --source-name "Old Developer" \
    --source-email "[email protected]" \
    --target-name "New Developer" \
    --target-email "[email protected]" \
    --from "https://gitlab.com/company/repo.git" \
    --to "https://github.com/company/repo.git" \
    migrate

Use Case: Employee transitions, email changes, or rebrand specific author

3. 🏢 Unified Mode

Convert ALL commits to a single author

git-migration-tool --unified \
    --target-name "Dev Kraken" \
    --target-email "[email protected]" \
    --from "https://github.com/client/repo.git" \
    --to "https://gitlab.com/mycompany/repo.git" \
    migrate

Use Case: Client work, personal branding, or company standardization

🌐 Platform Support

Supported Platforms

Platform	Status	URL Examples
GitHub	✅ Full	`https://github.com/user/repo.git`
GitLab	✅ Full	`https://gitlab.com/user/repo.git`
BitBucket	✅ Full	`https://bitbucket.org/user/repo.git`
AWS CodeCommit	✅ Full	`codecommit::region://repo-name`
Azure DevOps	✅ Full	`https://dev.azure.com/org/project/_git/repo`
SourceForge	✅ Basic	`https://sourceforge.net/p/project/code/`
Generic Git	✅ Basic	Any valid Git URL

Migration Paths

✅ Fully Tested:

GitHub → GitLab
GitLab → GitHub
GitHub → BitBucket
GitLab → BitBucket

✅ Supported (Auto-detected):

Any Git Platform → Any Git Platform

⚙️ Configuration

Interactive Configuration

# Guided setup with auto-detection
git-migration-tool --interactive

Environment Variables

# Set default author for unified mode
export GIT_MIGRATION_AUTHOR_NAME="Dev Kraken"
export GIT_MIGRATION_AUTHOR_EMAIL="[email protected]"

# Set default directories
export GIT_MIGRATION_LOG_DIR="$HOME/.git-migration-tool/logs"
export GIT_MIGRATION_TEMP_DIR="/tmp/git-migration"

Configuration File (Future Feature)

# ~/.git-migration-tool/config.yml
default:
  author_mode: preserve
  dry_run: true
  verbose: true
  max_file_size: "10M"

profiles:
  work:
    target_name: "Work Account"
    target_email: "[email protected]"
  personal:
    target_name: "Dev Kraken"
    target_email: "[email protected]"

📋 Examples

1. Interactive Mode (Recommended)

# Start interactive guided setup
git-migration-tool --interactive

2. Basic Migration (Universal)

# Preserve all authors - any platform to any platform
git-migration-tool --preserve \
    --from "https://github.com/user/repo.git" \
    --to "https://gitlab.com/user/repo.git" \
    migrate

3. Dry Run Testing

# Test migration without making changes
git-migration-tool --dry-run --verbose \
    --unified \
    --target-name "Dev Kraken" \
    --target-email "[email protected]" \
    --from "https://bitbucket.org/team/project.git" \
    --to "https://github.com/team/project.git" \
    migrate

4. Selective Author Change

# Change specific author during migration
git-migration-tool --selective \
    --source-name "Former Employee" \
    --source-email "[email protected]" \
    --target-name "Current Maintainer" \
    --target-email "[email protected]" \
    --from "https://gitlab.com/oldcompany/legacy.git" \
    --to "https://github.com/newcompany/legacy.git" \
    migrate

5. Repository Synchronization

# Sync changes between existing repositories
git-migration-tool --force \
    --from "https://gitlab.com/source/repo.git" \
    --to "https://github.com/target/repo.git" \
    sync

6. Legacy Syntax (Still Supported)

# Traditional GitLab to GitHub migration
git-migration-tool --preserve \
    --gitlab-url "[email protected]:company/project.git" \
    --github-url "[email protected]:company/project.git" \
    migrate

7. Main Branch Only Migration

# Migrate only main branch (clean migration)
git-migration-tool --preserve \
    --main-branch-only \
    --from "https://gitlab.com/company/repo.git" \
    --to "https://github.com/company/repo.git" \
    migrate

8. Large Repository Optimization

# Handle large repositories with file size limits
git-migration-tool --preserve \
    --max-size "50M" \
    --verbose \
    --from "https://gitlab.com/big/repo.git" \
    --to "https://github.com/big/repo.git" \
    migrate

9. Batch Processing (Using Examples)

# Run multiple example migrations
cd examples/
./migrate-preserve-authors.sh
./migrate-selective-author.sh  
./migrate-unified-author.sh
./migrate-main-branch-only.sh
./github-to-gitlab-demo.sh

🔍 Troubleshooting

Common Issues

1. Permission Errors

# Fix script permissions
chmod +x git-migration-tool.sh install-global.sh
chmod +x examples/*.sh

# Check SSH key access
ssh -T [email protected]
ssh -T [email protected]

2. URL Validation Errors

# Ensure URLs end with .git
✅ https://github.com/user/repo.git
❌ https://github.com/user/repo

# Check URL accessibility
git ls-remote https://github.com/user/repo.git

3. Large File Issues

# Reduce max file size limit
git-migration-tool --max-size "5M" ...

# Check repository size
du -sh .git/

4. git-filter-repo Installation

# Manual installation
python3 -m pip install git-filter-repo

# Alternative installation
brew install git-filter-repo  # macOS
sudo apt install git-filter-repo  # Ubuntu

Debug Mode

# Enable maximum verbosity
git-migration-tool --verbose --dry-run ...

# Check logs
tail -f ~/.git-migration-tool/logs/migration-*.log

Getting Help

Check built-in help: git-migration-tool --help
Review examples: cd examples/ and check scripts
Enable verbose mode: Add --verbose flag
Use dry-run: Test with --dry-run first
Check logs: Review log files in logs/ directory

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Fork and clone
git clone https://github.com/dev-kraken/git-migration-tool.git
cd git-migration-tool

# Install development dependencies
./install-global.sh

# Run tests
cd test/
chmod +x *.sh
./test-final-validation.sh

Code Structure

git-migration-tool/
├── git-migration-tool.sh           # Main executable
├── install-global.sh               # Installation script
├── src/
│   ├── git-migration-core.sh       # Core functions
│   ├── platform-detection.sh       # Platform support
│   └── banner-utils.sh             # UI utilities
├── examples/                       # Example scripts and configurations
├── test/                           # Test suite
├── logs/                           # Log files
├── config/                         # Configuration directory
├── backups/                        # Backup directory
└── README.md                       # This file

Adding Platform Support

Update src/platform-detection.sh:

# Add platform detection
detect_platform() {
    case "$url" in
        *newplatform.com*)
            echo "newplatform"
            ;;
    esac
}

Add platform configuration:

get_platform_name() {
    case "$platform" in
        newplatform) echo "New Platform" ;;
    esac
}

Test your changes:
```
cd test/
./test-final-validation.sh
```

Submitting Changes

Create feature branch: git checkout -b feature/new-platform
Make changes and test thoroughly
Update documentation and examples
Submit pull request with detailed description

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Dev Kraken

🌐 Website: https://devkraken.com
📧 Email: [email protected]
🐙 GitHub: @dev-kraken

⭐ Support

If you find this tool helpful, please:

⭐ Star the repository
🐛 Report issues on GitHub
💡 Suggest features via issues
🤝 Contribute improvements

🚀 Happy Migrating! 🚀

Created with ❤️ by Dev Kraken

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backups		backups
config		config
examples		examples
logs		logs
src		src
test		test
.gitignore		.gitignore
README.md		README.md
git-migration-tool.sh		git-migration-tool.sh
install-global.sh		install-global.sh

dev-kraken/git-migration-tool

Folders and files

Latest commit

History

Repository files navigation