repoclone

Clone, update and report on every repository in a GitLab group or GitHub organisation — in parallel, safely, and repeatably.

Point it at a namespace and it mirrors the whole tree onto your laptop. Run it again next week and it fast-forwards what changed, leaves your local work alone, and tells you what happened.

$ repoclone clone platform/tooling --token glpat-xxxx
gitlab platform/tooling → /Users/you/src/work
   cloned  platform/tooling/api
   cloned  platform/tooling/cli
  updated  platform/tooling/docs
  skipped  platform/tooling/legacy (local changes, left alone)

42 repositories: 30 cloned, 9 updated, 2 unchanged, 1 skipped

Install

Requires Python 3.11+ and git on your PATH.

# recommended — isolated install, command on your PATH
uv tool install repoclone-cli

# or with pipx
pipx install repoclone-cli

# or plain pip
pip install repoclone-cli

# or straight from the repository, before a release is cut
uv tool install git+https://github.com/devops-monk/repoclone-cli

The package is published as repoclone-cli and installs a command called repoclone — the name repoclone was already taken on PyPI by an unrelated project.

Check everything is wired up:

repoclone check --token glpat-xxxx

New to it? Follow the step-by-step first test — the first four steps cannot touch your disk.

Quick start

# GitLab group (path or numeric id), token on the command line
repoclone clone platform/tooling --token glpat-xxxx --dest ~/src/work

# GitHub organisation
repoclone clone kubernetes --provider github --token ghp_xxxx --dest ~/src/oss

# see what would happen first
repoclone clone platform/tooling --token glpat-xxxx --dry-run

Run the same command again tomorrow. Existing clones are pulled up to date, anything new is cloned, and repositories with uncommitted work are left alone. That is the default; --sync says it explicitly if you prefer it spelled out in a script:

repoclone clone platform/tooling --token glpat-xxxx --sync

Private / self-hosted instances

Pass your own domain with --host — this is the common case for company GitLab and GitHub Enterprise, and everything else works identically:

# self-hosted GitLab on your own domain
repoclone clone platform/tooling \
  --host https://git.tech.example.com \
  --token glpat-xxxx \
  --dest ~/src/work

# GitHub Enterprise Server
repoclone clone platform \
  --provider github \
  --host https://github.example.com \
  --token ghp_xxxx \
  --dest ~/src/work

# internal host with a self-signed certificate
repoclone clone platform/tooling --host https://git.internal.example.com --token $T --insecure

The API path is derived for you (/api/v4 for GitLab, /api/v3 for GitHub Enterprise) — give it the plain domain. Without --host the public gitlab.com / github.com is used. Put the host in a profile once and you never type it again.

Re-running is the normal case: repositories already on disk are fast-forwarded, new ones are cloned, and anything you have edited locally is left untouched.

Commands

Every command supports -h/--help. Passing an unknown option or a bad value prints the full help for that command, so you never have to guess.

Common options

Useful combinations

# a fast, space-efficient mirror for code search
repoclone clone platform --token $T --blobless -j 16

# only the services, skipping anything archived-looking
repoclone clone platform --token $T --include '/services/' --exclude '^platform/old-'

# refresh remote refs without ever touching working trees
repoclone clone platform --token $T --update fetch

# what have I got locally that is going stale?
repoclone report --stale-days 180 --output table

# daily refresh: pull everything, clone anything new
repoclone clone platform --token $T --sync

# include forks and archived repositories in a full audit
repoclone clone platform --token $T --forks --archived

# fail fast on a stuck repository instead of waiting ten minutes
repoclone clone platform --token $T --timeout 120

Tokens

Pass the token on the command line with --token, which is what most people do:

repoclone clone platform/tooling --token glpat-xxxx

If you would rather not have it in shell history, any of these also work — in this order of precedence:

1. --token
2. REPOCLONE_TOKEN
3. token_env in your profile (points at a variable of your choosing)
4. GITLAB_TOKEN / GITHUB_TOKEN
5. token_cmd in your profile, e.g. op read op://Private/GitLab/token

A read-only scope is enough. Over https, the token is used for the clone and then stripped from the saved remote, so it never lands in .git/config. Tokens are redacted from error output.

Configuration profiles

Typing the same flags every day gets old. repoclone config init writes ~/.config/repoclone/config.toml:

default_profile = "work"

[profiles.work]
provider = "gitlab"
host = "https://gitlab.example.com"
namespaces = ["platform/tooling"]
dest = "~/src/work"
protocol = "ssh"
concurrency = 8
token_env = "GITLAB_TOKEN"

[profiles.oss]
provider = "github"
namespaces = ["kubernetes"]
dest = "~/src/oss"
protocol = "https"

Then:

repoclone clone                 # uses the default profile
repoclone clone --profile oss   # uses the oss profile
repoclone config show           # what would apply right now

Precedence: command-line flags → environment variables → profile → built-in defaults. A flag you do not pass never overwrites your profile.

How it decides what to do

repoclone never runs git merge unless it can fast-forward, never force-updates, and never deletes anything. --prune only reports orphans — removing them stays your decision.

Output formats

list and report accept --output table|json|csv, so results pipe into other tools:

repoclone list platform --token $T --output json | jq -r '.[].repository'
repoclone report --output csv > inventory.csv

Exit codes

Documentation

• docs/usage.md — task-by-task guide with worked examples
  • Step-by-step first test — start here if you have just installed it
• docs/architecture.md — how the pieces fit together
• CONTRIBUTING.md — how to add a command, a provider or an output format
• docs/releasing.md — publishing to PyPI, versioning, trusted publishing

Licence

MIT.