The Lupaxa GitHub Toolbox
Part of The Lupaxa Project
lupaxa-github-repo-sync
A command-line application that clones, organises, and safely synchronises large collections of GitHub repositories from a single declarative JSON5 configuration.
Unlike many repository synchronisation tools, it does not assume every repository can be updated automatically. Each repository is inspected before any Git operation, so only repositories in a safe state are modified.
Features
- Safe repository inspection before synchronisation
- Automatic cloning of missing repositories
- Fast-forward updates where safe
- Protection against unsafe local states
- HTTPS and SSH clone protocols
- JSON5 configuration with inherited defaults
- Multiple GitHub organisations, aliases, and destination paths
- Rich console output with progress reporting
- Configuration validation and synchronisation plan preview
- Status check (optional fetch of tracking refs)
- Transient GitHub SSH retries during bulk sync
- Cross-platform: macOS, Linux, and Windows
Installation
From PyPI
pip install lupaxa-github-repo-sync
Verify the installation:
grs --version
or:
github-repo-sync --version
The shorter grs command is used in the examples below.
From source (development mode)
pip install -e ".[dev]"
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
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. Repository aliases must remain a single directory name.
If --config is not specified, the application looks for
~/.github-repo-sync.yaml, then .yml, .json, or .json5. Config files
may be YAML, JSON, or JSON5.
Validate the configuration:
grs --validate
Review the synchronisation plan:
grs --plan
Synchronise your repositories:
grs
Command-Line Interface
Synchronisation is the default operation.
| 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 a clean, synchronised state (may fetch tracking refs). |
Use -c FILE / --config FILE to point at a different JSON5 file.
grs --config work.json5 --validate
grs --status --ignore-clean --offline
grs --recover-rewritten-history
grs --results-table
Documentation
Online documentation:
Serve the docs locally:
mkdocs serve
Then open the local URL printed by MkDocs in your browser.
Development
Clone the repository and install development dependencies:
pip install -e ".[dev]"
Useful make targets:
make test # run tests
make type # type checking (mypy)
make check # lint, type check, and tests
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file lupaxa_github_repo_sync-0.1.1.tar.gz.
File metadata
- Download URL: lupaxa_github_repo_sync-0.1.1.tar.gz
- Upload date:
- Size: 44.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b72f3049380bd7af8f7735707234b957a861137fea905c4cf23a13429614219d
|
|
| MD5 |
a67cb758cf84fdacca76f68b80338b83
|
|
| BLAKE2b-256 |
25d19b284b44bc5d866136a67f9268d17261b8d9d016194670bd1faf2af1933a
|
Provenance
The following attestation bundles were made for lupaxa_github_repo_sync-0.1.1.tar.gz:
Publisher:
generate-release.yml on lupaxa-gh-toolbox/github-repo-sync
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
lupaxa_github_repo_sync-0.1.1.tar.gz -
Subject digest:
b72f3049380bd7af8f7735707234b957a861137fea905c4cf23a13429614219d - Sigstore transparency entry: 2581251833
- Sigstore integration time:
-
Permalink:
lupaxa-gh-toolbox/github-repo-sync@b221c3c8a3bae4ceeeb721185cd48e9eb1b29d05 -
Branch / Tag:
refs/tags/v0.1.1 - Owner: https://github.com/lupaxa-gh-toolbox
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
generate-release.yml@b221c3c8a3bae4ceeeb721185cd48e9eb1b29d05 -
Trigger Event:
push
-
Statement type:
File details
Details for the file lupaxa_github_repo_sync-0.1.1-py3-none-any.whl.
File metadata
- Download URL: lupaxa_github_repo_sync-0.1.1-py3-none-any.whl
- Upload date:
- Size: 42.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8c1df228e9510c7356b5565e4b9eca1939a47178b7cd835aaf7e9c635d53547a
|
|
| MD5 |
114d2d3b366fa34d94d6a27d3ff817c5
|
|
| BLAKE2b-256 |
342e19888b92618d38e990e14372c5b24325af1a7304074c22404713f31a7ae0
|
Provenance
The following attestation bundles were made for lupaxa_github_repo_sync-0.1.1-py3-none-any.whl:
Publisher:
generate-release.yml on lupaxa-gh-toolbox/github-repo-sync
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
lupaxa_github_repo_sync-0.1.1-py3-none-any.whl -
Subject digest:
8c1df228e9510c7356b5565e4b9eca1939a47178b7cd835aaf7e9c635d53547a - Sigstore transparency entry: 2581251838
- Sigstore integration time:
-
Permalink:
lupaxa-gh-toolbox/github-repo-sync@b221c3c8a3bae4ceeeb721185cd48e9eb1b29d05 -
Branch / Tag:
refs/tags/v0.1.1 - Owner: https://github.com/lupaxa-gh-toolbox
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
generate-release.yml@b221c3c8a3bae4ceeeb721185cd48e9eb1b29d05 -
Trigger Event:
push
-
Statement type:
