Skip to content

How it works

One process takes a whole batch of repositories. A run goes like this:

  1. Repositories come from the command line, the current checkout, or with --all-repos everything the token can reach. Each one needs a patchula.pkl at its root; the rest are skipped.
  2. Files are read through the GitHub API at the default branch’s commit, or from the working tree when no repository is named. No clone. If neither the commit nor the resolved config changed since the last run, the previous extraction is reused.
  3. Every dependency’s source is queried once per batch, however many repositories share it. Responses are stored with their ETag or Last-Modified validators, so a warm lookup is mostly 304 Not Modified. Release and tag histories are read newest first and stop at the first release already known.
  4. Rules pick the target for each dependency: the newest release allowed by its version policy, release-age wait, schedule window and PR limits. Updates that share a group, or a lockfile, land on one branch.
  5. For each branch the Count edits the exact bytes of each declaration, runs the lockfile tool in a scratch tree when one is needed, and creates a single commit through the API, which GitHub signs. An atomic ref lease guards the branch, and branches holding anyone else’s commits are left alone.
  6. A receipt records what was written. On the next run a matching receipt skips verification, tooling and PR reconciliation. An unchanged repository costs one GraphQL inventory query on the write side.

The result is a versioned JSON report for whatever called the Count. Logs are for people and are never meant to be parsed.

  • Batch-native: repositories run concurrently (eight by default) behind one GitHub rate-limit governor.
  • Conditional everywhere: every GET sends a validator when it has one, and GitHub does not count 304 responses against the primary rate limit.
  • No clone unless a lockfile tool needs a working tree. Then a persistent partial clone (blob:none) supplies only the files that tool reads.
  • Fail loudly: unknown config fields, unknown managers and unsupported lockfile formats are errors, never silent skips. A file that does not parse at all is skipped with a warning, and warnings stop branch cleanup so nothing is closed by mistake.

patchula run and patchula lookup process one batch with a token you supply and exit. patchula serve is a long-running GitHub App server: it verifies webhooks, keeps a deduplicated queue, sweeps on a cron schedule and keeps every cache warm between batches. Both use the same engine, so a batch behaves the same however it started.

run and lookup take the first of these that is set and not empty:

  1. PATCHULA_TOKEN
  2. GITHUB_TOKEN
  3. GH_TOKEN
  4. the token of a GitHub CLI signed in with gh auth login, read with gh auth token --hostname github.com

The Count only talks to github.com, so he asks gh for that host whatever its default host is. If gh is not installed, is not signed in, fails, or does not answer within 10 seconds, he carries on without it and the error names all four sources. The token is never printed or logged.

With no repository named, lookup, run --dry-run and tui read the working tree in the current directory, uncommitted changes included, with the same config discovery and file selection as a repository read from GitHub. Like a push, it carries tracked files and untracked ones Git does not ignore, so anything .gitignore, .git/info/exclude or the global excludes file ignores, such as node_modules/, is skipped. A directory that is not a Git checkout is read whole, except .git, and the config’s exclude applies either way. To read another checkout, cd there first. The report names the checkout local/<directory name>; a directory name that is not a valid repository name — it holds a space, @ or non-ASCII characters, say — is reported as local/ followed by the SHA-256 of the name instead. Lookups still reach the registries. lookup and run --dry-run write nothing, and tui writes only the updates you select.

A real run opens pull requests from what GitHub has, so with no repository named it runs the checkout’s GitHub repository: its origin remote, or its only remote. It refuses a working tree with uncommitted or untracked files, or a HEAD other than the remote’s default branch.