Skip to main content

polygit

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

uv tool install polygit
uv tool upgrade polygit    # later, to get the latest release

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 checkout  # switch every repo to a branch, or create it with -b
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.

pgit search <TERM> searches repos by name, path, or remote URL with ranked results:

pgit search polygit              # finds "polygit" and other repos containing the term
pgit search polygit --limit 10   # limit to top 10 matches
pgit search gsch --only github   # only GitHub repos matching "gsch"
pgit search term --json          # output as JSON array with name, path, platform, remote, score

Matching is by prefix, word boundary, or substring of the name, path, or origin remote URL; misspelled terms are not matched. --limit N (default: all) caps the results. --limit 0 returns nothing. --only <platform> filters to one platform before ranking. --jobs N sets parallelism for fetching remotes. TERM is required and case-insensitive; missing or empty term exits with status 2.

log

pgit log lists recent commits across all cloned repos, newest first. It reads local refs only and never fetches, so run pgit sync first to see remote activity:

pgit log                       # the 20 newest commits across all repos
pgit log --limit 50            # change the cap (--limit 0 prints nothing)
pgit log --since 2.weeks       # YYYY-MM-DD, or N.unit such as "2.weeks" / "3 days"
pgit log --author gary         # author name or email contains the text (case-insensitive, literal)
pgit log --only github --json  # JSON array with name, path, platform, hash, author, date, subject

Each line reads <hash> <date> <name> (<author>) <subject>. Commits come from each repo's current HEAD; repos that are not cloned or have no commits are skipped. Equal dates are ordered by repo path, then hash. An invalid --since or --limit exits with status 2. --jobs N sets parallelism.

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.

checkout

pgit checkout <branch> switches every cloned repo to an existing local branch; with -b it creates the branch everywhere:

pgit checkout main                         # switch every repo to local 'main'
pgit checkout -b feat/login                # create 'feat/login' at each repo's current HEAD
pgit checkout -b feat/login --from origin/main   # create it at origin/main instead
pgit checkout -                            # switch every repo back to the branch it was on before
pgit checkout main --dry-run               # list what would happen; changes nothing
pgit checkout -b feat/login --json         # emit JSON array of results

Local work is never overwritten. Switching to an existing branch, or creating from --from, skips repos with uncommitted changes (untracked files count). Plain -b only adds a branch at the current commit, so it works on a dirty repo and your changes come along, as with git checkout -b.

Each repo is reported as switched, created, up-to-date or failed, or skipped with a reason: dirty working tree, detached HEAD, no commits yet, merge/rebase/cherry-pick in progress, branch not found (without -b), branch already exists (with -b), or start point not found. A skip in one repo never stops the others, and re-running is safe — repos already on the branch are reported as up to date.

pgit checkout - switches each repo to the branch it was on before its last switch (git's checkout -), resolved per repo, so a tree mixing main and master can be restored in one command. Running it twice toggles back. A repo with no previous branch (never switched, previous state detached, or the branch was deleted) is skipped as no previous branch. - cannot be combined with -b.

pgit checkout reads local refs only and never fetches, so a branch that exists only on the remote counts as not found; run pgit sync first and use -b <branch> --from origin/<branch> to start from it. --from is only valid with -b.

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.13.2

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.13.2
File Size Uploaded Provenance Actions
polygit-0.13.2.tar.gz 166.7 kB Without provenance Details for polygit-0.13.2.tar.gz

Built distribution (wheel)

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

Total release size: 194.4 kB

Release files / polygit-0.13.2.tar.gz

Download URL polygit-0.13.2.tar.gz
Size 166.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ca3d9da09ee8b335bb7785056580f33a81b288bf7113ca10aa3ccfb92811823b
BLAKE2b-256 checksum
How to use checksums
1330486a9cec35b7fcbcf620afc18e6e4a5d9730a7b390555a7ec5d9f5c97fa4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.13.2-py3-none-any.whl

Download URL polygit-0.13.2-py3-none-any.whl
Size 27.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e1d732c422da006f0766cb3999031453d65b3b793828109937ff53a420e78e6
BLAKE2b-256 checksum
How to use checksums
3c8edd97438f42a337335c1da9a2d348680a62d51b1f5cb3bd7842c5b6c728bb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.13.2

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