holocron-sync 0.1.0

Holocron: The Ultimate Git Mirroring Tool

Holocron

The "Ultimate" Git Mirroring Tool

          /\
         /  \
        / /\ \
       / /  \ \
      / /    \ \
     /_/______\_\
     \ \      / /
      \ \    / /
       \ \  / /
        \ \/ /
         \  /
          \/

Holocron is a powerful Python application designed to mirror your GitHub repositories to a local directory or a self-hosted GitLab instance. It supports parallel syncing, continuous watch mode, and local-only backups (no GitLab required).

Features

• Parallel Syncing: Sync multiple repositories concurrently for maximum speed.
• Continuous Watch Mode: Polls for changes and syncs only when necessary (smart redundancy checks).
• Two-Way Mirroring: Creates a bare mirror (.git folder) for safety AND an optional checkout for visibility.
• Dockerized: Runs as a lightweight container.
• Backup Level:
  • Full: GitHub -> Local -> GitLab
  • Backup-Only: GitHub -> Local (No GitLab token needed)

Quick Start

1. Docker (Recommended)

docker-compose up -d --build

This starts Holocron in watch mode.

2. Manual Run

# Install dependencies
uv sync

# Run a one-time backup of all your repos locally (visible files)
export GITHUB_TOKEN=your_token
uv run python src/holocron.py --backup-only --checkout --concurrency 10

Configuration

Holocron uses environment variables for secrets:

Variable	Description	Required
GITHUB_TOKEN	Your GitHub Personal Access Token (repo scope)	Yes
GITLAB_TOKEN	Your GitLab Personal Access Token (api scope)	No (if --backup-only)
GITLAB_API_URL	URL to your GitLab API (default: http://gitlab.local/api/v4)	No

Command Line Arguments

Flag	Default	Description
--watch	False	Run continuously in a loop
--interval	60	Seconds to sleep between checks in watch mode
--window	60	Sync only repos pushed within the last N minutes
--backup-only	False	Mirror locally only, do not push to GitLab
--checkout	False	Create a visible working directory alongside the mirror
--concurrency	5	Number of parallel sync threads
--storage	./mirror-data	Directory to store repositories
--dry-run	False	Print what would happen without doing it
--verbose	False	Enable detailed debug logging

Development

Run tests with coverage:

uv run pytest --cov=src