CLI Reference¶

GitBridge provides a comprehensive command-line interface for repository synchronization. This reference covers all available commands and options.

Installation¶

After installing GitBridge, the gitbridge command becomes available:

Bash
# Check installation
gitbridge --version

# Get help
gitbridge --help

Commands Overview¶

GitBridge provides several commands for different operations:

Command	Description	Usage
`sync`	Synchronize repository	Main synchronization command
`status`	Check configuration and connectivity	Validate setup
`validate`	Validate configuration file	Test configuration
`init`	Initialize configuration	Create config file

Global Options¶

These options work with all commands:

Bash
--config, -c PATH      Configuration file path
--verbose, -v          Enable verbose output
--quiet, -q            Suppress output
--log-level LEVEL      Set log level (DEBUG, INFO, WARNING, ERROR)
--log-file PATH        Log to file
--no-color             Disable colored output
--help, -h             Show help message
--version              Show version

Command Details¶

sync - Synchronize Repository¶

The main command for synchronizing repositories.

Bash
gitbridge sync [OPTIONS]

Required Options¶

One of these option sets is required:

Option 1: Using configuration file

Bash
gitbridge sync --config config.yaml

Option 2: Using command-line arguments

Bash
gitbridge sync --repo URL --local PATH

All Options¶

Bash
# Repository settings
--repo, -r URL          Repository URL (required without config)
--local, -l PATH        Local directory (required without config)
--ref REF               Branch, tag, or commit (default: main)

# Authentication
--token TOKEN           GitHub personal access token
--username USER         GitHub username (browser method)
--password PASS         GitHub password (browser method)

# Sync options
--method METHOD         Sync method: api, browser, auto
--incremental           Enable incremental sync
--force                 Force full sync
--dry-run               Simulate without changes

# Network options
--proxy URL             HTTP/HTTPS proxy
--no-verify-ssl         Disable SSL verification
--auto-proxy            Auto-detect proxy settings
--auto-cert             Auto-detect certificates

# Performance options
--parallel-downloads N  Number of parallel downloads
--chunk-size SIZE       Download chunk size in bytes
--timeout SECONDS       Operation timeout
--retry-count N         Number of retries

# Browser options
--browser-type TYPE     Browser type: chromium, firefox, webkit
--headless              Run browser in headless mode
--browser-path PATH     Path to browser executable

Examples¶

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

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

# Using configuration file
gitbridge sync --config ~/configs/project.yaml

# Force full sync with verbose output
gitbridge sync --config config.yaml --force -v

# Browser method with specific browser
gitbridge sync --repo https://github.com/user/repo \
             --local ~/projects/repo \
             --method browser \
             --browser-type firefox

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

# Dry run to see what would be synced
gitbridge sync --config config.yaml --dry-run

status - Check Status¶

Check configuration, connectivity, and sync status.

Bash
gitbridge status [OPTIONS]

Options¶

Bash
--config, -c PATH       Configuration file
--show-config           Display resolved configuration
--show-rate-limit       Show API rate limit status
--test-connection       Test repository connectivity
--check-updates         Check for available updates

Examples¶

Bash
# Check basic status
gitbridge status

# Check with specific configuration
gitbridge status --config config.yaml

# Show detailed configuration
gitbridge status --config config.yaml --show-config

# Check API rate limits
gitbridge status --show-rate-limit

# Test connection to repository
gitbridge status --config config.yaml --test-connection

Output Example¶

Text Only

GitBridge Status Report
====================

Configuration:
  ✓ Configuration file loaded: config.yaml
  ✓ Repository: https://github.com/user/repo
  ✓ Local path: /home/user/projects/repo
  ✓ Authentication: Token configured

Network:
  ✓ Proxy: Auto-detected (http://proxy:8080)
  ✓ SSL: Custom certificates loaded
  ✓ Connection: Successful

Sync Status:
  ✓ Last sync: 2025-01-20 10:30:00
  ✓ Method: API
  ✓ Files synced: 1,234
  ✓ Total size: 156.7 MB

API Rate Limit:
  ✓ Remaining: 4,892 / 5,000
  ✓ Reset: 2025-01-20 11:00:00

validate - Validate Configuration¶

Validate configuration file syntax and values.

Bash
gitbridge validate [OPTIONS]

Options¶

Bash
--config, -c PATH       Configuration file to validate
--check-auth            Validate authentication
--check-network         Validate network settings
--check-paths           Validate file paths
--strict                Strict validation mode

Examples¶

Bash
# Validate configuration file
gitbridge validate --config config.yaml

# Full validation with all checks
gitbridge validate --config config.yaml \
                 --check-auth \
                 --check-network \
                 --check-paths

# Strict validation (fail on warnings)
gitbridge validate --config config.yaml --strict

Output Example¶

Text Only

Validating configuration: config.yaml
=====================================

Syntax:
  ✓ YAML syntax valid
  ✓ Required fields present
  ✓ No unknown fields

Values:
  ✓ Repository URL valid
  ✓ Local path accessible
  ✓ Reference format valid

Authentication:
  ✓ Token format valid
  ✓ Token has required scopes
  ✓ Token not expired

Network:
  ✓ Proxy configuration valid
  ✓ SSL certificates found
  ✓ Connection test successful

Result: Configuration is valid

init - Initialize Configuration¶

Create a new configuration file interactively.

Bash
gitbridge init [OPTIONS]

Options¶

Bash
--output, -o PATH       Output file path (default: config.yaml)
--template TYPE         Template type: basic, full, corporate
--non-interactive       Use defaults without prompting
--force                 Overwrite existing file

Examples¶

Bash
# Interactive initialization
gitbridge init

# Create configuration with specific template
gitbridge init --template corporate --output corporate-config.yaml

# Non-interactive with defaults
gitbridge init --non-interactive --output default-config.yaml

# Force overwrite existing
gitbridge init --force --output config.yaml

Interactive Example¶

Text Only

GitBridge Configuration Wizard
============================

Repository URL: https://github.com/user/repo
Local directory [./repo]: ~/projects/repo
Branch/tag/commit [main]: develop

Authentication required? [y/N]: y
GitHub token: **********************

Sync method [api/browser/auto]: api
Enable incremental sync? [Y/n]: y

Configure proxy? [y/N]: y
Proxy URL: http://proxy.company.com:8080

Auto-detect certificates? [y/N]: y

Configuration saved to: config.yaml

Test configuration now? [Y/n]: y
✓ Configuration is valid and working!

Configuration File Usage¶

Loading Configuration¶

Configuration files are loaded in this order:

Specified with --config flag
./config.yaml in current directory
~/.gitbridge/config.yaml in home directory
/etc/gitbridge/config.yaml system-wide

Environment Variable Expansion¶

Configuration files support environment variables:

YAML
auth:
  token: ${GITHUB_TOKEN}

local:
  path: ${HOME}/projects/${PROJECT_NAME}

Multiple Configurations¶

Use different configurations for different repositories:

Bash
# Personal projects
gitbridge sync --config ~/.gitbridge/personal.yaml

# Work projects
gitbridge sync --config ~/.gitbridge/work.yaml

# Open source contributions
gitbridge sync --config ~/.gitbridge/opensource.yaml

Exit Codes¶

GitBridge uses standard exit codes:

Code	Meaning	Description
0	Success	Operation completed successfully
1	General error	Unspecified error occurred
2	Configuration error	Invalid configuration
3	Authentication error	Authentication failed
4	Network error	Network or connectivity issue
5	Repository error	Repository access problem
6	File system error	Local file system issue
7	Rate limit error	API rate limit exceeded
8	Browser error	Browser automation failed

Shell Completion¶

Enable shell completion for better CLI experience:

Bash¶

Bash
# Add to ~/.bashrc
eval "$(_GITSYNC_COMPLETE=bash_source gitbridge)"

Zsh¶

Bash
# Add to ~/.zshrc
eval "$(_GITSYNC_COMPLETE=zsh_source gitbridge)"

Fish¶

Fish
# Add to ~/.config/fish/config.fish
eval "$(_GITSYNC_COMPLETE=fish_source gitbridge)"

Advanced Usage¶

Scripting¶

Use GitBridge in scripts:

Bash
#!/bin/bash

# Sync with error handling
if gitbridge sync --config config.yaml --quiet; then
    echo "Sync successful"
else
    exit_code=$?
    case $exit_code in
        3) echo "Authentication failed" ;;
        4) echo "Network error" ;;
        7) echo "Rate limit exceeded" ;;
        *) echo "Sync failed with code: $exit_code" ;;
    esac
    exit $exit_code
fi

Cron Jobs¶

Schedule regular syncs:

Bash
# Add to crontab
# Sync every hour
0 * * * * /usr/local/bin/gitbridge sync --config /home/user/.gitbridge/config.yaml --quiet

# Sync every day at 2 AM
0 2 * * * /usr/local/bin/gitbridge sync --config /home/user/.gitbridge/config.yaml --log-file /var/log/gitbridge.log

Docker Usage¶

Run GitBridge in Docker:

Bash
# Using configuration file
docker run -v $(pwd)/config.yaml:/config.yaml \
           -v $(pwd)/repo:/repo \
           gitbridge:latest \
           sync --config /config.yaml

# With environment variables
docker run -e GITHUB_TOKEN=$GITHUB_TOKEN \
           -v $(pwd)/repo:/repo \
           gitbridge:latest \
           sync --repo https://github.com/user/repo --local /repo

Troubleshooting¶

Common Issues¶

Command not found:

Bash
# Check installation
pip show gitbridge

# Ensure pip bin directory is in PATH
export PATH="$PATH:$(python -m site --user-base)/bin"

Permission denied:

Bash
# Check file permissions
ls -la ~/.gitbridge/

# Fix permissions
chmod 600 ~/.gitbridge/config.yaml

SSL certificate errors:

Bash
# Disable SSL verification (not recommended)
gitbridge sync --config config.yaml --no-verify-ssl

# Or use custom certificates
gitbridge sync --config config.yaml --auto-cert

Debug Mode¶

Enable debug output for troubleshooting:

Bash
# Maximum verbosity
gitbridge sync --config config.yaml -vvv --log-level DEBUG

# Save debug output to file
gitbridge sync --config config.yaml --log-level DEBUG --log-file debug.log

CLI Reference¶

Installation¶

Commands Overview¶

Global Options¶

Command Details¶

sync - Synchronize Repository¶

Required Options¶

All Options¶

Examples¶

status - Check Status¶

Options¶

Examples¶

Output Example¶

validate - Validate Configuration¶

Options¶

Examples¶

Output Example¶

init - Initialize Configuration¶

Options¶

Examples¶

Interactive Example¶

Configuration File Usage¶

Loading Configuration¶

Environment Variable Expansion¶

Multiple Configurations¶

Exit Codes¶

Shell Completion¶

Bash¶

Zsh¶

Fish¶

Advanced Usage¶

Scripting¶

Cron Jobs¶

Docker Usage¶

Troubleshooting¶

Common Issues¶

Debug Mode¶

Next Steps¶