GitHub Repository Sync

GitHub Repository Sync clones and fast-forwards the GitHub repositories listed in one YAML, JSON, or JSON5 configuration file.

Missing repositories are cloned. An existing repository is inspected first and fast-forwarded only when that update is safe.

Features

• Safe repository inspection before synchronisation.
• Automatic cloning of missing repositories.
• Fast-forward updates where safe.
• Protection against repositories with unsafe local states.
• Support for HTTPS and SSH clone protocols.
• YAML, JSON, or JSON5 configuration. A repository that omits clone_protocol uses config.clone_protocol.
• Multiple GitHub organisation support.
• Organisation and repository aliases.
• Relative path organisation aliases for multiple local trees under one clone_path.
• Configurable repository destinations.
• Concurrent clone, update, and status checks (--workers, default: CPU count).
• Ordered per-repository output (alphabetical by GitHub name after load, even when work runs in parallel).
• Rich console output with progress reporting.
• Compact configuration validation.
• Synchronisation plan preview.
• Detailed synchronisation result tables.
• Cross-platform support for macOS, Linux, and Windows.
• Suitable for interactive use, automation, and scheduled execution.

Installation

Install the latest release from PyPI.

pip install lupaxa-github-repo-sync

Verify the installation.

grs --version

or

github-repo-sync --version

The shorter grs command is used throughout the remainder of this document.

Quick Start

Create ~/.github-repo-sync.yaml.

config:
  clone_path: ~/Desktop/GitMaster
  clone_protocol: ssh

organisations:
  - name: the-lupaxa-project
    alias: Lupaxa/TheLupaxaProject
    repositories:
      - name: .github
        alias: github
      - name: workflows
      - name: brand-assets

  - name: lupaxa-gh-toolbox
    alias: Lupaxa/GitHubToolbox
    repositories:
      - name: github-repo-sync

Local layout resolves to clone_path/<organisation-alias>/<repository-alias-or-name>.

Organisation aliases may be a single directory name or a relative path under clone_path (for example Lupaxa/TheLupaxaProject). Repository aliases must remain a single directory name.

Validate the configuration.

grs --validate

Review the synchronisation plan.

grs --plan

Synchronise your repositories.

grs

Command-Line Interface

GitHub Repository Sync uses a simple flat command-line interface.

Repository synchronisation is the default operation. Use --validate or --plan to inspect configuration without modifying repositories. Use --status to audit repository cleanliness without changing working trees, branches, or commits (online mode may fetch remote-tracking refs).

Operating Modes

Command	Description
grs	Synchronise all configured repositories.
grs --validate	Validate the configuration and exit.
grs --plan	Display the resolved synchronisation plan and exit.
grs --status	Check repositories for clean, synchronised state (may fetch tracking refs).

Configuration

Option	Description
-c FILE, --config FILE	Use the specified YAML, JSON, or JSON5 configuration file.

Note: If --config is not specified, the application looks for a default configuration file in the user's home directory. It accepts YAML, JSON, or JSON5 (.github-repo-sync.yaml, then .yml, then .json, then .json5).

Presentation

Option	Description
--no-header	Do not display the application header.
--no-colour, --no-color	Disable coloured console output.
--console-width COLUMNS	Set the console width. Values are clamped to 80-300. The default is 180.
--version	Display the application version.

Status Check

Option	Description
--ignore-clean	With --status, omit fully clean repositories from per-repo output.
--offline	With --status, skip fetching remotes; use existing tracking refs.

Concurrency

Option	Description
--workers N	Process this many repositories at once for sync and --status (default: CPU count). Output is alphabetical by GitHub name after load.

Synchronisation

Option	Description
--recover-rewritten-history	Synchronisation only. Reset a clean local branch onto rewritten remote history. A dirty tree is still skipped.

Rejected with --validate, --plan, or --status. Without this flag, rewritten history is skipped.

Synchronisation Output

These options apply to a synchronisation run. They are ignored for --validate and --plan.

Option	Description
--no-configuration	Do not display the configuration summary.
--no-progress	Disable the repository progress display.
--no-repository-output	Suppress per-repository status messages.
--results-table	Display the detailed repository results table.
--no-failure-table	Do not display the failure table.
--no-summary-table	Do not display the Rich summary table.

Examples

Validate a configuration file.

grs --validate

Validate a different configuration file.

grs --config repositories.yaml --validate

Display the synchronisation plan.

grs --plan

Check repository cleanliness and upstream synchronisation.

grs --status
grs --status --ignore-clean --offline

Synchronise repositories using the default configuration.

grs

Reset clean local clones after a remote history rewrite (git-reset-history).

grs --recover-rewritten-history

Synchronise with a specific number of concurrent workers.

grs --workers 8

Synchronise repositories using an alternative configuration.

grs --config work.yaml

Synchronise repositories without displaying progress.

grs --no-progress

Display the detailed repository results table after synchronisation.

grs --results-table

Run quietly without displaying the configuration summary.

grs --no-configuration --no-progress

Documentation

Online documentation:

https://github-repo-sync.thelupaxaproject.org/

Serve the docs locally:

make init
make python-install-dev
make mkdocs-serve

Development

Install makefile skills, then the development extra:

make init
make python-install-dev

Lint, type-check, and test:

make python-check