How it works
One process takes a whole batch of repositories. A run goes like this:
A run, start to finish
Section titled “A run, start to finish”- Repositories come from the command line, the current checkout, or
with
--all-reposeverything the token can reach. Each one needs apatchula.pklat its root; the rest are skipped. - 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.
- 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. - 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.
- 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.
- 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.
Principles
Section titled “Principles”- 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.
Two ways to run
Section titled “Two ways to run”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.
Tokens
Section titled “Tokens”run and lookup take the first of these that is set and not empty:
PATCHULA_TOKENGITHUB_TOKENGH_TOKEN- the token of a GitHub CLI signed in with
gh auth login, read withgh 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.
Working tree or GitHub
Section titled “Working tree or GitHub”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.
© 2026 Sweepy
