# How it works

> What happens during a Count Patchula run, from reading repositories through the GitHub API to publishing verified commits and pull requests.

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

## A run, start to finish

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](https://count-patchula.sweepy.dev/reference/report/) for whatever called the Count. Logs are for people and are never meant to be parsed.

## 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

`patchula run` and `patchula lookup` process one batch with a token you supply and exit. `patchula serve` is a long-running [GitHub App server](https://count-patchula.sweepy.dev/guide/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

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

## Working tree or GitHub

With no repository named, `lookup`, `run --dry-run` and [`tui`](https://count-patchula.sweepy.dev/guide/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.
