Metadata-Version: 2.4
Name: lupaxa-github-repo-sync
Version: 0.1.6
Summary: Safely clone and update large collections of GitHub repositories from a declarative JSON5 configuration.
Author: The Lupaxa Project
Maintainer: The Lupaxa Project
License-Expression: MIT
Project-URL: Homepage, https://github.com/lupaxa-gh-toolbox/github-repo-sync
Project-URL: Documentation, https://github-repo-sync.thelupaxaproject.org/
Project-URL: Repository, https://github.com/lupaxa-gh-toolbox/github-repo-sync
Project-URL: Issues, https://github.com/lupaxa-gh-toolbox/github-repo-sync/issues
Keywords: automation,developer-tools,git,github,github-automation,repository,repository-management,synchronisation,synchronization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: GitPython<4.0.0,>=3.1.44
Requires-Dist: json5<1.0.0,>=0.12.0
Requires-Dist: PyYAML<7.0.0,>=6.0.2
Requires-Dist: rich<15.0.0,>=14.0.0
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.2; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.17.0; extra == "dev"
Requires-Dist: pre-commit<5.0.0,>=4.2.0; extra == "dev"
Requires-Dist: pytest<9.0.0,>=8.4.0; extra == "dev"
Requires-Dist: pytest-cov<7.0.0,>=6.2.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.12.0; extra == "dev"
Requires-Dist: twine<7.0.0,>=6.1.0; extra == "dev"
Requires-Dist: types-setuptools<81.0.0,>=80.1.6; extra == "dev"
Requires-Dist: mkdocs==1.6.1; extra == "dev"
Requires-Dist: mkdocs-material==9.7.7; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Dynamic: license-file

<p align="center">
    <a href="https://github.com/lupaxa-gh-toolbox">
        <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/gh-toolbox/readme-logo.png" alt="Organisation Logo" />
    </a>
</p>

<h1 align="center">GitHub Repository Sync</h1>

**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.

```bash
pip install lupaxa-github-repo-sync
```

Verify the installation.

```bash
grs --version
```

or

```bash
github-repo-sync --version
```

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

## Quick Start

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

```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.

```bash
grs --validate
```

Review the synchronisation plan.

```bash
grs --plan
```

Synchronise your repositories.

```bash
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.

```bash
grs --validate
```

Validate a different configuration file.

```bash
grs --config repositories.yaml --validate
```

Display the synchronisation plan.

```bash
grs --plan
```

Check repository cleanliness and upstream synchronisation.

```bash
grs --status
grs --status --ignore-clean --offline
```

Synchronise repositories using the default configuration.

```bash
grs
```

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

```bash
grs --recover-rewritten-history
```

Synchronise with a specific number of concurrent workers.

```bash
grs --workers 8
```

Synchronise repositories using an alternative configuration.

```bash
grs --config work.yaml
```

Synchronise repositories without displaying progress.

```bash
grs --no-progress
```

Display the detailed repository results table after synchronisation.

```bash
grs --results-table
```

Run quietly without displaying the configuration summary.

```bash
grs --no-configuration --no-progress
```

## Documentation

Online documentation:

[https://github-repo-sync.thelupaxaproject.org/](https://github-repo-sync.thelupaxaproject.org/)

Serve the docs locally:

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

## Development

Install makefile skills, then the development extra:

```bash
make init
make python-install-dev
```

Lint, type-check, and test:

```bash
make python-check
```

<a href="https://github.com/the-lupaxa-project">
    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
</a>
