🌐 MultiGit

One repository. Infinite destinations.

A production-ready, blazingly fast Git multi-remote synchronization tool
Push, pull, and sync your code across GitHub, GitLab, Bitbucket, Codeberg, Gitea/Forgejo with a single command

✨ Available as both multigit and mg commands for your convenience! ✨

📖 Table of Contents

Features • Why MultiGit? • Quick Start • Installation • Usage • Configuration • Security • Examples • FAQ • Contributing • Roadmap

---

✨ Features

🚀 Performance & Reliability ⚡ Blazingly Fast - Parallel operations via Tokio async runtime 🔄 Smart Sync - Incremental updates, not full clones 📊 Progress Tracking - Real-time progress bars and status 🛡️ Atomic Operations - All-or-nothing commits 🔁 Retry Logic - Automatic retry on transient failures

🔒 Security & Privacy 🔐 OS Keyring Integration - Native credential managers 🌐 Host-Bound Credentials - Tokens scoped to specific hosts 🔒 HTTPS Enforcement - Prevents insecure HTTP connections 🔑 Age Encryption - Encrypted credential fallback 🚫 Zero Plain Text - No passwords or tokens in files 📝 Audit Logging - Track all sensitive operations 🛡️ Secret Redaction - Automatic log sanitization 🔒 TLS/SSL - Encrypted network communication

🎯 Intelligent Operations 🧠 Smart Conflict Detection - Prevents data loss 🔀 Multiple Merge Strategies - Fast-forward, rebase, merge 🎯 Selective Sync - Choose branches, remotes, files 🔍 Health Checks - Auto-diagnose and fix issues 📈 Diff Analysis - See exactly what will sync

🎨 Developer Experience 💻 Rich CLI/TUI - Beautiful interactive terminal UI ✨ Conventional Commits - Interactive commit wizard 🤖 Daemon Mode - Background sync with scheduler 🌍 Cross-Platform - Linux, macOS, Windows 📚 Zero Config - Works out-of-the-box

🌐 Supported Platforms

Platform	Status	Features
GitHub	✅ Full Support	Public, Private, Enterprise
GitLab	✅ Full Support	Cloud, Self-hosted
Bitbucket	✅ Full Support	Cloud, Server
Codeberg	✅ Full Support	Public repositories
Gitea	✅ Full Support	Self-hosted instances
Forgejo	✅ Full Support	Self-hosted instances

---

💎 Why MultiGit?

⚡️ Save Time One command replaces dozens Instead of: git push origin main git push github main git push gitlab main git push backup main Simply: mg sync

🛡️ Stay Safe Never lose your code Automatic conflict detection Safe merge strategies Encrypted credentials Audit logging Rollback support

🚀 Work Smarter Built for developers Zero configuration Interactive wizards Beautiful progress bars Daemon mode CI/CD ready

🎯 Real-World Benefits

Traditional Workflow	With MultiGit	Time Saved
Push to 3 remotes manually	mg sync	~2 minutes
Set up credentials for each platform	One-time interactive setup	~15 minutes
Check sync status across platforms	mg status	~5 minutes
Resolve conflicts manually	Interactive resolver	~10 minutes
Total per day		~30 minutes

💰 That's 180+ hours saved per year for a typical developer!

---

🎬 Quick Start

Get started in under 2 minutes! Here's the fastest path to multi-remote nirvana:

# 1️⃣ Initialize MultiGit in your repository
mg init                    # or 'multigit init'

# 2️⃣ Add remote platforms (you'll be prompted for credentials)
mg remote add github <username>
mg remote add gitlab <username>
mg remote add bitbucket <username>

# 3️⃣ Make some changes, then use the interactive commit helper
mg cc                      # Interactive conventional commit wizard
# Or use traditional git commands - they work too!

# 4️⃣ Sync to all remotes with one command! 🚀
mg sync

# 5️⃣ Check sync status across all platforms
mg status

💡 Pro Tip: Use mg for lightning-fast typing or multigit for scripts - they're 100% identical!

🎥 Demo

$ mg sync
✓ Pushing to github...     [████████████████████] 100% (main)
✓ Pushing to gitlab...     [████████████████████] 100% (main)
✓ Pushing to bitbucket...  [████████████████████] 100% (main)
🎉 Successfully synced to 3 remotes in 2.3s

⚡ Performance

3x Faster than sequential pushes

5 Platforms supported

0 Plain text credentials

100% Rust, no dependencies issues

📦 Installation

Choose your preferred installation method:

🚀 From Releases (Easiest)

Download pre-built binaries for your platform from GitHub Releases:

Linux / macOS:

# Download the latest release
curl -LO https://github.com/TIVerse/multigit/releases/latest/download/multigit-linux-x64.tar.gz

# Extract and install
tar -xzf multigit-linux-x64.tar.gz
sudo mv multigit mg /usr/local/bin/

# Verify installation
mg --version

Windows (PowerShell):

# Download and run the installer
Invoke-WebRequest -Uri "https://github.com/TIVerse/multigit/releases/latest/download/multigit-windows-installer.exe" -OutFile "multigit-installer.exe"
.\multigit-installer.exe

🔧 Build from Source

# Clone the repository
git clone https://github.com/TIVerse/multigit.git
cd multigit

# Build release binaries
cargo build --release

# Test the build
./target/release/multigit --version
./target/release/mg --version          # Both binaries are built

# Optional: Install to system
cargo install --path .

🐳 Docker (Coming Soon)

docker pull tiverse/multigit:latest
docker run --rm -v $(pwd):/repo tiverse/multigit mg status

🚀 Usage

🎯 Core Workflows

📋 Initialize a Repository

# Navigate to your Git repository
cd your-git-repository

# Initialize MultiGit
mg init

# MultiGit creates a .multigit/ directory with configuration
# ✓ Configuration file created
# ✓ Default settings applied
# ✓ Ready to add remotes!

🔗 Managing Remote Platforms

# Add GitHub remote
mg remote add github your-username
# You'll be prompted for your Personal Access Token (PAT)

# Add GitLab remote
mg remote add gitlab your-username

# Add Bitbucket
mg remote add bitbucket your-username

# Add self-hosted Gitea/Forgejo
mg remote add mygitea your-username --url https://gitea.example.com

# Add Codeberg
mg remote add codeberg your-username

# List all configured remotes
mg remote list

# Remove a remote
mg remote remove github

# Update remote credentials
mg remote update gitlab --token

🔄 Syncing & Pushing

# Push to all configured remotes
mg push

# Push to specific remote only
mg push --to github

# Push specific branch
mg push --branch develop

# Sync bidirectionally (pull + push)
mg sync

# Sync with conflict resolution
mg sync --interactive

# Force sync (⚠️ use with caution - may overwrite changes)
mg sync --force

# Dry run to preview sync
mg sync --dry-run

📥 Pulling Changes

# Pull from primary remote (configured in settings)
mg pull

# Pull from specific remote
mg pull --from github

# Pull specific branch
mg pull --from gitlab --branch main

# Pull and rebase
mg pull --rebase

📊 Status & Monitoring

# Check sync status across all remotes
mg status

# Detailed status with commit differences
mg status --verbose

# Check specific remote
mg status --remote github

# Watch mode (auto-refresh every 5s)
mg status --watch

✍️ Conventional Commits (Interactive)

# Launch interactive commit wizard
mg cc                    # or 'mg commit'

# The wizard helps you:
# ✓ Select files to stage
# ✓ Choose commit type (feat, fix, docs, style, refactor, test, chore)
# ✓ Auto-detect scope from changed files
# ✓ Add breaking change markers
# ✓ Link to issues/tickets
# ✓ Preview formatted commit message
# ✓ Commit & optionally push

# Example output:
# ? Select commit type: feat
# ? Scope (optional): auth
# ? Short description: add OAuth2 support
# ? Breaking change?: No
# ? Issue reference: #42
# 
# Preview: feat(auth): add OAuth2 support (#42)
# 
# ✓ Committed successfully!

⚔️ Conflict Resolution

# List all detected conflicts
mg conflict list

# Resolve conflicts interactively
mg conflict resolve

# Choose resolution strategy
mg conflict resolve --strategy ours     # Use local changes
mg conflict resolve --strategy theirs   # Use remote changes
mg conflict resolve --strategy manual   # Manual resolution

# Show conflict diff
mg conflict diff

🤖 Daemon Mode (Background Sync)

# Start daemon with 5-minute sync interval
mg daemon start --interval 5m

# Start with hourly sync
mg daemon start --interval 1h

# Check daemon status
mg daemon status

# View daemon logs
mg daemon logs

# Stop daemon
mg daemon stop

# Restart daemon
mg daemon restart

# Configure daemon to run on system startup
mg daemon enable-startup

🔍 Health Check & Diagnostics

# Run comprehensive health check
mg doctor

# The doctor command checks:
# ✓ Git installation and version
# ✓ Remote connectivity
# ✓ Authentication status
# ✓ Configuration validity
# ✓ Repository integrity
# ✓ Network connectivity

# Auto-fix common issues
mg doctor --fix

# Verbose diagnostics
mg doctor --verbose

🎓 Common Scenarios

Mirror a project to GitLab mg remote add gitlab username mg push --to gitlab	Daily auto-sync mg daemon start --interval 24h
Backup to multiple hosts mg remote add github user mg remote add gitlab user mg sync	Check all remotes status mg status --verbose
Emergency conflict fix mg conflict list mg conflict resolve --interactive	Test connectivity mg doctor --verbose

🎨 Advanced Usage

# Chain commands for complex workflows
mg pull --from github && mg cc && mg push

# Use in CI/CD pipelines
mg init && mg remote add gitlab $CI_USERNAME && mg push --to gitlab

# Scheduled sync with cron
# Add to crontab: 0 */6 * * * cd /path/to/repo && mg sync

# Multi-branch sync
for branch in main develop staging; do
  git checkout $branch
  mg sync --branch $branch
done

📖 Configuration

MultiGit uses a hierarchical configuration system with sensible defaults:

🔧 CLI Flags (highest priority)
    ↓
📁 Repository Config (.multigit/config.toml)
    ↓
🏠 User Config (~/.config/multigit/config.toml)
    ↓
⚙️  Default Settings (lowest priority)

📝 Example Configuration

Create a .multigit/config.toml in your repository or ~/.config/multigit/config.toml for global settings:

# ====================================
# MultiGit Configuration
# ====================================

[settings]
# Default branch to sync
default_branch = "main"

# Enable parallel operations for speed
parallel_push = true
max_parallel = 4

# Verbose output
verbose = false

[sync]
# Automatic sync when daemon is running
auto_sync = false

# Primary source for pulling
primary_source = "github"

# Merge strategy: "fast-forward", "rebase", "merge"
strategy = "fast-forward"

# Conflict resolution: "abort", "ours", "theirs", "interactive"
conflict_resolution = "interactive"

[security]
# Authentication backend: "keyring" (recommended) or "encrypted-file"
auth_backend = "keyring"

# Enable audit logging
audit_log = true

# Encrypt local config
encrypt_config = true

[daemon]
# Background sync interval (e.g., "5m", "1h", "24h")
sync_interval = "1h"

# Enable webhook server
webhook_enabled = false
webhook_port = 8080

[ui]
# Progress bar style: "bar", "spinner", "quiet"
progress_style = "bar"

# Color output
color = "auto"  # "auto", "always", "never"

# Show notifications
notifications = true

[remotes.github]
username = "your-username"
enabled = true
# Optional: Custom API URL for GitHub Enterprise
# api_url = "https://github.company.com"

[remotes.gitlab]
username = "your-username"
api_url = "https://gitlab.com"
enabled = true

[remotes.bitbucket]
username = "your-username"
enabled = false

[remotes.codeberg]
username = "your-username"
enabled = true

[remotes.mygitea]
username = "your-username"
api_url = "https://gitea.example.com"
enabled = true

🎛️ Configuration Commands

# View current configuration
mg config show

# Set a configuration value
mg config set sync.strategy rebase

# Edit configuration in your default editor
mg config edit

# Validate configuration
mg config validate

# Reset to defaults
mg config reset

🔒 Security

🛡️ Security is our top priority. Your credentials are never compromised.

🔐 Credential Management OS Keyring Integration 🔑 macOS: Keychain Windows: Credential Manager Linux: Secret Service / gnome-keyring Encrypted Fallback 🔒 Age encryption when keyring unavailable Password-protected local storage AES-256 encryption standard

🛡️ Security Features Host-Bound Credentials 🌐 Credentials scoped to specific hosts Prevents confused-deputy attacks Automatic migration from legacy keys HTTPS Enforcement 🔒 HTTP URLs rejected by default Opt-in for insecure connections Protects against MitM attacks Zero Plain Text 🚫 No tokens in config files Environment tokens opt-in only Memory wiping after use Secret Redaction 🛡️ Automatic log sanitization Masks tokens, passwords, keys Safe daemon output logging Audit Logging 📝 Track all sensitive operations Credential access monitoring Configurable log retention

🔑 Setting Up Credentials

# Add credentials interactively (recommended)
mg remote add github username
# 🔐 You'll be prompted for your Personal Access Token
# ✓ Token encrypted and stored in OS keyring
# ✓ Never appears in plain text

# Verify credential storage
mg config show --security

🔒 Security Best Practices

✅ Use PATs Personal Access Tokens, not passwords

🔄 Rotate Regularly Update tokens periodically

🎯 Minimal Scope Grant only needed permissions

📋 Audit Logs Review security logs regularly

🚨 Security Reporting

Found a security vulnerability? Please DO NOT open a public issue. Instead:

• 📧 Email: security@tiverse.dev
• 🔒 Use GitHub Security Advisory
• ⏱️ We'll respond within 24-48 hours

🏗️ Architecture

MultiGit follows a clean, modular architecture designed for extensibility and maintainability:

┌─────────────────────────────────────────────────────────┐
│                   Frontend Layer                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │   CLI    │  │   TUI    │  │ Daemon   │  │  API    │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                  Core Engine                             │
│  ┌──────────────┐  ┌─────────────┐  ┌────────────────┐ │
│  │ Sync Manager │  │  Conflict   │  │   Scheduler    │ │
│  │              │  │  Resolver   │  │                │ │
│  └──────────────┘  └─────────────┘  └────────────────┘ │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│              Platform Adapters                           │
│  ┌────────┐  ┌────────┐  ┌──────────┐  ┌────────────┐ │
│  │ GitHub │  │ GitLab │  │Bitbucket │  │Gitea/Forge │ │
│  └────────┘  └────────┘  └──────────┘  └────────────┘ │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│            Git Operations Layer                          │
│              (libgit2 wrapper)                           │
│  ┌───────┐  ┌──────┐  ┌───────┐  ┌─────────────────┐  │
│  │ Clone │  │ Push │  │ Pull  │  │ Conflict Detect │  │
│  └───────┘  └──────┘  └───────┘  └─────────────────┘  │
└──────────────────────────────────────────────────────────┘

🧩 Component Details

Frontend Layer CLI commands Interactive TUI Daemon service REST API (planned)

Core Engine Sync orchestration Conflict detection Job scheduling State management

Platform Adapters GitHub API GitLab API Bitbucket API Gitea/Forgejo API

Git Layer libgit2 wrapper Repository ops Credential mgmt Network transport

🤝 Contributing

We ❤️ contributions! Whether you're fixing bugs, adding features, or improving docs, we welcome your help.

🚀 Quick Start for Contributors

1️⃣ Fork & Clone git clone https://github.com/YOUR_USERNAME/multigit.git cd multigit

2️⃣ Create Branch git checkout -b feature/amazing-feature

3️⃣ Make Changes # Make your changes cargo test cargo fmt

# 4️⃣ Commit with conventional commits
git commit -m 'feat: add amazing feature'

# 5️⃣ Push and create PR
git push origin feature/amazing-feature

📋 Contribution Guidelines

• 📖 Read our Contributing Guide for detailed guidelines
• ✅ Ensure all tests pass: cargo test
• 🎨 Format your code: cargo fmt
• 🔍 Run linter: cargo clippy
• 📝 Update documentation if needed
• ✉️ Use Conventional Commits

🎯 Areas We Need Help

🐛 Bug Fixes Help squash bugs

📚 Documentation Improve our docs

🎨 UI/UX Better user experience

🧪 Testing More test coverage

📝 Development Status & Roadmap

🎉 Current Release: v2.0.0

✅ Completed Features

Core Functionality ✅ Multi-remote synchronization ✅ Smart conflict detection & resolution ✅ Parallel async operations ✅ OS keyring integration ✅ Encrypted credential storage ✅ Interactive CLI/TUI

Advanced Features ✅ Daemon mode with scheduler ✅ Conventional commits wizard ✅ Health check & diagnostics ✅ Comprehensive test suite (58+ tests) ✅ Cross-platform support ✅ Rich documentation

🚀 Roadmap

Version	Features	Status
v2.1.0	TUI Dashboard, Interactive status viewer	🚧 In Progress
v2.2.0	Git LFS support, Submodule sync	📋 Planned
v2.3.0	Workspace management (multi-repo)	📋 Planned
v3.0.0	Webhook server, GUI with Tauri	💭 Future

View Detailed Roadmap

v2.1.0 - Enhanced UI (Q1 2025)

• Full-screen TUI dashboard with ratatui
• Real-time sync monitoring
• Interactive conflict resolution UI
• Customizable themes

v2.2.0 - Advanced Git Features (Q2 2025)

• Git LFS support for large files
• Submodule synchronization
• Partial clone support
• Shallow clone optimization

v2.3.0 - Workspace Management (Q3 2025)

• Multi-repository workspaces
• Bulk operations across repos
• Workspace templates
• Dependency graph visualization

v3.0.0 - Integration & GUI (Q4 2025)

• Webhook server for push events
• REST API for integrations
• Native GUI application with Tauri
• Plugin system

📊 Project Stats

📄 License

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

📚 Examples

Check out the examples/ directory for complete working examples:

• basic_usage.rs - Configuration and remote management
• scheduler_example.rs - Periodic task scheduling
• ui_formatting.rs - Beautiful terminal output

Run examples with:

cargo run --example basic_usage
cargo run --example scheduler_example
cargo run --example ui_formatting

📋 Quick Command Reference

Category	Command	Description
Setup	mg init	Initialize MultiGit in repository
	mg remote add <platform> <user>	Add a new remote platform
Sync	mg sync	Bidirectional sync all remotes
	mg push	Push to all remotes
	mg pull	Pull from primary remote
	mg status	Check sync status
Commits	mg cc	Interactive conventional commit
	mg commit	Alias for cc
Daemon	mg daemon start --interval 1h	Start background sync daemon
	mg daemon status	Check daemon status
	mg daemon stop	Stop daemon
Config	mg config show	View current configuration
	mg config edit	Edit configuration
Health	mg doctor	Run health diagnostics
	mg doctor --fix	Auto-fix common issues
Conflicts	mg conflict list	List all conflicts
	mg conflict resolve	Resolve conflicts interactively

💾 Platform Support Matrix

OS	Architecture	Status	Download
🐧 Linux	x86_64	✅ Supported	Download
🐧 Linux	aarch64 (ARM)	✅ Supported	Download
🍎 macOS	Intel (x86_64)	✅ Supported	Download
🍎 macOS	Apple Silicon (M1/M2)	✅ Supported	Download
🪟 Windows	x86_64	✅ Supported	Download
🪟 Windows	ARM64	🚧 Coming Soon	-

🎯 Use Cases

Open Source Maintainers

• Mirror repositories across GitHub, GitLab, and self-hosted platforms
• Ensure availability if one platform goes down
• Reach wider audiences on different platforms

Enterprise Teams

• Maintain internal GitLab and external GitHub repos in sync
• Backup to multiple locations automatically
• Comply with data residency requirements

Individual Developers

• Keep personal and work accounts synchronized
• Showcase work on multiple platforms for visibility
• Automatic backups with daemon mode

CI/CD Pipelines

• Deploy to multiple hosting platforms from one source
• Test across different Git hosting APIs
• Automated synchronization in workflows

⚖️ Comparison with Alternatives

Feature	MultiGit	Shell Scripts	Git Aliases	Manual Sync
Multi-remote push	✅ One command	⚠️ Custom script	⚠️ Per-remote	❌ Very tedious
Conflict detection	✅ Automatic	❌ Manual	❌ Manual	❌ Manual
Secure credentials	✅ OS keyring	⚠️ Often plain text	⚠️ Git config	⚠️ Various
Progress tracking	✅ Real-time UI	❌ No	❌ No	❌ No
Daemon mode	✅ Built-in	⚠️ Via cron	❌ No	❌ No
Cross-platform	✅ Native binaries	⚠️ Shell dependent	✅ Yes	✅ Yes
API support	✅ All major platforms	⚠️ Manual setup	❌ No	❌ No
Error recovery	✅ Automatic retry	⚠️ Manual	❌ No	❌ No
Conventional commits	✅ Interactive wizard	❌ No	❌ No	⚠️ Manual
Configuration	✅ TOML + CLI	⚠️ Hard-coded	⚠️ Git config	N/A

Why Choose MultiGit?

🎯 Purpose-Built Unlike generic scripts, MultiGit is designed specifically for multi-remote sync with robust error handling and conflict resolution.

🔒 Security First Native OS keyring support means your credentials are never stored in plain text or version control.

⚡ Performance Parallel async operations make syncing multiple remotes faster than sequential git commands.

❓ FAQ

How is this different from git remote add?

Git's native remote support requires you to push/pull each remote individually. MultiGit:

• Pushes to all remotes with one command
• Detects and resolves conflicts automatically
• Manages authentication securely
• Provides daemon mode for automatic syncing
• Offers rich CLI/TUI experience

Does MultiGit work with private repositories?

Yes! MultiGit fully supports private repositories on all platforms. You'll need to provide a Personal Access Token (PAT) with appropriate permissions when adding a remote.

Can I use MultiGit in CI/CD pipelines?

Absolutely! MultiGit is designed for automation:

# Example GitHub Actions workflow
- name: Sync to GitLab
  run: |
    mg init
    mg remote add gitlab ${{ secrets.GITLAB_USERNAME }}
    mg push --to gitlab

How does MultiGit handle merge conflicts?

MultiGit provides three conflict resolution modes:

1. Interactive (default) - Prompts you to resolve conflicts
2. Abort - Stops sync and preserves current state
3. Strategic - Use --strategy ours/theirs to auto-resolve

You can configure the default behavior in your config file.

Is my authentication information secure?

Yes! MultiGit uses:

• OS Keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Age Encryption as fallback
• Zero plain text - Never stores credentials in files

Can I sync only specific branches?

Yes! Use the --branch flag:

mg sync --branch main
mg push --branch develop --to github

What happens if one remote fails?

MultiGit continues syncing to other remotes and reports which operations succeeded/failed. You can review errors and retry with mg sync --retry.

Does MultiGit support Git LFS?

Git LFS support is planned for v2.0.0. Follow issue #XX for updates.

Can I use this with monorepos or workspaces?

Single-repo support is stable in v2.0.0. Workspace management for multiple repositories is coming in a future release.

How do I report bugs or request features?

We love feedback! Please:

• 🐛 Report bugs
• 💡 Request features
• 💬 Join discussions

🙏 Acknowledgments

MultiGit stands on the shoulders of giants:

• 🦀 Built with Rust - Performance and safety
• 📚 Git operations powered by libgit2 - Robust Git internals
• 🎨 Terminal UI with ratatui - Beautiful TUI
• ⚡ Async runtime by Tokio - Blazing fast concurrency
• 🎯 CLI framework with clap - Powerful argument parsing
• 🔐 Secure storage with keyring - OS-native credentials

📧 Support & Community

💬 Get Help

Report Bugs

Request Features

Join Discussions

Read Docs

⭐ Star History

---

🎉 Show Your Support

If MultiGit has helped you, please consider:

⭐ Starring this repository to show your support
🐦 Sharing it with your network
🤝 Contributing to make it even better
☕ Sponsoring the project (coming soon)

---

Made with ❤️ by the TIVerse Team

_{© 2024 TIVerse. Licensed under MIT.}