GitBridge - GitHub Repository Synchronization Tool¶

Overview¶

GitBridge is a powerful Python tool designed to synchronize GitHub repositories to local folders when direct git access is blocked. It provides two synchronization methods - GitHub API and browser automation - ensuring you can always access your code, even in restricted network environments.

Key Features¶

Quick Example¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Basic sync
gitbridge sync --repo https://github.com/user/repo --local ~/projects/repo

# With authentication
gitbridge sync --repo https://github.com/user/repo \
             --local ~/projects/repo \
             --token YOUR_GITHUB_TOKEN

# Corporate environment with auto-detection
gitbridge sync --config config.yaml --auto-proxy --auto-cert

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

repository:
  url: https://github.com/username/repo
  branch: main

local:
  path: ~/projects/repo

auth:
  token: ${GITHUB_TOKEN}  # From environment variable

sync:
  method: api
  incremental: true

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from gitbridge import GitHubAPISync

sync = GitHubAPISync(
    repo_url="https://github.com/user/repo",
    local_path="/path/to/local",
    token="YOUR_GITHUB_TOKEN"
)

# Perform sync
changes = sync.sync()
print(f"Synced {changes['updated']} files")

Why GitBridge?¶

The Problem¶

Many corporate and institutional networks block direct git access (SSH and HTTPS) for security reasons, making it impossible to use standard git commands like git clone or git pull. However, browser access to GitHub often remains available.

The Solution¶

GitBridge provides two robust methods to synchronize repositories:

1. API Method: Uses GitHub's REST API over HTTPS (same as browser traffic)
2. Browser Method: Automates a real browser to download files when API is blocked

Both methods support:

• Incremental updates (only changed files)
• Branch and tag selection
• Progress tracking
• Corporate proxy support
• SSL certificate handling

Installation¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Using pip
pip install gitbridge

# Using uv (recommended)
uv pip install gitbridge

# From source
git clone https://github.com/nevedomski/gitbridge
cd gitbridge
uv pip install -e .

Full Installation Guide

Documentation Structure¶

System Requirements¶

• Python: 3.10 or higher (3.11+ recommended)
• Operating System: Windows, macOS, or Linux
• For Browser Mode: Chrome/Chromium/Firefox/Edge browser
• Network: HTTPS access to GitHub (browser access)

Support¶

• GitHub Issues
• Documentation
• Email Support

License¶

GitBridge is open source software licensed under the MIT License.