Metadata-Version: 2.4
Name: github-repository-sync
Version: 0.0.1
Summary: Find and clone all repositories for a GitHub organization.
Author: Kaizten Analytics
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# GitHub Organization Repository Sync

`github-repository-sync.py` finds all repositories for a GitHub organization and checks whether they already exist locally under a recursive search root.

Repositories that are missing locally are cloned into `<root>/<org>/<repo>` by default. The script detects existing local repositories by inspecting their Git remotes, so repositories can be located in nested folders.

The script uses named arguments only. There are no positional arguments.

## Dependencies

- Python 3.10 or newer
- Git
- GitHub CLI (`gh`), recommended for private repositories

Authentication options:

- Use an authenticated GitHub CLI session with `gh auth login`.
- Or set `GITHUB_TOKEN` or `GH_TOKEN`.
- Or pass a token with `--token`.

Without authentication, GitHub only returns public repositories.

## How to use

Run the script with the organization name:

```bash
./github-repository-sync.py --org kaizten
```

By default, the script searches recursively under `~` and clones missing
repositories into `~/kaizten`.

Use `--dry-run` to preview the missing repositories and clone destinations
without cloning anything:

```bash
./github-repository-sync.py --org kaizten --dry-run
```

Use `--root` to search and clone under a different directory:

```bash
./github-repository-sync.py --org kaizten --root /home/christopher
```

Use `--clone-dir` to clone missing repositories somewhere other than
`<root>/<org>`:

```bash
./github-repository-sync.py --org kaizten --clone-dir /home/christopher/repos
```

If a clone destination already exists and is not empty, the script chooses the
next available suffixed directory, such as `repo-1`.

## Examples

Preview missing repositories for `kaizten`:

```bash
./github-repository-sync.py --org kaizten --dry-run
```

Clone all missing repositories for `kaizten` under the default root:

```bash
./github-repository-sync.py --org kaizten
```

Search under `/home/christopher` and clone missing repositories under
`/home/christopher/kaizten`:

```bash
./github-repository-sync.py --org kaizten --root /home/christopher
```

Clone using SSH URLs:

```bash
./github-repository-sync.py --org kaizten --protocol ssh
```

Skip archived repositories:

```bash
./github-repository-sync.py --org kaizten --exclude-archived
```

Use an explicit GitHub token:

```bash
./github-repository-sync.py --org kaizten --token YOUR_GITHUB_TOKEN
```
