Skip to main content

polygit

Manage multiple git repos from a single .pgit config file.

uv tool install polygit

Usage

pgit sync      # clone missing repos, fetch all
pgit status    # show repos with uncommitted changes
pgit pull      # pull all repos, auto-stashing local changes
pgit commit    # commit dirty repos without pushing
pgit push      # interactively commit and push dirty repos
pgit merge     # merge a target branch into each repo
pgit repos     # discover drift between .pgit and the filesystem
pgit branches  # show current branch and tracking status per repo

status, pull, push and sync accept --jobs N to control how many repositories are processed in parallel. The default (when omitted) is 8.

pgit sync --jobs 4
pgit status --jobs 1
pgit pull   --only github --dry-run --jobs 4
pgit branches --only github --jobs 4

N must be a positive integer; otherwise the command prints a clear error and exits with status 2.

status, pull and push accept --only <platform> to operate on a single platform (e.g. github) instead of all of them. branches also accepts --only:

pgit status --only gitlab
pgit pull   --only github --dry-run
pgit push   --only gitlab --all
pgit branches --only github

Passing an unknown platform prints an error to stderr and exits 1.

commit

pgit commit commits dirty repos without pushing to remotes:

pgit commit                # prompt for a message per repo (default)
pgit commit --all          # one message for all dirty repos
pgit commit --wip          # auto-commit with "WIP <timestamp>"
pgit commit --dry-run      # list dirty repos that would be committed
pgit commit --wip --json   # emit JSON array of commit results

Note: --json is available with --all or --wip modes.

merge

pgit merge <branch> merges a target branch into the current branch of each cloned repo:

pgit merge main            # merge local 'main' into current branch of each repo
pgit merge main --no-ff    # force a merge commit
pgit merge main --squash   # stage the merged changes without committing
pgit merge main --dry-run  # list repos that would be merged or skipped; changes nothing
pgit merge main --json     # emit JSON array of merge results

pgit merge acts on local branches and does not fetch from remotes — run pgit sync first if you need updated remote branches. Repos with dirty working trees, detached HEADs, or missing target branches are skipped safely with a clear reason.

Configuration

Create a .pgit file in the root directory that contains your repos:

github:
  your-username:
    repo-one:
    repo-two:
  some-org:
    their-repo: {remote: "some-org/their-repo"}

gitlab:
  your-namespace/group:
    private-repo:
    another-repo:

pgit discovers this file by walking up from the current directory — so running pgit status anywhere inside your repos root just works.

Remote overrides

If a repo is cloned to a local path that differs from its remote path, use the remote key:

github:
  my-local-name:
    project: {remote: "upstream-org/project"}

push modes

pgit push                # prompt for a message per repo (default)
pgit push --all          # one message for all dirty repos
pgit push --wip          # auto-commit with "WIP <timestamp>"

dry run

pgit pull --dry-run      # show ahead/behind per repo; changes nothing
pgit push --dry-run      # list dirty repos that would be committed and pushed

pull --dry-run compares against the last fetched state of each upstream, so run pgit sync first for current numbers.

branches

pgit branches shows the current branch and upstream tracking status for each cloned repository:

pgit branches

Output shows one line per repo:

  • ✓ — up to date with upstream
  • ↑ — ahead of upstream (needs a push)
  • ↓ — behind upstream (needs a pull)
  • ⚠ — diverged (both ahead and behind), upstream deleted on the remote, or detached HEAD
  • ~ — branch has no upstream configured (also an empty repo)
✓ github/gschaetz/polygit: main -> origin/main (up to date)
↑ github/gschaetz/tools: main -> origin/main (2 ahead)
↓ github/gschaetz/notes: main -> origin/main (3 behind)
⚠ github/gschaetz/dotfiles: main -> origin/main (3 ahead, 1 behind)
⚠ github/gschaetz/old: feat -> origin/feat (upstream gone)
⚠ github/gschaetz/lib: detached HEAD at a1b2c3d
~ github/gschaetz/experiment: feature-xyz (no upstream)

Like pull --dry-run, this reads the last fetched state of each upstream, so run pgit sync first for current numbers.

Use --only <platform> to filter by platform (e.g. pgit branches --only gitlab). Use --jobs N to control parallelism (default: 8).

branches --json

pgit branches --json   # machine-readable status for every cloned repo

Prints a single JSON array on stdout and nothing else. Unlike status --json, clean repos are included:

[{"platform": "github", "path": "gschaetz/polygit", "branch": "main", "sha": null,
  "upstream": "origin/main", "ahead": 0, "behind": 0, "state": "tracking"}]

state is tracking, none (no upstream), gone (upstream deleted on the remote) or detached. When detached, branch is null and sha holds the short commit hash. upstream is null when there is none.

review

pgit review opens a PR/MR for every cloned repo whose current branch has been pushed and is ahead of the default branch:

pgit review                # prompt per repo (default)
pgit review --all          # one PR title/body for all eligible repos
pgit review --auto         # auto-generate title from branch name, minimal body
pgit review --auto --dry-run
pgit review --base release
pgit review --json

Detection: a repo qualifies when it is tracking the same-named upstream branch (feat/x → origin/feat/x), that branch is ahead of the base, and it is not itself the base branch. Only local refs are read; run pgit sync first if you want current numbers.

The PR base is the remote's default branch (origin/HEAD, falling back to main then master). Pass --base <branch> to override it (e.g. for release branches).

With --auto, PR titles are generated from branch names (feat/auth → feat: auth). With --all, one title/body is prompted for and shared. In interactive mode you get a per-repo prompt with a diff summary and a blank title skips the repo.

review creates PRs via the GitHub/GitLab API when a token is available:

GH_TOKEN=<token> pgit review --auto     # GitHub
GITLAB_TOKEN=<token> pgit review --auto # GitLab

Token scopes: GitHub needs repo; GitLab needs api. Without a token, pgit review prints ready-to-click PR/MR URLs for manual creation.

pgit review --auto --dry-run   # list candidates with planned titles/URLs; creates nothing
pgit review --only github      # review only GitHub repos
pgit review --jobs 4            # parallelism for non-interactive modes (default: 8)

--json (with --all or --auto) prints a single JSON array on stdout and nothing else.

[{"platform": "github", "path": "r", "branch": "feat/x", "status": "created", "url": "https://...", "error": null}]

status is created (PR created via API), manual (no token — URL only), planned (--dry-run), or failed.

Branches must be pushed first — run pgit push before pgit review.

status --json

pgit status --json   # machine-readable list of dirty repos

Prints a single JSON array on stdout and nothing else:

[{"platform": "github", "path": "gschaetz/mousehat", "changed_files": 2}]

changed_files is the number of entries in git status --short. Clean repos are omitted, so the array is empty when there is nothing to commit.

repos — drift detection

pgit repos compares what's actually on disk against your .pgit config and reports:

  • Remote mismatch — repo is at the right path but the git remote differs (e.g. SSH vs HTTPS)
  • Wrong location — remote is tracked in .pgit but cloned to a different directory
  • Untracked — repo on disk not referenced in .pgit at all
  • Missing — in .pgit but not yet cloned (run pgit sync)

It then offers to update .pgit or rename directories interactively.

Migrating from repos.yaml

If you were using the sync.sh predecessor, rename your repos.yaml to .pgit — the format is identical.

Requirements

  • Python 3.10+
  • git

Metadata

Release files for polygit 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polygit 0.9.0
File Size Uploaded Provenance Actions
polygit-0.9.0.tar.gz 130.0 kB Without provenance Details for polygit-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for polygit 0.9.0
File Interpreter ABI Platform Actions
polygit-0.9.0-py3-none-any.whl Python 3 none any Details for polygit-0.9.0-py3-none-any.whl

Total release size: 149.9 kB

Release files / polygit-0.9.0.tar.gz

Download URL polygit-0.9.0.tar.gz
Size 130.0 kB
Tags Source
SHA-256 checksum
How to use checksums
1cf3db37212f246180df5cddbc36767d5283b8e6e309c0f9da7178d84cdf71a0
BLAKE2b-256 checksum
How to use checksums
fb387054d568d63c7261a5c5792d6a7cb86c3f742ccda0621d7550cd46759bcd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / polygit-0.9.0-py3-none-any.whl

Download URL polygit-0.9.0-py3-none-any.whl
Size 20.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cdb554433734c8b037f6655b648bcbc87a8df2c011bb48f60a66860b378a13ae
BLAKE2b-256 checksum
How to use checksums
a68cd447f53e00bbf948ad7af1948b832105166f627397dbd2a44e16bb85f807
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for polygit 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page