Quick Start Guide¶

Get up and running with GitBridge in under 5 minutes! This guide will walk you through syncing your first repository.

Prerequisites¶

Before starting, ensure you have:

• GitBridge installed (Installation Guide)
• Network access to GitHub.com
• A target directory for the synced repository

Step 1: Basic Repository Sync¶

Let's start by syncing a public repository:

1

gitbridge sync --repo https://github.com/python/cpython --local ~/projects/cpython

What happens:

1. GitBridge connects to the GitHub repository
2. Downloads the entire repository structure
3. Saves files to ~/projects/cpython
4. Creates .gitbridge/metadata.json for tracking

1
2
3

✓ Repository synced successfully
Files: 4,521 downloaded, 0 skipped
Time: 2m 34s

Step 2: Incremental Updates¶

Run the same command again:

1

gitbridge sync --repo https://github.com/python/cpython --local ~/projects/cpython

Notice how it's much faster! GitBridge only downloads changed files:

1
2
3

✓ Repository synced successfully  
Files: 3 updated, 4,518 unchanged
Time: 5s

Step 3: Using Configuration Files¶

Instead of typing long commands, create a configuration file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

repository:
  url: https://github.com/python/cpython
  branch: main

local:
  path: ~/projects/cpython

sync:
  incremental: true
  method: api

1
2

# Now just run:
gitbridge sync --config config.yaml

Step 4: Syncing Private Repositories¶

For private repositories, you need authentication:

Generate a GitHub Token¶

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Click "Generate new token (classic)"
3. Select scopes: repo (full control of private repositories)
4. Copy the generated token

Use the Token¶

1
2
3
4

gitbridge sync \
  --repo https://github.com/yourusername/private-repo \
  --local ~/projects/private-repo \
  --token ghp_YourGitHubTokenHere

1
2
3
4

export GITHUB_TOKEN=ghp_YourGitHubTokenHere
gitbridge sync \
  --repo https://github.com/yourusername/private-repo \
  --local ~/projects/private-repo

1
2
3
4
5
6
7
8

repository:
  url: https://github.com/yourusername/private-repo

local:
  path: ~/projects/private-repo

auth:
  token: ${GITHUB_TOKEN}  # Read from environment

Step 5: Specific Branch or Tag¶

Sync a specific branch, tag, or commit:

1
2
3
4
5
6
7
8

# Sync a branch
gitbridge sync --repo https://github.com/user/repo --local ~/repo --ref develop

# Sync a tag
gitbridge sync --repo https://github.com/user/repo --local ~/repo --ref v1.0.0

# Sync a specific commit
gitbridge sync --repo https://github.com/user/repo --local ~/repo --ref abc123def

Common Use Cases¶

Corporate Environment with Proxy¶

If you're behind a corporate proxy:

1
2
3
4
5

# Auto-detect proxy from system
gitbridge sync --config config.yaml --auto-proxy

# Or specify manually
gitbridge sync --config config.yaml --proxy http://proxy.company.com:8080

When API Access is Blocked¶

Use browser automation as fallback:

1

gitbridge sync --repo https://github.com/user/repo --local ~/repo --method browser

Check Repository Status¶

Before syncing, check the repository status:

1

gitbridge status --config config.yaml

Output:

1
2
3
4
5
6

Repository: https://github.com/python/cpython
Branch: main
Latest commit: abc123def (2 hours ago)
Local path: ~/projects/cpython
Last sync: 2025-01-15 10:30:00
Status: 42 files outdated

Quick Reference¶

Essential Commands¶

Key Options¶

Tips and Tricks¶

1
2

sync:
  incremental: true

1
2

gitbridge sync --config work-repo.yaml
gitbridge sync --config personal-repo.yaml

1
2

# Sync every hour
0 * * * * /usr/bin/gitbridge sync --config /home/user/config.yaml

1

gitbridge sync --config config.yaml --verbose

What's Next?¶

Now that you've mastered the basics:

• 📖 Read the User Guide for advanced features
• 🔧 Learn about Configuration options
• 🔐 Set up Authentication properly
• 🏢 Configure for Corporate Environments
• 🤖 Explore CLI Commands in detail

Need Help?¶

If something doesn't work:

1. Check the Troubleshooting Guide
2. Run with --verbose for detailed error messages
3. Check your network access to GitHub
4. Create an issue for support