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.

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.8.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.8.0
File Size Uploaded Provenance Actions
polygit-0.8.0.tar.gz 114.5 kB Without provenance Details for polygit-0.8.0.tar.gz

Built distribution (wheel)

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

Total release size: 130.5 kB

Release files / polygit-0.8.0.tar.gz

Download URL polygit-0.8.0.tar.gz
Size 114.5 kB
Tags Source
SHA-256 checksum
How to use checksums
02196452b31b702a725cdb9fac3a06f9c10e77b42598507315405dc84db2a7d1
BLAKE2b-256 checksum
How to use checksums
7d379b847146e867a82ba0b680e47d7de68c8be31af7db6d45d73544045159b4
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.8.0-py3-none-any.whl

Download URL polygit-0.8.0-py3-none-any.whl
Size 16.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ced83e653631ea6917bf098174a14f919f959fcd46b5f76a276847c58510d64b
BLAKE2b-256 checksum
How to use checksums
f359adbe51d9fc349e05764b747619bc96c9fa1a9b9c046d625cfb481fb91cae
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.8.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