ply
Zero-dependency git smart-HTTP client that edits one file in a remote repo in O(1) memory and pushes the change as a delta. Runs anywhere with fetch, CompressionStream, crypto.getRandomValues and Uint8Array (Node ≥ 20, Workers, browsers behind a CORS proxy).
Every byte and every roundtrip is recorded as an OTLP span. The test suite is a property/fuzz harness that uses real git as the oracle and the spans as the coverage map that steers generation.
The hosted HTTP API and the public repository viewer live in ply-web (the Cloudflare Worker ply). This repository is the git client.
Install
ply is not on npm (the npm name ply belongs to another package). Install it from GitHub; npm builds dist/ on install:
npm install github:ivarvong/ply # the default branch, as of now
npm install github:ivarvong/ply#<commit-sha> # recommended: pin a commit for reproducible buildsIt installs as ply, so imports read from 'ply' and from 'ply/<subpath>' (ply/edit, ply/read, ply/tree, ply/checkout-node, …). Types ship with it (dist/*.d.ts); JavaScript and TypeScript use the same calls.
ply is ESM-only: there is no CommonJS build and no require export condition. The Node floor is 20 (engines.node is >=20; all 19 entry points import on 20.17.0). From a CommonJS file, await import('ply') works on every supported Node. require('ply') depends on the Node version: it works where Node loads an ES module with require() by default, which is Node 20.19.0 and later on the 20 line (Node's changelog for 20.19.0: "require(esm) is now enabled by default"; measured on 20.19.0 and 20.20.2) and Node 22.12 and later (measured on 22.15.0, 24.2.0, 24.16.0, 24.18.0 and 25.2.1). Before that it throws ERR_REQUIRE_ESM: on Node 20.18 and earlier (measured on 20.17.0, 20.18.0 and 20.18.3) and on Node 22 before 22.12 (Node's documented boundary, not measured here). CI job pack packs the tarball, installs it with --ignore-scripts into an empty project, and checks every import and this require() behaviour under Node 20, 22 and 24 (npm run check:pack, test/pack-install.test.js).
The git install above needs the package manager to run ply's prepare script: dist/ is not in git, and prepare builds it (npm first installs ply's dev tools in a temporary clone). Not every package manager runs it, and none of them fails when it does not run. Measured in an empty project at commit 77048fb:
| package manager | default | --ignore-scripts |
|---|---|---|
| npm 11.16.0 | builds dist/; imports work | exits 0, no dist/ |
| pnpm 8.15.9 | builds dist/; imports work; installs the whole repository (7.8 MB), where npm installs files only (1.7 MB) | exits 0 with the warning has to be built but the build scripts were ignored, no dist/ |
| yarn 1.22.22 | exits 0 without running prepare, no dist/ | exits 0, no dist/ |
| bun 1.2.18 | exits 0 with Blocked 1 postinstall, no dist/; bun pm trust ply then fails (tsc: command not found) | exits 0, no dist/ |
With no dist/, every import fails with ERR_MODULE_NOT_FOUND. So the git install works with npm and with pnpm 8, scripts on; it does not work with yarn 1 or bun 1.2, or with scripts off. pnpm, yarn and bun were given github:ivarvong/ply#<sha>, npm a local clone of the same commit (git+file://); pnpm 9 and later and yarn 2 and later were not measured. The packed tarball contains dist/ and installs with scripts off (measured with npm; CI job pack). CI uploads it as the workflow artifact ply-tarball, which needs a GitHub login and expires; there is no install URL for it yet.
Beta
ply is pre-1.0 (0.2.0). The API can change between commits without a deprecation period, and there are no tagged releases yet: pin a commit sha, read the commit log before moving the pin, and let your type checker or tests catch a changed signature. Span names and attributes are a stated contract (see Telemetry contract).
Requirements
- Runtime: Node ≥ 20, Cloudflare Workers, or any runtime with
fetch,CompressionStream/DecompressionStream,crypto.getRandomValuesandUint8Array(a browser works behind a CORS proxy).ply/tree-node,ply/checkout-nodeandply/repo-nodeare Node only (node:fs). - TypeScript (optional): the shipped declarations compile with
skipLibCheck: falseunderlib: ["ES2022"]with@types/node20, 22 or 24, under theDOMlib, and under@cloudflare/workers-types.npm run check:distandtest/dist-types.test.jscompile each of those five consumers (pinned:@types/node20.19.43, 22.20.5 and 24.19.2,@cloudflare/workers-types5.20260916.1, TypeScript 7.0.2,nodenextresolution) and fail when a type package is missing; none is skipped. They need the web globals one of those provides (ReadableStream,Response,AbortSignal,URL);lib: ["ES2022"]with no types package is not enough. - A git smart-HTTP server: GitHub, GitLab, Gitea/Forgejo, Cloudflare Artifacts, or self-hosted
git http-backend(http.receivepack trueto push; nothing else). A stock git server works: withoutuploadpack.allowFilterits advertisement has nofilter, and ply learns that from the server (quirks.treeFilter = 'none', learned once per remote: see the Artifacts notes below) and fetches unfiltered: the same results, with more bytes per read. The quick start below runs on both. ply speaks protocol v2 for reads and receive-pack for pushes; SHA-1 repositories only. A server that answers only v0/v1 is refused asunsupported(what: 'protocol version') on the first ls-refs. - Auth, per call in
opts.auth:{ token }(HTTP Basic with userx-access-token, which GitHub tokens use),{ token, user }(a host that wants a username: GitLaboauth2for an OAuth token, your Gitea/Forgejo user),{ bearer }, or{ header }(anAuthorizationvalue sent as is). Or userinfo in the URL (https://<token>@host/…), sent as git sends it. Noauthand no userinfo: anonymous. Credentials never reach a span or an error message; redirects are not followed. Details in "Credentials" under More detail.
What ply does not do: create or delete repositories (that is the host's API, or git init --bare on your server: ply needs one to exist, empty or not); SSH transport (removed; HTTPS only); Git LFS content (an LFS pointer is refused by edits, see Guards); pull requests, issues or any other host API object; a working tree or index (there is no clone: every call reads what it needs over the wire).
Quick start: a repo end to end
Every call takes (url, spec, opts) (opts is optional: auth, limits, signal, and tracer, a new Tracer({ exporter }) to export spans; without one they are dropped), and returns a Result: { ok: true, value } or { ok: false, error }, never a throw. The blocks below run in order against one repository that starts empty (they are executed as written, against git http-backend with and without uploadpack.allowFilter, by test/e2e-customer.test.js, and type-checked as TypeScript by test/types/readme.typetest.ts). A ref that is written is a full name (refs/heads/main; a tag's name may be short); a ref that is only read (readCommit's ref, createBranch's from, createTag's target) may also be a short name (main, v1.3.0) or a commit id.
// quick-start: setup
const url = 'https://git.example.com/acme/site.git'; // an existing repository, empty or not
const opts = { auth: { token: process.env['GIT_TOKEN'] } }; // add tracer: new Tracer({ exporter }) to export spans
const author = { name: 'Release Bot', email: 'bot@example.com' }; // time defaults to now, tz to +0000
const outDir = './site-checkout'; // checkoutDir writes here; it must be absent or emptyFirst commit into an empty repository. pushTree commits exactly files as the tree. A branch that does not exist yet is created as a root commit.
// quick-start: first-commit
import { pushTree } from 'ply';
const first = await pushTree(url, {
ref: 'refs/heads/main',
files: {
'README.md': '# site\n',
'src/config.ts': 'export const VERSION = "1.2.3";\n',
'bin/build': { data: '#!/bin/sh\necho build\n', mode: '100755' },
},
author, message: 'Initial commit',
}, opts);
if (!first.ok) throw first.error;
console.log(first.value.newCommit); // the commit id main now points atRead a commit, a directory, and a file (streamed, hash-checked as it is read).
// quick-start: read
import { readCommit, listTree, readFile } from 'ply';
const head = await readCommit(url, { ref: 'main' }, opts);
if (!head.ok) throw head.error;
if ('empty' in head.value) throw new Error('main has no commits yet');
console.log(head.value.oid, head.value.tree, head.value.parents, head.value.message);
const listing = await listTree(url, { ref: 'main', path: 'src' }, opts);
if (!listing.ok) throw listing.error;
for (const e of listing.value.entries) console.log(e.mode, e.type, e.oid, e.name); // as git ls-tree prints them
const file = await readFile(url, { ref: 'main', path: 'src/config.ts' }, opts);
if (!file.ok) throw file.error;
const config = await new Response(file.value.stream).text(); // read the stream to the end (or cancel it)
console.log(file.value.size, config);Edit one file: find exactly one occurrence and replace it. The blob streams through; the push is a delta.
// quick-start: edit
import { editFile } from 'ply';
const bump = await editFile(url, {
ref: 'refs/heads/main', path: 'src/config.ts',
find: 'VERSION = "1.2.3"', replace: 'VERSION = "1.2.4"',
author, message: 'Bump version to 1.2.4',
}, opts);
if (!bump.ok) throw bump.error; // match_count when find is not there exactly once
console.log(bump.value.newCommit, bump.value.noop); // noop: find === replace, nothing pushedSeveral changes in one commit, applied in order.
// quick-start: commit-changes
import { commitChanges } from 'ply';
const change = await commitChanges(url, {
ref: 'refs/heads/main',
changes: [
{ kind: 'create', path: 'docs/intro.md', content: '# Intro\n' }, // refuses a path that exists
{ kind: 'write', path: 'README.md', content: '# site\n\nHello.\n' }, // creates or overwrites
{ kind: 'edit', path: 'src/config.ts', find: '1.2.4', replace: '1.3.0' }, // exactly one match
{ kind: 'delete', path: 'bin/build' }, // a file or a whole directory
{ kind: 'rename', from: 'docs/intro.md', to: 'docs/index.md' },
],
author, message: 'Docs; version 1.3.0',
}, opts);
if (!change.ok) throw change.error;
console.log(change.value.outcome, change.value.oid); // 'commit', or 'noop' when the tree did not changeBranches: create one at a commit (a ref name or a 40-hex commit id), commit to it, merge it back. mergeBranch fast-forwards when it can and otherwise writes a merge commit (git's merge-ort result for clean merges; merge_conflict with the paths otherwise).
// quick-start: branch-merge
import { createBranch, mergeBranch } from 'ply';
const feature = await createBranch(url, { ref: 'refs/heads/feature', from: 'main' }, opts);
if (!feature.ok) throw feature.error; // cas_conflict when the branch already exists
const work = await commitChanges(url, {
ref: 'refs/heads/feature',
changes: [{ kind: 'create', path: 'src/feature.ts', content: 'export const feature = true;\n' }],
author, message: 'Add feature flag',
}, opts);
if (!work.ok) throw work.error;
const hotfix = await editFile(url, { // main moves on meanwhile
ref: 'refs/heads/main', path: 'README.md', find: 'Hello.', replace: 'Hello, world.', author, message: 'Fix greeting',
}, opts);
if (!hotfix.ok) throw hotfix.error;
const merged = await mergeBranch(url, { ref: 'refs/heads/main', from: 'refs/heads/feature', author }, opts);
if (!merged.ok) throw merged.error;
console.log(merged.value.outcome, merged.value.oid); // 'merge': a commit with parents [main, feature]Tags: lightweight (the ref names the commit) or annotated (a tag object with a tagger and message).
// quick-start: tag
import { createTag } from 'ply';
const release = await createTag(url, { name: 'v1.3.0', target: 'refs/heads/main' }, opts);
if (!release.ok) throw release.error;
const notes = await createTag(url, { name: 'v1.3.0-notes', target: release.value.commit, message: 'Release 1.3.0', tagger: author }, opts);
if (!notes.ok) throw notes.error;
console.log(notes.value.oid, notes.value.commit); // the tag object, and the commit it namesRebase, cherry-pick, revert. Each replays commits with the same three-way merge and pushes with the old tip as the compare-and-swap.
// quick-start: rebase-pick-revert
import { rebaseBranch, cherryPick, revertCommit } from 'ply';
const topic = await createBranch(url, { ref: 'refs/heads/topic', from: 'refs/heads/main' }, opts);
if (!topic.ok) throw topic.error;
const onTopic = await commitChanges(url, { ref: 'refs/heads/topic', changes: [{ kind: 'create', path: 'src/topic.ts', content: 'export const topic = 1;\n' }], author, message: 'Add topic' }, opts);
if (!onTopic.ok) throw onTopic.error;
const onMain = await commitChanges(url, { ref: 'refs/heads/main', changes: [{ kind: 'create', path: 'CHANGELOG.md', content: '1.3.0\n' }], author, message: 'Changelog' }, opts);
if (!onMain.ok) throw onMain.error;
const rebased = await rebaseBranch(url, { ref: 'refs/heads/topic', onto: 'refs/heads/main', committer: author }, opts);
if (!rebased.ok) throw rebased.error; // topic's commits replayed onto main's tip
const picked = await cherryPick(url, { ref: 'refs/heads/main', commit: rebased.value.oid, committer: author }, opts);
if (!picked.ok) throw picked.error; // outcome 'ok', or 'empty' when main already has the change (nothing written)
const reverted = await revertCommit(url, { ref: 'refs/heads/main', commit: picked.value.oid, committer: author }, opts);
if (!reverted.ok) throw reverted.error; // a 'Revert "Add topic"' commit on mainHistory, first parent, newest first (git log --first-parent).
// quick-start: history
import { readLog } from 'ply';
const log = await readLog(url, { ref: 'refs/heads/main', limit: 10 }, opts);
if (!log.ok) throw log.error;
for (const c of log.value.commits) console.log(c.oid.slice(0, 7), c.parents.length, c.message.split('\n')[0]);Check out a whole tree: as streams (Workers-safe), or into a directory (Node, laid out as git clone would, without .git).
// quick-start: checkout
import { checkoutTree } from 'ply';
import { checkoutDir } from 'ply/checkout-node';
const tree = await checkoutTree(url, { ref: 'v1.3.0' }, opts);
if (!tree.ok) throw tree.error;
for await (const f of tree.value.files) {
if (f.stream) console.log(f.path, f.mode, (await new Response(f.stream).arrayBuffer()).byteLength); // read each stream
}
const written = await checkoutDir(url, { dir: outDir, ref: 'main' }, opts);
if (!written.ok) throw written.error;
console.log(written.value.written.files); // files written under outDirDelete a branch. Without expected the tip ls-refs reports is the compare-and-swap; with expected: '<oid>' the delete happens only from that tip. The branch the remote's HEAD names is refused by the server (push_rejected).
// quick-start: refs
import { listRefs, deleteBranch, deleteTag } from 'ply';
const refs = await listRefs(url, {}, opts); // branches and tags; { prefixes: ['refs/heads/'] } for branches only
if (!refs.ok) throw refs.error;
console.log(refs.value.head, refs.value.refs.map(r => r.name)); // 'refs/heads/main', [ 'refs/heads/feature', … ]
const gone = await deleteBranch(url, { ref: 'refs/heads/feature', expected: work.value.oid }, opts);
if (!gone.ok) throw gone.error; // cas_conflict when feature moved off that commit; not_found when it is gone
const untagged = await deleteTag(url, { name: 'v1.3.0-notes' }, opts);
if (!untagged.ok) throw untagged.error;Errors. error.code is a closed union, so a switch with assertNever in default is checked exhaustive by TypeScript (a new code in ply fails your build, not your users). What to do with each:
// quick-start: errors
import { assertNever } from 'ply';
const stale = await editFile(url, {
ref: 'refs/heads/main', path: 'src/config.ts', find: 'VERSION = "9.9.9"', replace: 'VERSION = "10.0.0"', author, message: 'Bump',
}, opts);
if (!stale.ok) {
const e = stale.error;
switch (e.code) {
case 'cas_conflict': // the ref moved between read and push (editFile already redid it once): read again, redo
console.warn('moved', e.expected, e.actual); break;
case 'match_count': // find matched e.matches times, not once: the file is not what you expected
console.warn('matches', e.matches); break;
case 'not_found': // e.miss.kind: 'ref' | 'path' | 'repository' | 'head_unborn' | 'commit' | …
console.warn('missing', e.miss.kind); break;
case 'auth': // 401/403: the credential is missing, wrong, or lacks write access
console.warn('auth'); break;
case 'limit_exceeded': // a limits.* bound (e.what, e.got, e.max): raise it with withLimits, or do less per call
console.warn('limit', e.what, e.got, e.max); break;
case 'ambiguous': // the push was sent and may have landed: read the ref back before doing anything else
console.warn('unknown outcome'); break;
case 'network': case 'timeout': case 'rate_limited': case 'upstream_5xx': case 'protocol': case 'pack_corrupt':
console.warn('transient: retry with backoff', e.code); break; // isRetryable(e) is true for exactly these
case 'merge_conflict': case 'not_fast_forward': case 'not_linear': case 'unrelated_histories':
console.warn('history needs a human', e.code); break;
case 'push_rejected': case 'push_partial': case 'remote_error': // a hook, branch protection, or the server said no
console.warn('refused', e.message); break;
case 'bad_request': case 'unsupported': case 'lfs_pointer': case 'http': case 'not_git': case 'aborted': case 'internal':
console.warn('fix the call or the setup', e.code, e.message); break;
default:
assertNever(e);
}
}retryPolicy(error) gives the same advice as data (yes, fresh, read, no), and CODE_DOCS[code] a one-line description. Every option an entry takes is in its section below.
More detail
inflate(buf, pos = 0, opts) reads the zlib member at buf[pos..] and reports the bytes it consumed. pos is a position in buf: a non-negative safe integer no greater than buf.length (at the very end there are no bytes, so the member is cut: pack_corrupt). Any other value (negative, fractional, NaN, past the end, a string) is bad_request before a byte is read; it used to be passed to subarray, which reads a negative offset from the end of the buffer, and NaN threw.
Sha1 is an incremental hasher: update(bytes) any number of times, and digest() (20 bytes) or hex() (an Oid) is a snapshot of the bytes fed so far. It leaves the hasher as it was, so it can be called repeatedly (same input, same value) and update() may continue afterwards, which is what a running pack checksum needs. A second digest() used to return the hash of the message plus its padding. streamingSha1().hex() may also be awaited more than once (the same value); on Workers it ends the native DigestStream, so there an update after hex() rejects.
resolvePack(parsed, external, limits) resolves every delta of a parsed pack (parsePack's value, or { objects } built by hand) and returns { objects, stats }. objects is a Map from id to object, and its iteration order promises one thing: every base that is in the pack comes before the objects built on it (an id the pack holds twice has the place of the copy that resolved first). The order of siblings is not part of the contract, and it changed when the resolver began to work by dependency: for a thin pack [REF@2 on X, REF@3 on X, OFS@4 on 2] with X given, the objects come out at offsets 2, 4, 3 where they came out 2, 3, 4. external(oid) supplies thin bases: { type, data } for a base that is not in the pack, or null. It is called once per distinct missing base id, in pack order of the first REF_DELTA that waits on that id, however many deltas rest on it (it used to be called once per waiting delta, so a caller that counts invocations sees fewer), and only after everything the pack can resolve by itself has resolved. Every REF_DELTA waiting on an id that external gives is patched directly on that base (chain 1, counted in stats.externalBases), also when the pack then produces that id itself: for [REF@2 on X, OFS@3 on 2 producing X, REF@4 on X] with X given, both REF deltas are patched on the given X (externalBases 2, maxChain 2) where the second used to be patched on the pack's copy at offset 3 (externalBases 1, maxChain 3), so such a pack can resolve where it used to be limit_exceeded. The other way round, a REF_DELTA whose base the pack itself builds is patched on the pack's copy whenever that copy resolves before the id is asked for: external is then not asked for that id, even if it holds it, and the delta's chain is the pack's own, so such a pack can be limit_exceeded where it used to resolve. For [REF@2 on X producing A, REF@3 on B producing C, OFS@4 on 2 producing B] with X and B given, external is asked for X only (it used to be asked for X, then B), and C is patched on the pack's B at offset 4: C's chain is 3, stats.maxChain 3 and stats.externalBases 1 (C used to be patched on the given B: chain 1, maxChain 2, externalBases 2), and with maxDeltaChain 2 the pack is limit_exceeded "delta chain depth 3 exceeds limit 2" where it used to resolve. A REF_DELTA on an id the pack holds twice is patched on whichever copy is registered when the delta is resolved, which can be the deeper one: for [REF@2 on c0 producing c5, whole c1 at 3, OFS@4 on 3 producing c0, whole c5 at 5, REF@6 on c5 producing c2] with no external, the object at offset 6 has chain 3 where it had 1, and with maxDeltaChain 2 the pack is limit_exceeded where it used to resolve. A pack of either shape that both versions refuse may carry the other code: limit_exceeded where it was pack_corrupt "ref delta base … not found", and the reverse. A base it returns must hash to the id that named it (pack_corrupt otherwise); a base it does not have is pack_corrupt "ref delta base … not found". The chain limit is checked before the lookup, and that check counts OFS links down to the nearest REF_DELTA: a delta more than maxDeltaChain OFS deltas above a REF_DELTA whose base has not resolved from the pack is limit_exceeded (what: 'delta chain depth') and external is not called; a delta exactly maxDeltaChain OFS deltas above it is limit_exceeded if the base is given and "not found" if it is not. A chain of REF deltas is counted one link at a time, as each base resolves, and none of it is refused before the lookup: with its bottom base withheld, a REF chain of any length is "not found" after external was asked once for each link's base id, and with that base given the first link past maxDeltaChain is limit_exceeded. describePack(bytes, limits) takes no lookup: a base outside the pack is listed under missingBases, the objects that wait on it have oid: null, and the same check applies: an OFS chain more than maxDeltaChain deltas above a REF_DELTA whose base is missing is limit_exceeded, and a chain of REF deltas above a missing base is not (each link's base id is listed under missingBases). stats is { maxChain, externalBases, baseLookups, steps }: the longest delta chain resolved, the deltas patched directly on a base external gave, the REF_DELTA base lookups by id, and steps, the number of entry visits the resolver made. An entry is visited at most three times in any pack order, so steps is at most three times the object count; it is a work counter for tests and telemetry, and its exact value may change between versions. Input with two entries at one offset (hand-built only; parsePack cannot produce it) gives one object at that offset: the first of those entries to resolve, which need not be the first in the list, because whole objects resolve before deltas, and deltas on bases in the pack before deltas on bases external gives. A cycle of OFS bases (hand-built only) is limit_exceeded delta chain depth.
Wrong-shape arguments. These entry points answer null, undefined (for a required argument), a number or an array where an object, array or Uint8Array is documented with bad_request whose what names the argument, never a throw: pushRepo (spec, options), pushDir (spec, options), filesFromDir (dir, options), pushPack, copyTree, loadTransferPack, planTransfer, planPackBatches, resolvePackRange, scanPackIndex, packSubset; decodeSavedIndex answers them with its bad_argument refusal (what bytes or want), and the root's matchOption with bad_request (what option or handlers), while isSome and isNone answer false. Every other export may still throw a TypeError on such an argument; each call shape that does is listed in the STILL_THROWS allow-list in test/input-validation.test.js, which fails when a listed shape stops throwing or an unlisted one starts.
parsePack accepts optional maxObjects and maxInflatedTotal. Omitting them uses DEFAULT_LIMITS (maxPackObjects 100_000, maxInflatedTotal 256 MiB). A limits object that drops either key fails closed (bad_request) instead of leaving the cap off. validateIdent({ name, email, time, tz }) is the only way to build an author, committer, or tagger: time is a non-negative safe integer, tz is a civil offset (-1200..+1400), and the result is branded so a spread cannot reach ident(). ply-web also uses these entry-point exports: validateIdent, validateRef, validatePath, concat, limitError, isFilterRejection, fromAny, packParseOpts.
import { editFile, Tracer, consoleExporter } from 'ply';
const tracer = new Tracer({ exporter: consoleExporter() }); // logs each export as one JSON line; or your own (request) => …, which gets the object: { resourceSpans: [{ resource, scopeSpans: [{ scope, spans: [span] }] }] }
const cache = new Map(); // trees by oid, reused across edits
const r = await editFile('https://github.com/o/r.git', {
ref: 'refs/heads/main', path: 'src/config.ts',
find: 'VERSION = "1.2.3"', replace: 'VERSION = "1.2.4"',
author: { name: 'bot', email: 'bot@x' }, message: 'bump',
}, { auth: { token: process.env.GIT_TOKEN }, tracer, cache });
if (!r.ok) {
switch (r.error.code) { /* exhaustive over Code: every case, no default, then assertNever(r.error) */ }
}
// r.value.newCommit, r.value.pushBytes (≈ 300 + |replace| + 80·depth), r.value.noopEvery public function returns a Result (0.2.0): { ok: true, value } or { ok: false, error }, never a throw. error is a PlyError: an Error with a code from a closed union, so switch (r.error.code) with no default is checked exhaustive by the compiler. The one exception is decodeSavedIndex, whose error is the typed SavedIndexRefusal (a plain object; switch (r.error.tag) over its eight tags, see Saved pack index below), because a refused saved index means "scan again", not a failure. A stream (readFile's stream, checkoutTree's files) reports a failure the way a stream does: it errors, with that same PlyError.
Your own code failing is an Err too. When a function you passed throws or rejects, the Err carries the thrown value, untouched, as error.cause (ply writes nothing on it), and error.what says whose it was. These are named:
| you passed | error.what | error.code |
|---|---|---|
signer (its sign fails, or returns a non-string) | 'signer' | bad_request |
filter (pushDir / filesFromDir) | 'filter' | bad_request |
transport: frames() throws, or its stream rejects | 'transport.frames' | bad_request on a read request; ambiguous on the push request |
transport: advertise() throws or rejects | 'transport.advertise' | bad_request |
fetchImpl throws or rejects | 'fetchImpl' | network (a fetch that fails is a network failure); aborted / timeout instead when the request's signal fired, and those are not named fetchImpl |
cachingFetch's shouldCache, waitUntil, or the cache's match / delete / put throws when called | 'shouldCache', 'waitUntil', 'cache.match', 'cache.delete', 'cache.put' | bad_request |
Every other function you pass ends in the backstop: a throw from it that reaches the end of an operation (editFile, commitChanges, pushTree, merge, rebase, pick, and an operation() body together with every callback reached from it) is what: 'callback' with the thrown value as error.cause. For an operation() body this is a breaking change since #277: before it, the body's throw reached you unchanged; see "operation(): your body's outcomes" below. Three things are not failures of the operation: a cache whose match or delete promise rejects is a miss, a put that rejects is counted in stats (putFailed, putError; a put that throws when called is the fetch's 'cache.put' failure, since it is called inside the fetch; under verifyBeforeStore the put is called only after verifyFetchAnswer accepted the answer, after the fetch answered, so one that throws there is counted in putFailed too, putError holding the 'cache.put' Err's message, which names the thrown value, and the fetch is unaffected), and an advertise() ply calls only to confirm a refused push or an empty answer confirms nothing when it fails. A thrown value that already carries one of ply's codes (a transport or fetch that wraps ply's own) is that error, as it is. The outcome class follows the push: before the push request was handed to the transport nothing can have moved, so the failure is definite (the code in the table; the backstop is bad_request, retry no); once it was, the ref may have moved, so it is ambiguous (read the ref back): a named failure on a later read is then the cause of that ambiguous, and the backstop puts the replaced code, if the thrown value had one, in error.original. pushDir and filesFromDir also return node:fs's own failures (a missing directory, an unreadable file) as bad_request with what: 'dir' and the node error (its code such as ENOENT or EACCES, its path) as error.cause. This holds whatever the thrown value is: one that cannot be described (a null-prototype object, an object whose message getter or toString throws, a revoked Proxy) still ends as that Err, whose message says a value with no string form and whose cause is the value. Telemetry callbacks are different: they never change the outcome at all (see onTelemetryError).
operation(): your body's outcomes
Breaking change since #277. In operation(op, url, opts, body), a throw from body (or from any callback reached from it) never reaches you as a throw or a rejection. This covers body only: a caller tracer whose start() throws, or an opts.link whose span is null or undefined (or whose traceId/spanId getter throws), still rejects before body runs. What you get back depends only on what was thrown and on whether a push request had been handed to the transport (the first t.frames() call for a service other than git-upload-pack) when it was thrown:
body … | before the push request was handed over | after |
|---|---|---|
throws a value that is not a PlyError | bad_request, what: 'callback', cause the thrown value | ambiguous, what: 'callback', cause the thrown value, its code in original if it has one (any value but null or undefined; a node ECONNRESET error, say) |
throws a PlyError | that PlyError, as itself | ambiguous, what: 'callback', cause the thrown error, its code in original (a thrown ambiguous is itself) |
returns a Result | that Result, as it is | that Result, as it is |
So a callback's own throw is treated as a failure, never as an answer: a definite cas_conflict you learned and then threw after the push is reported ambiguous. Return expected outcomes as values, a discriminated union inside the Ok (the pattern ply-web adopted in ivarvong/ply-web#153):
type Bump = { tag: 'bumped'; commit: string } | { tag: 'conflict'; reason: 'ref_exists' | 'stale_expected' };
const r = await operation<Bump>('bump', url, opts, async ({ t, root, outcome }) => {
// … read refs over t …
if (exists) return outcome('conflict', { tag: 'conflict', reason: 'ref_exists' });
// … push over t …
return outcome('ok', { tag: 'bumped', commit });
});
if (!r.ok) return status(r.error); // ply's failure, or your crash (what: 'callback')
if (r.value.tag === 'conflict') return conflict409(r.value.reason);test/operation-callback-contract.test.js pins each row.
Upgrading from 0de5ad4-era releases
Before #277 a value thrown from an operation() body reached the caller unchanged, so some consumers threw their own errors through it for control flow (ply-web's ref_exists and stale_expected 409s). Those now arrive as bad_request (what: 'callback', your value in error.cause), or as ambiguous when thrown after the push request was handed over; nothing fails to compile and nothing throws, the answer just changes. Return them as values instead (above). Reading error.cause of a what: 'callback' Err works as a stopgap before the hand-over, but after it the code is ambiguous and the ref may have moved.
Credentials: auth: { token, user? } (Basic <user>:<token>, user defaulting to x-access-token, sent as UTF-8 bytes as git sends a credential helper's), { bearer }, or { header } (an Authorization value forwarded verbatim; it and a bearer token must be printable ASCII). An auth that would send nothing is bad_request: {}, an empty token with no user, and { user } alone (git's credential API asks for the password there; { user, token: '' } sends Basic <user>:, the https://<user>@host form). Without auth, userinfo in the URL is sent as git sends it, byte for byte (percent-decoded): https://user:pass@host/… is Basic user:pass, a token as the user (https://<token>@host/…, the GitHub and GitLab form) is Basic <token>:, https://:pass@host/… is :pass; a NUL, CR or LF in it, or a URL that does not parse, is bad_request before any request. createTransport (and every operation given a URL) requests only http: and https: URLs, and the rule is applied to the URL that will be requested, in this order: the URL must parse, its userinfo must be clean (what: 'url userinfo'), then your allowUrl runs on the base, then the scheme is checked, and only then are auth and limits validated. A base that is not http(s) given together with an invalid auth or an invalid limit therefore reports what: 'url', where the same options on an http(s) base report what: 'auth' or the limit's name (what: 'requestTimeoutMs'); both are bad_request, and before the scheme rule such a base reported the auth or the limit. So a base in a scheme of your own that allowUrl maps to https: is accepted, an allowUrl that refuses returns your own error, an allowUrl that answers with a URL that is not http(s) is bad_request (what: 'allowUrl'), and without an allowUrl a base that is not http(s) (file:, data:, ssh:, git:, …) is bad_request (what: 'url', a fixed message that never repeats the URL) with no request made; before, such a base was accepted and failed later as a network error from fetch. None reaches a span, a URL attribute or an error message, even when a server echoes it (the Basic user too, when it is token-shaped or the whole credential). By default redirects are never followed: a 3xx is an http error naming the target, so no credential can follow it to another origin. followRedirects: 'initial' is git's http.followRedirects=initial: only the first GET info/refs is followed (up to maxRedirects, each Location through your allowUrl), the base is rewritten, and a cross-origin rebase drops the credential. How that exchange settled (the followed Locations, or none) is remembered per remote and service, like the quirks record, so a later transport for the same remote sends its first POST straight to the settled base with no GET; the remembered Locations go through that transport's own allowUrl and maxRedirects again, and a 3xx on that base drops the memo, settles over the network and re-sends a byte body once (a streamed body gets the error). forgetQuirks(url) forgets it too.
Outcomes are typed on r.error.code: cas_conflict (retry), match_count (find ≠ exactly once), not_found, auth, rate_limited, pack_corrupt, remote_error, upstream_5xx. A find === replace edit returns { noop: true } and pushes nothing.
Wire sequence
| # | Request | Response | Why |
|---|---|---|---|
| 1 | v2 ls-refs with ref-prefix | one line | head oid |
| 2 | v2 fetch want <commit> filter tree:0 deepen 1 done | 1-object pack | commit only (~300 B) |
| 3…N+2 | v2 fetch want <tree> filter tree:0 per level | 1-object pack each | only the trees on the path; cached by oid (immutable) |
| N+3 | v2 fetch want <blob> | 1-object pack, streamed | inflate → scan → SHA-1, never materialized |
| N+4 | v0 receive-pack thin pack | unpack ok / ng | commit full + N tree REF_DELTAs + blob REF_DELTA; old new ref line is the CAS |
With a warm tree cache (root tree oid unchanged) steps 3…N+2 vanish: 3 roundtrips + push.
Fewer round trips on repeat edits
Two ideas from gitgrep:
cachingFetch(fetch, caches.default, { waitUntil })asfetchImpl: the commit/tree fetches are wants-only, filtered, and every object is hash-verified on arrival, so the responses are immutable and cached per colo undersha256(url, credential, body). The answer streams to the caller and, through a verifier, intocache.put; withoutverifyBeforeStorenothing on the cache path holds a whole answer (with it, a MISS holds up to three timeslimits.maxPackBytes, below). The verifier keeps one pkt-line frame of state and errors the body handed toputat the first violation or at the end: pkt-line framing complete to the final flush, noERRpacket, no sideband channel-3 message and, when there is a packfile section, aPACKv2/v3 header and a trailing SHA-1 equal to a running SHA-1 of the pack bytes (no inflate, no delta resolution; pack and progress are each held tolimits.maxPackBytes, and limits that do not parse store nothing). That running SHA-1 is what a MISS costs in the cache layer: in Node it is ply's pure-JS SHA-1, measured at about 3.5 ms of CPU per MiB of pack (Node 24.18, laptop, 1 MiB and 10 MiB answers; about 0.4 ms per MiB without it), and where the platform hascrypto.DigestStream(Workers) it is the native digest, not measured here. An acknowledgments-only fetch answer (a round that ends on itsNAK/ACKlines, to a request withoutdone) is refused and not stored, asverifyFetchAnswerrefuses it ("answer: no packfile section"). The answer to another command a caller's ownshouldCacheadmits (ls-refs) is checked for framing andERRonly, and is cacheable. A failed or cut answer still reaches the caller and is not stored, so one bad exchange is not replayed:PackCache.puttakes no abort signal, so the errored body is the abort (a Cache API put fails with its body), and the key is deleted after a refusal as well, counted instats.verifyFailedwith the reason instats.verifyError(git.pack.cache.verify.failed/.verify.erroron the span). A delete that fails there, by rejecting or by throwing, is ignored and does not reject the promise handed towaitUntil. The store never paces the caller: the cache branch queues at mostCACHE_LAG_BYTES(1 MiB) for a store that reads slower than the caller, and past that the put is given up and the answer is not stored (stats.putFailed, the key deleted). A caller that cancels the response body cancels the origin and the put; nothing is drained. The store is untrusted, and a HIT is streamed exactly as stored, with no pass in the cache layer (f.counters.parsedcounts the chunks the cache layer parsed; a HIT adds none): the check is the caller's own parse of the replayed answer. ply's client verifies the pack and hashes every object, and a HIT whose answer it refuses (pack_corrupt,protocolorremote_error: a flipped pack byte, a cut or empty entry, a wrong pack trailer, a storedERR) is deleted and asked for once more from the origin (x-ply-cache: bust, answeredx-ply-pack-cache: BUST,stats.bust); the retry's outcome is the call's outcome, and a limit, a timeout, an abort or a transport failure on a HIT is not retried. The blob stream is never cached, unlessverifyBeforeStore: true: that widens the rule to every wants-only fetch and stores an answer only afterverifyFetchAnsweraccepted the whole of it (every want present, every object hashed;openBlobhas no retry past a bad entry, so the entry must be right when it is written). Under the flag the store reads the cache branch whole, capped at three timeslimits.maxPackBytes(the pack and the progress v2Step accepts, plus framing), before the put, on top of the streaming verifier; an answer it refuses, and the answer to a request that is no fetch (ls-refs under a caller'sshouldCache), is not stored and is counted instats.verifyFailed(nothing was put, so no key is deleted);stats.verifyOkcounts only the answers handed toput, not every answer the streaming verifier passed. When theputis called differs: without the flag it is called inside the fetch on every MISS, before the fetch answers (aputthat throws when called is that fetch's'cache.put'Err, and the answer is cancelled first); with it, only onceverifyFetchAnsweraccepted the answer, after the fetch answered, so aputthat throws or rejects then isstats.putFailed(putErrorthe'cache.put'Err's message for a throw, the rejection's own message for a reject) and never a rejection of the fetch already returned. Off Workers,memoryCache({ maxBytes, maxEntries })is a store with the same shape: it keeps at mostmaxBytesof bodies and header text (defaultLIMIT_MEMORY_CACHE_BYTES, 64 MiB) in at mostmaxEntriesentries (defaultLIMIT_MEMORY_CACHE_ENTRIES, 1024), evicts the least recently used first, and does not store an entry larger than the whole byte budget. A fractional budget is floored (maxBytes: 100.5is 100 bytes); a value that is not a finite, non-negative number (NaN, a negative, an infinity) falls back to the default, since the constructor returns no error.head: the oid you believe the ref points at (your lastnewCommit). Skips ls-refs; receive-pack's compare-and-swap is the freshness check, and a stale hint is redone once from a real ls-refs (result.hintis'used' | 'stale' | null).
Against github.com: 4 rtt / 549 ms cold → 3 rtt / 73 ms with both.
head runs ls-refs concurrently with a speculative fetch of the hinted commit, so a stale hint is corrected before anything is pushed — same wall time as skipping ls-refs, one extra request, no wasted push. A cas_conflict (replica lag between ls-refs and receive-pack) is redone once, the retry's span linked to the first.
Also: client.discover() is a capability canary (agent, object-format, fetch= features); push records the server's band-2 text in git.push.remote.messages; the blob hash uses native crypto.DigestStream where the platform has it.
Reading without a clone
readFile(url, { ref, path }, opts) → { ref, commit, blob, mode, size, stream }: ls-refs → commit (tree:0, deepen 1) → one tree per level → the blob as a ReadableStream, hash-checked as it passes (the stream errors rather than ends if the bytes are not the blob's). The latest chunk stays until the object hash and the pack trailer verify, and a failure errors the stream without releasing it, so a consumer that received every byte saw a verified blob. size is known before the first byte. A path that ends in / names a directory and is bad_request (what: 'path') before any request, as git cat-file -t HEAD:file/ refuses it for a blob; earlier versions dropped the slash and read file (a breaking change, #300-8). listTree still reads dir/ as dir, as git does for a tree. openBlob(transport, oid, { maxBytes, follows }) opens that stream on a caller's transport for an oid it already resolved: { kind: 'stream', size, stream }, or { kind: 'too_big', size } when the object header's size is above maxBytes. The fetch is cancelled then (git.read.blob.header_only) and no body byte is delivered. readBlob is the same, buffered, and a pack that fails verification is an error rather than bytes. The stream is O(1) in memory but not unbounded on the wire: a blob whose pack exceeds limits.maxPackBytes (128 MiB; GitHub caps files at 100 MiB) is limit_exceeded, and one whose zlib stream runs past what its declared size allows (zlibBound, zlib's own deflateBound) is pack_corrupt, so a server cannot feed a reader forever. listTree(url, { ref, path }) → { tree, entries: [{ name, mode, oid, type }] } as git ls-tree prints them. ref is HEAD (default), a full ref, a short name (git's order: tags before branches), or a commit oid; tags are peeled. resolveCommit(transport, ref, { abbrev: 'advertised' }) also takes a 4–39 character lowercase hex prefix when it matches one advertised tip (HEAD, branches, tags, and peeled targets) in that one ls-refs; a ref name wins, as in git. The default abbrev: 'off' keeps a short hex string as a ref name. resolveAbbrev is that step on an ls-refs answer (unique_among_advertised, none, or ambiguous). It is weaker than git rev-parse: an interior object is not a candidate. import { readFile, listTree } from 'ply/read' (36 KB min, no push or merge code). A not_found carries miss (miss.kind): a missing ref, an absent or unborn HEAD, a missing path, a file where a directory was required, a directory, a submodule, a commit (miss.kind === 'commit', then miss.miss is absent or not_commit), or a repository 404. readCommit of an unborn HEAD, or of that branch by name, returns { empty: true, ref } instead of not_found. walkPath(transport, treeOid, comps, { cache }) walks a tree the caller already has. walkCommit(transport, commitOid, comps, { cache, levels }) → { commit, data, tree, entry } walks from a commit: on a server known to take combine:blob:none+tree:K (GitLab, Codeberg) the commit and its first min(levels, 2) tree levels come in one fetch, elsewhere it is the commit and one tree per level, as readFile reads them; levels defaults to comps.length + 1, and a tree that fetch brought but the walk did not read is answered by fetchObject with no request. fetchCommit(transport, oid) is that commit fetch for a 40-hex id: { oid, data, commit }, or not_found with that commit miss. A corrupt pack stays pack_corrupt. readCommit, readLog, and pickCommit use that classification.
The walk's first two tree levels ride with the commit (#218) where the server takes filter combine:blob:none+tree:K (git with uploadpack.allowFilter: gitlab.com, codeberg.org, a self-hosted git): one fetch brings the commit and every tree at depth < K, K = the levels the path needs, at most 2 (the root and its children). readFile at depth n is then 3 + max(0, n − 2) round trips instead of 3 + n, listTree 2 + max(0, n − 1) instead of 3 + n. Deeper levels are still one tree:0 fetch each: K = 3 is the whole repository's second level (gitlab-org/gitlab: 526 KB and 566 trees, against 36 KB and 48 trees at K = 2), slower than the round trips it saves. The pack is checked as a blob:none pack is (hashes computed, every commit and tree against your limits, an extra over a limit dropped, a malformed object fails it) and its trees harvested for the walk. Whether a server takes it is learned from its answer and kept with the quirks record (not in it: the record's shape is unchanged); it is asked only once tree:0 is known to work there, and the first time runs beside the tree:0 commit fetch, so a refusal costs a request, not a round trip. GitHub refuses it (filter 'combine' not supported, tree filter allows max depth 0), so GitHub reads are unchanged; Artifacts sends every tree with a blob:none commit fetch already (3 round trips at any depth) and is never asked. A failed attempt is not used: the tree:0 walk answers. Spans: git.fetch.path_trees (the filter sent) on that fetch.
One object by id: fetchObject
fetchObject(transport, { oid, expectType, filter, deepen }) → { type, data, oid, size } (objectAt is the same for an id already parsed). One object costs one object of pack, whatever the history behind it. By default (deepen left out or null) a want that may be a commit (expectType left out, TYPE.COMMIT or TYPE.TAG) is sent with deepen 1: git answers a commit want without a depth with every commit reachable from it (filter tree:0 drops trees and blobs, not ancestors), so the pack grew with the repository's history and a large one was refused at limits.maxInflatedTotal (curl/curl: 64 MiB of commits for one commit). With expectType TYPE.TREE or TYPE.BLOB no deepen is sent: no history is reachable from a tree or a blob. To ask for history, say so: deepen: n is the commit and n − 1 generations of its ancestors, deepen: 0 sends no deepen line (the whole history, held to the pack limits); a caller's deepen is always sent as given. The server's shallow-info section is read as protocol v2 defines it and nothing returned or kept says the repository is shallow (the result has no such field; the span carries the server's lines as git.fetch.shallow). An annotated tag want is answered by git with the tag and the one commit it peels to (two objects, where it was the tag and the whole history); fetchObject still refuses a two-object answer to a want that is not expectType: TYPE.COMMIT (pack_corrupt, pack: expected 1 object, got 2). A server whose advertisement lists no shallow on its fetch= line is not sent the default depth: after discover() none is sent; otherwise a first request it refuses (an empty response, an ERR line (remote_error) or HTTP 400) sends ply to the advertisement once per quirks record, and the want is asked again without deepen, once (the answer is then the history, and the limits refuse it honestly when it is too large). That request is the one sent before the default depth and its answer is read the same way: a server that also lists no filter is asked unfiltered, and one that refuses tree:0 is asked with blob:none. If shallow is listed the first error stands; so an ERR line or a 400 for any other reason (a want the server does not have) costs one advertisement read, once per record. A 401, 403, 404, 429 or 5xx is never asked again, nor is a request whose deepen the caller gave. What the advertisement said about shallow is kept beside the quirks object, not in it: a consumer that rebuilds quirks from JSON relearns once per rebuilt object, which costs requests only on a server without shallow. The pack cache keys on the request body, so a deepen 1 request never shares an entry with one that sent none: every request that now carries the default depth (untyped wants and expectType: TYPE.TAG included, not only commits) has a new key.
Recent history: readLog
readLog(url, { ref, limit = 20 }, opts) → { ref, oid, commits: [{ oid, tree, parents, author, committer, message, signed }], truncated } (the commit view is readCommit's). The order is first parent, newest first: exactly git rev-list --first-parent -n <limit> <ref>, the line a branch's history follows (one merge commit per landed branch). parents lists every parent. truncated is true when history continues past the last commit returned; fewer than limit commits with truncated true means the server's own repository is shallow there. One fetch: want <commit> deepen <limit> filter tree:0, commits only. A server that refuses tree:0 (Artifacts) gets blob:none, learned once into quirks; that pack also carries every tree of the window, checked and harvested, so a following listTree/readFile on the same transport costs no round trip. Every object passes assertFetched, and the window is held to the deepen contract: a commit the server sent that is not an ancestor of ref, or a withheld parent without a shallow line, is pack_corrupt, never a short or foreign log. limit is 1 to limits.maxMergeDepth (1024); path filtering is not supported (bad_request): under tree:0 the window has no trees. import { readLog } from 'ply/log' (43 KB min). Measured on a local mirror of curl (10 commits, served by git http-backend): tree:0 6,073 B, 10 objects; blob:none 128,965 B, 87 objects (10 commits, 77 trees), against 121,646 B for blob:none deepen 1. Tested in test/log.test.js: server (tree:0, blob:none-only) × shape (linear, merges, root within the limit, first-parent length equal to the limit, longer) × limit (1, n, larger than the history) × server behaviour (honest, shallow lines dropped, a foreign commit added) = 90 cells, each against git.
Pushing a whole tree (deploy from a directory, no git binary)
pushTree(url, { ref, base?, files, author, message }, opts) commits exactly files as the new tree, on the current head of ref (or base), and pushes it with the same rules as editFile: head hint, one fresh retry on cas_conflict, strictHead, verify (an acknowledged push that does not read back is ambiguous), signer, cache. An absent ref is created as a root commit (zero old oid: the CAS means "must not exist"). Identical files are { noop: true }, nothing pushed.
import { pushTree } from 'ply/tree'; // Workers-safe
import { pushDir } from 'ply/tree-node'; // Node: walks a directory (node:fs)
await pushTree(url, { ref: 'refs/heads/main', author, message: 'deploy', files: {
'index.html': '<h1>hi</h1>', // string or Uint8Array → 100644
'bin/build': { data: script, mode: '100755' },
'latest': { mode: '120000', data: 'v2/index.html' }, // symlink: the target is the blob
'vendor/lib': { mode: '160000', oid: submoduleCommit }, // gitlink: no data; the server need not have the commit
} }, { auth, tracer, head: lastCommit });
await pushDir(url, { dir: './dist', ref: 'refs/heads/main', author, message: 'deploy' }, { auth, tracer });files is an object, a Map, or an iterable of { path, mode?, data?, oid? }. Paths are validated like editFile's (no .git, .., empty components); a path given twice, or as both a file and a directory, is bad_request before any request (git's fsck calls that tree duplicateEntries; encodeTree now refuses it too). README and readme are two names to git and are accepted: they collide only on a case-insensitive checkout.
encodeTree (and so every tree pushTree, commitChanges and mergeTrees write) never writes a tree git fsck --strict refuses. Each entry is checked before a byte is written, and the first one that fails is bad_request with what naming the field: a name that is not a string or has no byte form (tree entry name); a mode that is not exactly 100644, 100755, 120000, 40000 or 160000 (mode: zero-padded and non-canonical modes such as 040000 and 100664 are refused, not rewritten); an oid that is not 40 lowercase hex (oid); and, as tree entry, an empty name, a NUL or a / in a name, ., .., any spelling of .git that git checks (case-folded, NTFS short and stream forms, HFS ignorable code points, after a backslash), a name over 4096 bytes, the all-zero oid, .gitmodules as a symlink, tree or gitlink, .gitattributes as a tree or gitlink, and a duplicate name. A non-string name used to be encoded as its string form ("5", "undefined", "[object Object]"); it is now refused. pushTree refuses these with no request sent; commitChanges refuses them after its reads and before any push. The error does not grow with the name: the message quotes at most the first 200 UTF-16 units of a name or mode, followed by … (N UTF-16 units) when it was cut, and the entry field holds the same first 200 units, so match on what and the reason, not on the full name. The cut never splits a surrogate pair: when the 200th unit is the first half of one, 199 units are quoted, so a well-formed name gives a well-formed message and entry. A value that is not a string is named by its type (object, bigint) instead of being stringified. Each blob is bounded by maxObjectSize, the file count by maxPackObjects, each directory by maxTreeEntries.
treeSort(entries) returns the entries (the same objects, any iterable of { mode, name }) in git's tree order: by name bytes, a directory (40000) sorting as its name followed by /. It computes each entry's key once, before sorting, so it reads each name and mode once; the order is unchanged. Every name is therefore encoded: a name with no byte form (a lone surrogate) is bad_request for the first such entry in the order given, and a list of one such entry is now refused too (it used to be returned as it was, because a sort of one entry compares nothing). A name that is not a string (null, undefined, a Symbol, an object whose toString throws), or an entry that is not an object (null, undefined), is bad_request tree entry name must be a string at any list length, one entry included: the name is never converted to a string, so treeSort does not throw on it (a directory with such a name used to throw, or to sort as null/; a list of one such entry used to be returned as it was).
Repeat pushes are thin: ply reads the parent's trees only where the new tree differs (one tree:0 fetch per changed directory, cached by oid; on Artifacts the first blob:none fetch carries them all), sends only blobs no such tree names, and sends each changed tree as a REF_DELTA against the tree it replaces. Measured on a 208-entry tree (207 blobs, 26 trees) (test/push-tree.test.js): push 1 is 234 objects / ≈116.9 KB; push 2 (one file changed, one added, one deleted) is 7 objects / 1,176 B, exactly git rev-list --objects new ^old; push 3 (a one-byte change, head hint + cache) is 4 objects / 841 B with two upload-pack requests (ls-refs and the hinted commit, concurrent). Only the parent's trees are consulted, so a blob that exists on the server only in older history is sent again (correct, not minimal). Any push whose pack exceeds limits.maxPackBytes is refused before the upload starts: limit_exceeded, what: 'push pack bytes', got = the measured pack size (set maxPackBytes a little under a host's cap: Artifacts allows 64 MiB, 67,108,864 bytes, of request body, which is the pack plus the command prefix, and the prefix grows with ref name length).
pushDir / filesFromDir(dir, { filter, limits }) read a directory as git's index would: the owner's execute bit makes 100755, a symlink is 120000 with its target (never followed), empty directories vanish, .git is skipped, anything else (FIFO, socket) is bad_request. filter(path, { directory, symlink }) → false leaves a path out; .gitignore is not read, and there is no ply push CLI. Gitlinks come only from files ({ mode: '160000', oid }): a nested checkout is walked as a plain directory. A tree oid from filesFromDir equals git add -A && git write-tree on the same directory (tested). File names: on macOS a name is recorded as git add records it under the configuration git init writes there (core.precomposeunicode = true), so a file created as e + U+0301 is é in the tree and in the path a filter sees, while the file is still opened by its name on disk. That is git's precompose, not Unicode NFC: a decomposed pair is joined, marks are never reordered, a character standing alone is never rewritten (KELVIN SIGN U+212A, U+0958 and U+F900 stay as they are), a name holding a code point beyond the BMP (an emoji) is recorded as read, and the Balinese pairs are not joined (tested against git add -A of git 2.50 on macOS only, over every code point NFC rewrites and the decomposed form of every precomposed character); on every other platform a name is recorded as the file system returns it. Neither rejects: a directory that does not exist, or a file that cannot be read, is bad_request with what: 'dir' and node's error as cause (before 0.2.0's Result contract was enforced here, they rejected as node:fs rejects).
Each object once. push (client.push, and every command that pushes through it: editFile, commitChanges, pushTree, merge, rebase) sends a whole object that objects holds more than once a single time: the first copy, in its place, and an ofs base that named a repeat names the kept copy. A pack with one object twice is refused by a strict receiver (git index-pack --strict: "The same object … appears twice in the pack"). So PushResult.entries, the span's git.push.pack.objects (and its git.push.pack.* sizes) and the git.push.object events count the objects sent, which can be fewer than objects.length. Delta entries are sent as given; planPush returns the list as given; pushPack sends your pack untouched.
Push a pack you already have (pushPack)
A mirror relay, a bundle import or a pack cut from another pack does not need its objects in memory. pushPack sends a complete pack from a ReadableStream, with push's command checks, capability checks and report handling:
const r = await pushPack(transport, {
commands: [{ ref: 'refs/heads/main', oldOid: ZERO_OID, newOid: head }],
pack: stream, // header, entries, trailer; read once
length: packBytes, // optional: the pack alone, without the commands
atomic: true, // optional, checked against the advertisement (as are pushOptions)
});Memory is about two of the stream's chunks, whatever the pack's size (256 MiB measured, test/push-pack.test.js). length, when given, is checked against maxPackBytes before anything is sent and against the bytes as they go. Without it, the count is enforced while sending: the chunk that would cross maxPackBytes is never sent. The request is chunked either way (no Content-Length).
A refusal before the request (a bad command, an over-cap length, a capability the server does not advertise) leaves the stream unread and unlocked, and the caller still owns it. So does a request that failed before the transport pulled the first chunk of its body (a signal that had already fired, a connect or DNS failure, a fetchImpl that rejects without reading the body, an HTTP answer that arrives with the body still unpulled): the server received no command list, so no ref can have moved, and the result is that failure itself, not ambiguous: aborted, timeout, network, or the answer's own code (auth for 401/403, not_found for 404, rate_limited for 429, upstream_5xx, http for a redirect, not_git for a 200 with the wrong content-type); the stream stays unread and unlocked unless the transport cancelled the body itself. From the first pull of the body the stream is spent: it is never retried, a request that did not finish it cancels it (asked once, with the failure as the reason when there is one, and never waited for: a stream whose read() or cancel() never settles does not hold pushPack past the server's report, your abort or a timeout), and every failure is ambiguous, with the first cause in original (bad_request for a wrong length, limit_exceeded for the cap, internal for a failed source). The last chunk is released only after the source has ended and its length has passed, so a refused pack never reaches the server whole. Ply does not parse or hash the pack: a corrupt one is refused by the server's report.
Custom exchanges on a transport (frames)
Every command in ply is one exchange on a transport: t.frames(service, body, span, hints) POSTs body to service and yields the response as pkt-line frames; t.advertise(service, span) is the info/refs GET. A request ply has no call for (a receive-pack with its own capabilities, a v2 command of your own) goes through the same method instead of a raw fetch(), and so gets what ply's calls get:
- auth as configured on the transport, and scrubbing: no form of the credential reaches a span, a URL attribute or an error message, even one the server echoes back;
- remote text made printable, at the sites listed here: text the server wrote is cut to at most 1024 UTF-16 units and then has every control, format and lone-surrogate character written as
\uXXXX(tab and newline stay in running text; the rule is SAFETY.md I43) before it reaches an error message at these sites: anERRline (capabilities, ls-refs, fetch), band 3 (fetch; push, in theambiguousmessage), the HTTP error body (200 units) and content-type, a non-v2 first line, a refused acknowledgment line and a malformed ls-refs or receive-pack advertisement line (60 units), the section names of a fetch answer that has no packfile section (60 units each, at most 8 names), and the too-large push reason. The span attributegit.push.band2.tailis escaped the same way. These still carry the server's text as received, so escape them before printing: the span attributesgit.push.remote.messages,git.push.ng.reason,git.fetch.sectionsand the fetch progress text (git.sideband.progress.tail),hookOutput, thelinesandrejecteddetail fields, the ng reason quoted in apush_rejected,cas_conflictorpush_partialmessage, and the object-format name in anunsupportedmessage. A credential the server echoes in anERRline (capabilities, ls-refs, fetch) or in band 3 (fetch, push) is redacted before the text is cut, so a cut that falls inside it leaves no part of it in the message;v2Step,sidebandStepandparseCapabilitiesV2take the scrubber as an optional last argument (none by default) for a caller that drives them itself. A message that quoted such a character raw before now shows the escape; - spans:
framesfills the span you pass withgit.service,git.request.bytes(aStreamBody'slength),http.request.method,url.full(redacted),http.response.status_code,git.response.bytes,git.response.first_byte_msand the rest of the HTTP attributes (the telemetry contract below); - the transport's redirect policy, limits, timeouts (first byte, idle) and
signal; - typed errors: a non-2xx, a foreign content type, a timeout, a network failure and a broken pkt-line are each a
PlyError(auth,not_found,http,not_git,timeout,network,protocol, ...), thrown from the iteration (results never throw, streams error).
What it leaves to you: the request's bytes (pkt framing, capabilities, a pack), what the reply means, and ending your span. body is bytes or a StreamBody { stream, length }, read at the request's pace as it goes out (chunked). length is the figure the span reports, not a check: frames sends what the stream yields, so a stream that yields a different count, or bytes that are not a whole pack, is yours to catch (measured in the test: 7 extra bytes after a pack's trailer land, 7 short is git's unpack failed). A stream that errors midway ends the request: on Node, fetch rejects and frames throws network with your error on its cause chain; on workerd an errored request body can end as if it were complete. So a pack you are still producing should hold its last chunk back until it has checked the whole, and keep its own failure to report, as pushPack does (streamSource in src/packwrite.ts). Get a transport from createTransport(url, opts), GitHttp.create(url, opts) (.t), or transportFrom(record) for a transport of your own. A receive-pack with a streamed pack, the report read with the exported step functions (this block is executed by test/custom-exchange.test.js against git http-backend, with the error paths beside it):
// custom-exchange: receive-pack
import { createTransport, Tracer, KIND, ZERO_OID, TYPE, buildPack, hashObject, encodeTree, encodeCommit } from 'ply';
import { frames } from 'ply/transport';
import { pushBody, streamInit, streamStep, streamFinish, classifyReport } from 'ply/push';
// what to send: a root commit holding one file
const file = new TextEncoder().encode('hello\n');
const tree = encodeTree([{ mode: '100644', name: 'hello.txt', oid: hashObject('blob', file) }]);
if (!tree.ok) throw tree.error;
const made = encodeCommit({ tree: hashObject('tree', tree.value), author: 'Me <me@example.com> 1700000000 +0000', message: 'hello\n' });
if (!made.ok) throw made.error;
const commit = hashObject('commit', made.value);
const objects = [{ type: TYPE.BLOB, data: file }, { type: TYPE.TREE, data: tree.value }, { type: TYPE.COMMIT, data: made.value }];
const spans = [];
const t = createTransport(url, { ...opts, tracer: new Tracer({ onEnd: s => spans.push(s) }) });
if (!t.ok) throw t.error;
// the request: the commands as pkt-lines and a flush, then the pack, as one stream of known length
const commands = [{ ref: 'refs/heads/main', oldOid: ZERO_OID, newOid: commit }];
const prefix = pushBody({ commands, caps: ['report-status', 'side-band-64k', 'agent=me/1'] });
if (!prefix.ok) throw prefix.error;
const { pack } = await buildPack(objects);
const stream = new ReadableStream({ start(c) { c.enqueue(prefix.value); c.enqueue(pack); c.close(); } });
const body = { stream, length: prefix.value.length + pack.length };
const span = t.value.tracer.start('custom receive-pack', { kind: KIND.CLIENT, scrub: t.value.scrub });
let reply = streamInit(true); // side-band-64k: the report in band 1, progress in band 2
try {
for await (const f of frames(t.value, 'git-receive-pack', body, span)) {
const stepped = streamStep(reply, f);
if (!stepped.ok) throw stepped.error;
reply = stepped.value;
}
} catch (e) { span.error(e); throw e; } finally { span.end(); }
const done = streamFinish(reply);
if (done.tag !== 'report') throw new Error(`no report: ${done.why}`);
const report = classifyReport(done.lines, commands); // { tag: 'statuses', refs: [{ ref, ok: true, reason: '' }] }
if (report.tag !== 'statuses' || !report.refs.every(r => r.ok)) throw new Error(`refused: ${JSON.stringify(report)}`);encodeCommit is held to the reader. encodeCommit({ tree, parents?, author, committer?, encoding?, extra?, message? }) returns a Result and never throws. As encodeTag does, it parses what it built with parseCommit and returns bad_request (what: 'commit', or the field that would not read back) for a commit git or ply would not read back as the one given: an author or committer that is not an ident line git fsck accepts (Name <email> <seconds> <+hhmm>; build one with ident(validateIdent(…))), an extra line that starts tree , parent , author , committer or encoding (pass the encoding as encoding), and an empty extra line (it would end the header and turn the lines after it into message text). Before this, those inputs returned ok with bytes git hash-object refuses or parseCommit reads as pack_corrupt. Every commit it returns is stored by git hash-object -t commit byte for byte.
Stability. Transport (kind, url, tracer, parent, limits, signal, quirks, objects, scrub, frames, advertise) is the public contract every command is written against, and the ply/transport exports frames, advertise and transportFrom are public API: a change to their shape is a breaking change, named in the release notes (ply is pre-1.0, so a minor version may carry one). Frame and StreamBody are part of it. The step functions used above (pushBody, streamInit/streamStep/streamFinish, classifyReport, pktStep, v2Step, sidebandStep) are public too, but they are protocol codecs: they follow git's wire format, and their states are opaque records you pass back, not fields to read. The HTTP implementation behind frames (createTransport's internals, its retry and redirect memo) is not: depend on what it does, as described here, not on how. Before writing an exchange, check for the call that already does it: a pack you have is pushPack, objects are push, a fetch is packStream/fetchPack, refs are lsRefs, capabilities are discover/receiveCaps. Those add what a raw exchange does not: command and capability checks, a push's outcome rule (a report read exactly as git writes it, everything else ambiguous), and the cancel-and-release rules for a streamed pack.
Push a whole local repository (history, no git binary)
pushRepo(dir, url, { refspecs?, all?, tags?, force?, dryRun?, thin? }, opts) is git push <url> <refspecs> from a machine with Node and no git: it reads dir's .git itself (a work tree, a linked worktree or a bare repository: loose objects inflated and hash-checked, every packfile parsed and resolved, packed-refs and loose refs, HEAD), asks the remote for its refs (one ls-refs), and sends one receive-pack request for every command. Example: examples/push-repo.mjs.
import { pushRepo } from 'ply/repo-node'; // Node: reads .git (node:fs)
const r = await pushRepo('./repo', url, { refspecs: ['main', 'v1.0', '+wip:refs/heads/backup', ':stale'] }, { auth });
if (r.ok && r.value.upToDate) console.log('Everything up-to-date'); // nothing was sent
await pushRepo('./repo', url, { all: true, tags: true }, { auth }); // every branch and tagRefspecs are git's: src, src:dst, +src:dst (forced), :dst (delete). src resolves as git resolves a name (x, refs/x, refs/tags/x, refs/heads/x, refs/remotes/x, refs/remotes/x/HEAD; a name given in full or from refs/, a branch and a tag outrank a refs/remotes/ match, as in git's count_refspec_match, so a branch foo beside a remote named foo is the branch, and two matches of the same rank, a branch and a tag, are bad_request; a ref directly under refs/, such as refs/stash, is not counted, as git's one_local_ref leaves it out, so a branch stash in a repository that has run git stash is the branch, and such a ref is the source only when it is named in full or nothing else matches; tested against git push --dry-run), HEAD is the current branch, a 40-hex id needs a full dst, and a missing dst is the same ref. Under refs/, an entry that is not a ref to git is not one to pushRepo: a file or directory whose name starts with . or ends in .lock, and a file whose full name git check-ref-format refuses (Finder's .DS_Store, bad~name), are left out whatever they hold, as git push leaves them out (tested against git push --dry-run); a well-named ref file that holds neither an id nor ref: <name> is still bad_request, what: 'ref'. A loose ref that is a symbolic link is read as git reads it: a link whose target text is a ref name (refs/heads/main) is a symbolic ref to that name, any other link is the file it points at, and a link that points nowhere is not a ref (tested against git push --dry-run). One known difference from git: while a symbolic link to a directory exists anywhere under refs/, every pushRepo from that repository fails with bad_request, what: 'ref', and the link as path, even a push of an unrelated ref, where git walks into the link and pushes (a link can loop, so ply refuses the repository by naming the link rather than leave the refs behind it out). A short dst is the branch or tag the remote has by that name, else the kind of src. With no refspecs (and neither all nor tags) the current branch goes to the same name. The pack is what the remote lacks: everything reachable from the new tips minus everything reachable from the remote's refs that the local repository has (exactly git rev-list --objects <new> --not <remote refs>; gitlinks are not followed). A non-fast-forward update of a branch, an update of a ref whose tip the local repository lacks (git's "fetch first") and any change to an existing tag are refused before anything is sent — not_fast_forward, naming every refused ref, the same code a server's own non-fast-forward refusal carries — unless the refspec has + or force is set; none of the other refs are sent then either. Refs already at their target are current; when every ref is, the result is upToDate and no receive-pack request is made. dryRun makes the same decisions and counts the objects, and sends nothing. The result: { upToDate, dryRun, updates: [{ ref, oldOid, newOid, kind: 'create' | 'update' | 'force' | 'delete' }], current, objects, deltas, thinDeltas, rawBytes, packBytes }; spans git.push_repo → git.push_repo.read, git.push_repo.plan, git.receive-pack.
The pack is delta-compressed (planDeltas, encodeDelta in ply, a block-hash copy/insert generator in the shape of git's diff-delta.c): each tree and blob is tried against the previous version of the same path in the pack, then of the same file name (a rename), as an OFS_DELTA, kept only when it is under half the object, with chains of at most 50. Commits and tags are stored whole. thin: true also deltas the first version of each path against the remote's copy (REF_DELTA): git push sends thin packs and receive-pack completes them (index-pack --fix-thin), but ply cannot prove a host it has not seen does, so it is opt-in. Measured on this repository's own history (test/push-repo.test.js, against a stock git http-backend; git push's pack is git pack-objects --revs --thin --delta-base-offset): HEAD~50 to an empty remote, 957 objects, 1,394,379 B against git's 1,546,809 B (every object whole, as before: 4,513,180 B); then HEAD on top, 1,576 objects, 845,188 B thin against git's 856,093 B (1,512,574 B without thin, against git's 1,443,193 B non-thin; whole: 8,517,408 B).
Memory: every packfile is resolved in memory (no .idx is read), so it suits repositories up to a few hundred MB. It fails closed with limit_exceeded: the objects held by maxInflatedTotal (256 MiB by default), their count by maxPackObjects, each by maxObjectSize, the pack sent and each local packfile by maxPackBytes (128 MiB by default; a local .pack is held whole while it is parsed, so one past the bound is refused from its size, before a byte of it is read: what: 'local pack bytes'; one exactly at the bound is read), the refs by maxRefs. For a larger repository raise all three of maxInflatedTotal, maxPackObjects and, when a single .pack is over 128 MiB, maxPackBytes: the process then holds that much, so this is for a repository that fits in memory. One that does not goes through the range-reader pipeline instead (scanPackIndex, resolvePackRange, planPackBatches, packSubset over a RangeSource, below), which holds no pack whole. With maxPackBytes raised past 2 GiB a pack of 2 GiB or more is read in pieces of at most 1 GiB (node aborts the process on a single read of 2^31 bytes or more), and a file the runtime cannot allocate one buffer for is limit_exceeded (what: 'local pack buffer bytes', got the file's size), never a crash. Every other file pushRepo reads whole is bounded the same way, from its size, before a byte of it is read (one exactly at the bound is read; limit_exceeded with got the file's size): a loose object file by the longest zlib stream an object of maxObjectSize can have (zlibBound(maxObjectSize + 32); what: 'local loose object bytes'), packed-refs and config by maxLsRefsBytes (128 MiB by default, the bound a ref listing has on the wire; what: 'local packed-refs bytes', 'local config bytes'), and the one-line files, a loose ref file, HEAD, commondir and a .git file, by 65 520 bytes (the pkt-line maximum, not configurable; what: 'local ref file bytes', 'local HEAD bytes', 'local commondir bytes', 'local .git file bytes'). A text file within a raised bound that the runtime cannot hold as one string (node: 512 MiB) is limit_exceeded too (what ending buffer bytes), so none of these files makes pushRepo reject. One of them that cannot be opened or read is treated as absent, as before. A packfile the file system will not give (EACCES, EIO, …) is unsupported with kind: 'filesystem', what: 'local pack', the path, and the node:fs error as cause, never a rejection. Refused with bad_request and what: SHA-256 repositories (objectFormat), reftable (refStorage), partial clones (partialClone), objects/info/alternates (alternates), shallow repositories (shallow), a ref file that is not an id or a symbolic ref (ref); a missing object is bad_request (what: 'object'), a loose object that does not hash to its name pack_corrupt.
Mirror one ref between remotes
syncRef(srcUrl, dstUrl, { ref, dstRef?, force? }, opts) keeps dstRef (default ref) on the destination equal to ref on the source: git fetch <src> <ref> then git push --force-with-lease=<dstRef>:<dstTip> <dst>, with no clone (src/sync.ts). One ls-refs on each side; equal tips are in_sync and nothing else is sent. Otherwise one fetch from the source with the destination's tip as the have, and one receive-pack command whose old id is that tip (zero: a create). The pack pushed is the source's pack as received, delta for delta and never thin, so it holds only what the source computed the destination lacks: nothing reachable from the destination's tip when the source has that commit (a source that does not NAKs the have and sends the whole history, which is still correct). Each remote has its own auth, fetchImpl, quirks and transport under opts.src and opts.dst (a top-level auth names neither and is bad_request); tracer, parent, signal, limits (maxPackBytes bounds the pack both ways) and verify are shared. Example (run as written by test/sync-ref.test.js):
// sync-ref example
import { syncRef } from 'ply';
const r = await syncRef(srcUrl, dstUrl, { ref: 'refs/heads/main' }, {
src: { auth: { token: process.env['SRC_TOKEN'] } }, // read with one credential
dst: { auth: { token: process.env['DST_TOKEN'] } }, // write with another
});
if (!r.ok) throw r.error; // not_fast_forward: the source was rewritten (force: true follows it); cas_conflict: the mirror moved
if (r.value.outcome === 'in_sync') console.log('in sync at', r.value.oid);
else console.log(r.value.outcome, r.value.from, '->', r.value.to, `${r.value.objects} objects, ${r.value.pushBytes} B`);The result is { outcome: 'in_sync', ref, dstRef, oid } or { outcome: 'created' | 'updated', ref, dstRef, from, to, forced, objects, pushBytes }. An update that is not a fast-forward (a rewritten or diverged source, a destination ahead of it) and any change to an existing tag are not_fast_forward before anything is pushed, unless force: true, which pushes the source's tip with the same compare-and-swap. A push that loses the race to another writer is cas_conflict with expected the tip ply read and actual the destination's tip read back (null: deleted), as createBranch and deleteBranch report one. Spans: git.sync_ref → two git.upload-pack ls-refs (one per remote), git.upload-pack fetch, git.receive-pack.
One commit from a change list
commitChanges(url, { ref?, base?, changes, author, committer?, message, time? }, opts) writes one commit. changes is applied in order: create (refuses a path that already exists; write overwrites, which is what git add does), edit (exactly one non-overlapping match, or match_count), delete (a file or a directory; empty directories are pruned), rename. Modes are 100644, 100755 and 120000. A mode you give always wins. With no mode, a write over an existing regular file keeps that file's mode (a 100755 script stays executable, as rewriting a file's content does in git), and a create, or a write to a new path or over a symlink, is 100644; to clear the executable bit pass mode: '100644'. So a mode-less write of identical bytes over a 100755 file changes nothing (noop on an existing ref). A single edit of an existing blob goes through editFile, so a large file stays a stream; every other list is an in-memory tree of the paths it touches.
ref defaults to the remote HEAD, born or unborn (an empty git init --bare -b main commits refs/heads/main; a symref to a branch with no commit does the same). A detached HEAD is bad_request. A server that will not name an unborn HEAD is not_found. Pass ref for either. base defaults to that ref's tip. Another ref creates ref from it (an annotated tag is the commit it names, here and as an editFile base) and is cas_conflict (expected the zero id, actual the tip) when ref already exists. A 40-hex base is that commit — lowercase, as everywhere else in ply — and bad_request when the target exists at a different tip. The compare-and-swap is the one the call read first: a ref that was absent then is pushed with the zero old id on every path (a single streamed edit too, from a ref or a 40-hex base), so a ref another writer creates meanwhile, even at the base commit, is cas_conflict, never a commit on top of it reported as created. The zero id is bad_request before any request.
An absent ref with no base is a root commit. A result tree equal to the parent does not write an empty commit: an existing ref returns { outcome: 'noop' }; a new ref is bad_request (nothing to commit) and stays absent. head is the tip the ref must have, or the zero id when it must be absent; a mismatch is cas_conflict and is not retried. A lost push reads the ref back, so actual is the oid that won. With no head a commit on a ref that existed is last-writer-wins, the same way for a single streamed edit and for an in-memory change list: when its push loses to another writer (the ref moved, or was deleted) the call reads the ref again and redoes the commit once against what is there (git.commit.attempt is 1 on the span). A ref deleted meanwhile under a 40-hex base is created again from that commit (created: true, oldOid: null); a ref that moved is committed on its new tip, or is bad_request under a 40-hex base it no longer matches. With head, the same race is cas_conflict (actual null for a deleted ref) and the ref stays as the other writer left it. author.time and committer are separate stamps. import { commitChanges } from 'ply'.
editFile accepts the same 40-hex base (the commit to edit) and an optional committer. A base ref that is an annotated tag, or a tag of a tag, is the commit git peels it to (where git branch <name> <tag> starts the branch). A commit id that is not the tip of an existing ref is bad_request.
Checking out a whole tree (no git binary, no clone)
checkoutTree(url, { ref, path? }, opts) → { ref, commit, tree, path, entries, files }: ls-refs → one blob:none fetch of the commit (deepen 1: the commit and every tree under it — on Artifacts, the only filter it serves anyway) → the blobs, up to batch (default 1,000) wants per request. entries is every non-tree entry under path as [{ path, mode, oid }] in git ls-tree -r order, paths relative to path; files is an async iterator of { path, mode, oid, size, stream }. Modes are git's canonical 100644, 100755, 120000 (a symlink: the stream is its target) and 160000 (a gitlink: size 0, stream null, the submodule's commit is not in this repository).
import { checkoutTree } from 'ply/checkout'; // Workers-safe
import { checkoutDir } from 'ply/checkout-node'; // Node: writes a directory (node:fs)
const r = await checkoutTree(url, { ref: 'main', path: 'site' }, { auth, tracer });
if (r.ok) for await (const f of r.value.files) if (f.stream) await env.BUCKET.put(f.path, f.stream, { httpMetadata: { contentLength: f.size } });
const done = await checkoutDir(url, { dir: './out', ref: 'v1.2.0' }, { auth, tracer }); // == git clone, minus .gitEvery object is checked against its oid: a blob batch is delta-resolved and keyed by computed hash before any file is yielded (an object nobody asked for is pack_corrupt); a blob fetched alone streams through readFile's verifier (the stream errors rather than ends on wrong bytes). A batch that hits maxPackBytes, maxInflatedTotal or maxObjectSize is split in half and refetched, down to single blobs, which stream in O(1) memory (a single blob whose pack is over maxPackBytes is limit_exceeded: every fetch, streamed or not, delivers at most that much pack); a host that refuses a many-wants fetch (an HTTP error, ERR) gets one blob per request from then on (quirks.blobWants = 'single'). A wrong blob is never a reason to fall back. Entries walked are bounded by maxPackObjects (a tree reused at many paths cannot multiply past it), depth by maxPathDepth, and a tree naming one entry twice (a symlink a beside a directory a) is pack_corrupt.
Measured against git http-backend (test/checkout-tree.test.js, 22 entries: nested and unicode paths, exec bits, four symlinks, a gitlink, a 3 MiB blob, one blob at two paths): 3 requests (ls-refs, trees, blobs), the same behind an Artifacts-like blob:none-only proxy, against 72 for the per-file loop (readCommit → listTree per directory → readFile per blob, as the first examples/checkout-tree.mjs did, before checkoutDir). A commit oid as ref skips ls-refs.
checkoutDir / writeFiles(dir, files) lay the files out as git clone does — diff -r --no-dereference identical to a clone of the same ref, permission bits included (100755 is created 0777 & ~umask, others 0666 & ~umask; symlinks never followed; a gitlink is an empty directory). dir must be absent or empty. Paths go through validatePath again (no .., absolute, empty or .git component); each directory is made one level at a time and must be a real directory (a symlink there — one this checkout made, or the same name on a case-insensitive filesystem — is bad_request, what: 'checkout path'); files are opened O_EXCL, so nothing is overwritten or written through a link. A file whose stream fails verification is removed before the error is rethrown; a checkout that throws leaves dir partial. No index, no .git, no working-tree updates: a one-shot materialisation.
Hosts that refuse filter tree:0 (Cloudflare Artifacts)
Artifacts advertises fetch=filter but answers anything other than blob:none with 400 … only blob:none is supported. ply learns that from the answer (not the host name), sets quirks.treeFilter = 'blob:none' on the transport and asks for blob:none from then on: a commit want then returns every tree of the commit, which ply delta-resolves, hash-checks and keeps (up to limits.maxHarvestBytes) so the deeper levels cost no round trip. The 400 is paid once per remote: a call that passes no quirks uses a record ply keeps per remote (origin + path, never the credential or query; the 256 most recently used remotes, per process or Workers isolate), and concurrent first requests wait for the one that finds out instead of each paying it. A quirks object you pass wins and is filled in place (pass a fresh {} to opt a call out of the shared record); forgetQuirks(url) drops one remote's record and forgetQuirks() all of them (a server reconfigured, a test faking several servers at one URL). A stale record costs bytes, never correctness. Cost: measured 8.9× the bytes of tree:0 on a small repo; a merge-base walk ships every tree of every commit in its window. Spans say so (git.fetch.filter.fallback, git.fetch.wide.extra_bytes). A server whose upload-pack advertises no filter at all (a stock git http-backend: uploadpack.allowFilter is off by default) gets quirks.treeFilter = 'none': a filtered fetch that comes back empty triggers one advertisement read, and with no filter on its fetch= line the request is retried unfiltered (discover() sets it too; an advertisement that lists filter again turns it back to tree:0). Unfiltered fetches carry objects a filter would have left out, so reads there cost more bytes; the results are the same. Artifacts rejects stale ref updates as ng <ref> stale ref, which is cas_conflict. Other observed Artifacts behaviour: an unknown want is an HTTP 500 (not ERR), HEAD follows the first-pushed branch and can be unborn, a receive-pack GET carrying Git-Protocol: version=2 is answered with a v2-style list that names no push capabilities (so ply sends that header for upload-pack only, as git does), a push is capped at 64 MiB (67,108,864 bytes) of request body, pack plus command prefix, HTTPS only. Its limits page also caps a push at 50,000 objects and 1 MiB of ref updates, and a file at 32 MiB.
Branches and merging (git operations only)
editFile(url, { ref: 'refs/heads/feature', base: 'refs/heads/main', … })builds the commit onbase's head and createsref(zero old-oid: the CAS means "must not exist yet").mergeBranch(url, { ref, from, author })landsfromintoref: merge-base via commit-only packs, thenup_to_date/fast_forward(empty pack — the server has every object) / a merge commit with parents[ours, theirs]from a three-way tree merge (git's trivial-merge rules per directory, only differing subtrees fetched). A file both sides changed is merged line by line with a port of git's xdiff (linemerge.js: histogram diff with its classic-Myers fallback, group compaction, zealous conflict refinement — what merge-ort runs), so a clean result is byte-for-byte git's; anything else ismerge_conflictwith the paths and a reason per path (content,binary,too large to merge,undecided,possible rename …). Git changed its compaction in 2.54;rediff: 'myers'(default) matches git ≥ 2.54,'skip'older git,'undecided'conflicts wherever the two differ..gitattributesmerge drivers apply when you say which tree supplies them —attributes: 'ours'(whatgit mergein a worktree reads),'theirs','base', a ref or commit (attr.tree), ornull(default: none, as git ≥ 2.46 does in a bare repository):-merge/binaryconflict,merge=unionkeeps both sides. The merge base is git's (merge-base --all); a criss-cross history with two bases is refused rather than merged against one. The remaining supersets are renames (no rename detection: the guards conflict instead) and criss-cross. The rename guard is by path, not by similarity: a path neither side holds any more (deleted on both sides anywhere in the tree, including inside a directory both sides changed to the same tree, or a file one side replaced by a directory of its name) beside any added path ismerge_conflict, whether or not git would pair them as a rename. So a merge, rebase or cherry-pick whose delete the target already has is refused when either side also added a file (git: clean, or an empty pick).conflictslists each path once, with the reason the tree walk gave it if it had one. A merge with no directory both sides changed identically reads no tree for this. One with such directories can cost extra tree reads even when it is clean: the guard must rule out a path lost on both sides inside them beside a path one side alone added or removed, so it reads either those directories (base's copy and the shared one) or the directories only one side changed (base's copy and that side's), whichever are fewer, and the other set only if the first cannot rule it out; sibling directories 8 at a time, no tree twice (40 identically changed directories beside 40 one side edited: 83 tree reads, not 3).fastForwardOnly,noFastForward,signer,verify,limits.maxMergeBlobBytes(8 MiB). The line merge's work is bounded too: it counts its diff steps and stops atlimits.maxMergeWorksteps per merged file (2^32 inDEFAULT_LIMITS, 2^26 inWORKER_LIMITS), answeringtoo large to merge— a file whose histogram diff goes quadratic (every adjacent pair of lines swapped: ~0.75 n² steps, so past ~75,700 lines at the default and ~9,450 in a Worker) is refused at the budget instead of merged in minutes;mergeLines/diffScripttakemaxWork(the same budget, absolute, for that call) and ameter({ steps }) to change and read it. The count is kept inside the call, from zero: themeteris only written (itsstepsis set to that call's total on every return, refused or not, and to 0 when the call returns before any diff: binary content, an input overmaxBytes,driver: 'binary') and never read, so one meter reused across files, or one that is not an object (an array is one and gets astepsproperty; a function is ignored), changes no result, and a meter whose write throws (a setter, a Proxy'ssettrap, a revoked Proxy) is dropped with the result unchanged; amaxWorkthat is not a non-negative finite number (NaN,Infinity, a negative, a string) reads as the default, and alimits.maxMergeWorkthat is not one isbad_requestlike any other limit. Neither function throws on anymeterormaxWorkvalue (an unknowndriverstill throws). The count covers the classic-Myers fallback's whole work as well (the class counts, the trim, the cleanup's neighbour scans of up to 100 lines each way, every diagonal, snake and heuristic pass of the search, each box's trim and marks), not only its diagonals, so a low-variety file (a few distinct lines, each more than 64 times) spends the budget as it spends CPU: its counts are higher than they were (two unrelated 10,000-linea/b/cfiles: 5,370,282 steps for the diff) and such a file reachestoo large to mergesooner.createBranch(url, { ref, from }),deleteBranch(url, { ref, expected? })andcreateTag(url, { name, target, message?, tagger? })manage refs by URL (src/refops.ts): one receive-pack command each, no objects except an annotated tag's tag object.from/targetis a ref name (resolved asreadCommitresolves one; an annotated tag is peeled) or a 40-hex commit id the server must have. A ref that already exists iscas_conflict(expectedthe zero id,actualits tip), as a create is ineditFile; a delete whoseexpectedis not the tip iscas_conflictbefore anything is sent, and one that loses a race to another writer after ls-refs iscas_conflictwithactualthe ref read back (null only when it was deleted); an absent ref isnot_found; what the server refuses (deleting the branch HEAD names) is itspush_rejected.verify: truereads a created ref back. On a transport you already hold:fastForward(t, { ref, from, to })anddeleteRef(t, { ref, oid }).rebaseBranch(url, { ref, onto, committer })replays the branch's linear chain ontoonto's head (per commit: three-way of parent-tree / new-tip / commit-tree; author and message kept, committer ours, signatures dropped as git does) and force-updates the branch with its old tip as the CAS; commits that become empty are dropped as git's--empty=dropdoes and listed indropped. One difference fromgit rebasestands: git leaves out a commit whose patch id equals a commit already inontobefore it replays anything (its default,--no-reapply-cherry-picks); ply computes no patch ids and replays every commit, which isgit rebase --reapply-cherry-picks. The results are equal while the upstream copy is in place (the replay comes out empty and is dropped) and differ when upstream applied the patch and later reverted it: git leaves the commit out, ply applies it again (and a replay git would have skipped can conflict).squash: truemakes one commit; its default message is the replayed messages joined by blank lines (whatgit rebase -iwrites for pick, squash, …).cherryPick/revertCommitare the same primitive with one commit. Merge commits in the chain →not_linear. A root commit (no parent) is picked and reverted against the empty tree, as git does.empty: 'keep'writes the commit when the result tree is already the target's (git cherry-pick --keep-redundant-commits, which also keeps a commit that was empty to start); the result isoutcome: 'kept_empty'. The defaultempty: 'stop'reportsoutcome: 'empty'and writes nothing. The kept commit is built by the same path as a non-empty one: a cherry-pick keeps the picked author line (name, email, time, zone) and message, a revert uses the reverting author and git'sRevert "<subject>"message, and the committer stamp is the caller's.One primitive underneath all of it — the three-way tree merge, with the line merge for files both sides changed — with different arguments:
op base ours theirs commit merge merge-base tree main branch parents [main, branch]rebase (per commit) commit's parent tree new tip commit parent [new tip]squash merge-base tree main branch tip parent [main]cherry-pick commit's parent tree (empty tree, if the commit is a root) target commit parent [target]revert commit tree target commit's parent tree (empty tree, if the commit is a root) parent [target]A pull request is a GitHub API object around such a branch; that call is outside this library.
SSH
SSH transport removed 2026-10-31; history on branch archive/ssh.
Guards and policy
- LFS pointers are refused (
lfs_pointer): the file's content is in the LFS store, and editing the pointer corrupts it. The check is on the blob's first bytes (version https://git-lfs.github.com/spec/v1), which are streaming past anyway, so it costs nothing;allowLfsPointer: trueopts in to editing the pointer itself. - Signed commits: pass
signer(fromed25519Signer({ privateKey, publicKeyRaw })orgenerateSigner()) and the commit carries an SSH signature (PROTOCOL.sshsig, Ed25519 via WebCrypto — Workers and node). Verified bygit verify-commitandssh-keygen -Y verifyintest/sign.test.js; satisfies "require signed commits" branch protection with the public key registered as a signing key.signCommit(commitBytes, signer)andwithGpgsig(commitBytes, signature)sign any encoded commit, including one with no body section (encodeCommitwith nomessage): the signed object without itsgpgsigheader is the input byte for byte. (Before, such a commit came back with a blank line added after the headers, sogit verify-commitrejected its signature.) - We identify as
ply/0.2.0, not as git.
Layers
operations edit · push tree · merge · rebase · cherry-pick · revert operation.js: root span, transport, outcome, verify rule
commands lsRefs · packStream/fetchObject · fetchPack/negotiate · push · discover · receiveCaps free functions over a transport
transport the contract (transport.js): t.frames(service, body, span, hints) · t.advertise(service, span)
implementation: http.js (one POST per command)
protocol pure step functions: pktStep · v2Step · spStep · scanStep · streamStep · reportStep · threeWay · decideHead
codecs pktline · inflate · sha1 · objects · pack (delta/build) · validate
errors errors.js: every code, its retry policy; errors-doc.js: what each meansEach layer is testable without the one below it, and test/bundle.test.js asserts the dependency direction. Transport hints are neutral ({ bypassCache }), not headers; transport-specific detail goes under http.*, the neutral facts under git.transport, git.request.bytes, git.response.bytes, git.response.cache.
Telemetry conventions (enforced by test/pure.test.js and test/span-contract.test.js)
- Span names:
git.<service> <command>for wire round trips (git.upload-pack ls-refs,git.upload-pack fetch,git.receive-pack);git.<op>for operation roots (git.edit,git.commit,git.push_tree,git.checkout,git.read_log,git.merge,git.rebase,git.cherry_pick,git.revert,git.branch_create,git.branch_delete,git.tag_create);git.<op>.<phase>for their children. - Attribute keys: dotted lowercase under
git.http.url.server.mem.error.ply.exception.. - Every trace root (operation roots and the spans that follow them, below) carries
<name>.outcome(ok,noop,fast_forward,cancelled, …, or the error code). - On the HTTP transport (
createTransport), every wire span carriesgit.transportandserver.address.git.request.bytesis on POST spans only (git.upload-pack ls-refs,git.upload-pack fetch,git.receive-pack): the request body's length, set before the POST is sent (so a failed POST carries it too; ongit.receive-packit is then set again to the bytes actually sent), and absent when the GET ply makes before a POST fails first.git.response.bytesis set only when a response body was read to its end: on the GET spans (git.upload-pack discover,git.receive-pack advertise) once the advertisement is read whole, and on a POST span once the POST's response is read whole. A GET span never carriesgit.request.bytes, and an exchange that fails before its body is read whole (a non-2xx, a wrong content-type, a body over the cap, a timeout, a cut stream) sets nogit.response.bytesof its own. The GET ply makes on a POST's own span (before the first POST underfollowRedirects: 'initial', and before the re-send after a stale redirect memo; after the POST, when ls-refs gets an empty answer and when a push is refused at its status line) setsgit.response.bytesthere to the advertisement's length once it is read whole. Before the POST: a POST that reads its response whole replaces it with its own, and a POST that fails keeps the GET's count; the method is set back toPOSTfor the first POST underfollowRedirects: 'initial', but a span re-sent after a stale redirect memo ends withhttp.request.method(GET, from the re-settling GET) beside the re-sent POST's status,git.request.bytesandgit.response.bytes(the re-send does not set the method again). After the POST: the GET's count,http.request.method(GET) and status are what the span ends with. A transport you pass in sets what it sets.
Telemetry contract
Span names, kinds, parent/child structure, links and attribute keys (with their value types) are public API. test/span-contract.json is the contract: test/span-contract.test.js runs every operation (editFile, commitChanges, pushTree, checkoutTree, readFile, listTree, readCommit, mergeBranch, rebaseBranch, cherryPick, revertCommit, createBranch, deleteBranch, createTag), and the wire spans against real git and fails, naming each span and key, when what is emitted differs from the file. Values are not part of the contract; repeated siblings (three fetches) are one node, so round-trip counts are not either.
- Removing or renaming a span or key, changing a value's type, or moving a span is a breaking change for consumers' dashboards and alerts, and is called out as one in the PR and the release notes.
- Adding one also fails the test until the snapshot is regenerated (
npm run test:spans:update), so every addition is visible in review as a diff oftest/span-contract.json.
In-process consumers: onEnd
An exporter gets each span as one OTLP/JSON ExportTraceServiceRequest object, { resourceSpans: [{ resource, scopeSpans: [{ scope, spans: [span] }] }] } (an object, not a string: JSON.stringify it for a JSONL file or a collector's body; consoleExporter does). Telemetry never changes an operation's outcome: a throw or a rejected promise from exporter or onEnd is caught, counted in tracer.telemetryErrors and handed to the optional onTelemetryError(error, { hook, span }) tracer option; the operation's Result is what it would have been with a healthy tracer. hook is 'exporter', 'onEnd', 'onFinish' (ply's own end-of-operation attributes) or 'internal': ply's own span-building failed (for example an attribute value with no string form), which is never blamed on your exporter; that span is counted and not exported. onTelemetryError is optional in TracerOptions and in the TracerConfig type; its types are exported as TelemetryErrorSink and TelemetryHook. opts.tracer is duck-typed: ply requires start() and calls no other method of it (every span, wire spans included, is opened with start(); a span() of your own is never called by ply), so a { start } object, a { start, span } wrapper or a Tracer built by another pinned copy of ply works and gets the same isolation (its telemetryErrors counter and onTelemetryError are used when present). A consumer in the same process (a list kept for one request, spans mirrored onto a platform tracer) usually wants plain values instead, and would otherwise pay to build the OTLP form and then flattenLine it straight back. new Tracer({ onEnd }) calls onEnd(span) with an EndedSpan as each span ends: exactly the FlatSpan that flattenLine reads back from the line the exporter would get (ids, name, kind, durationMs, status, attributes as plain values, credential-scrubbed; events; links), plus startTimeUnixNano, endTimeUnixNano and otlp(), which builds that OTLP span on first call (and returns the same object after). onEnd runs before the exporter. A tracer with onEnd and no exporter builds no OTLP at all unless otlp() is called; one with neither builds nothing. A subclass that overrides export still gets every span. test/otel-ended.test.js holds the EndedSpan equal to flattenLine of the exported line over random attribute records of every value kind.
const spans = [];
const tracer = new Tracer({ onEnd: s => spans.push(s) }); // s.attrs['git.response.bytes'] is a number; no OTLP builtSpan lifetimes
Some work is driven by the caller after the call returns: readFile's stream, checkoutTree's files iterator (and each streamed blob in it). Their spans — git.read.blob, git.checkout.blobs — follow the span that started them instead of being its children:
- Each is the root of a trace of its own, with an OTLP link
ply.link=follows_fromto the span it follows, and that span carriesply.link=followed_byback if it was still open when the follower started (git.read→git.read.blob;git.checkout.blobs→ each streamedgit.read.blob). Links per span are capped atmaxEvents, the rest counted indroppedLinksCount. - A follower is not an invocation (no
ply.isolate.*), inherits its leader's credential scrubbing, and carries its own<name>.outcome. It ends when the work does: the stream read to the end (ok), failing (the error code), or cancelled by the consumer (cancelled). A stream neither read to the end nor cancelled never ends its span, and holds its connection, like an unreadfetchbody. - Every other span ends within its parent: no child outlives its parent (asserted over every trace in the contract test).
Why not keep the root open until the stream ends: the root's duration would then be the consumer's read speed (a slow downstream client, a Worker's response piping out), not ply's work, and a stream the caller never drains would leave the root — the span dashboards key on — unexported. Why not a child that ends late: trace viewers draw and roll up durations by the root span, so a child past its parent's end renders outside it and the root's time undercounts the work under it (#35). This is OpenTracing's FOLLOWS_FROM reference (a parent that does not depend on its child's result), which OpenTelemetry represents as a span link; Jaeger, Tempo and Honeycomb show links as navigable references between traces. So the operation root measures what the caller awaited (until the result is ready; for readFile, until the stream is open and its size known), and the follower measures the transfer.
Errors
An argument of the wrong shape is a caller error answered as a value, never a throw: null, a number or an array where an object is documented (an options bag, a spec, a pack, a source) is bad_request with what naming the argument ('options', 'spec', 'pack', …), for pushRepo, pushDir, filesFromDir and the stack entries scanPackIndex, resolvePackRange, planPackBatches, packSubset, planTransfer, copyTree, loadTransferPack and pushPack (#296). decodeSavedIndex keeps one error union: a wrong-shape bytes or want is its bad_argument refusal naming the argument, a tag like the other seven. userAgent must be an RFC 9110 field value (field-vchar 0x21-0x7E or obs-text 0x80-0xFF, with SP and HTAB only between them); a control character, DEL, a code point above U+00FF or a leading or trailing SP/HTAB is bad_request (what: 'userAgent', earlier 'user agent') when the options are parsed, where it used to fail later as a retryable network error (#300-1).
Every error a function returns has a code from errors.js, whose RETRY table says what to do: yes (retry as-is), fresh (re-resolve the parent: cas_conflict), no, or read (ambiguous: the push may have landed — read the ref back before anything else). A push says landed (resolves), not landed (cas_conflict, not_fast_forward, push_rejected: each git rejection reason's class is in SPACE.md "Push ng reasons") or partly landed (push_partial, a non-atomic multi-ref push: err.landed and err.rejected name the refs) only on a report exactly as git's receive-pack writes it; every other state after the request may have reached the server — a cut, trailing bytes, band 3, a near-miss line, option lines, a limit hit while reading — is ambiguous (SAFETY.md I36; the space and every cell's outcome: SPACE.md). A push that provably sent nothing is not one of those states, for push, pushPack and everything built on them: a signal that had already fired before the request was made is aborted (or timeout) with no request made, and a request that failed before the transport pulled the first chunk of a streamed body (a pack over 16 KiB, or pushPack's) is that failure itself (network, aborted, timeout, or an HTTP answer's own code), because the server received no command list. A body small enough to be handed over as bytes cannot be seen leaving, so a failed request with one stays ambiguous. After an acknowledged push, any failure to confirm — a forged report, a transport error on the read-back — is ambiguous, enforced in one place (operation.js/verifyRef, push.js/ambiguousAfterPush).
A fetch answer is judged as git's fetch-pack judges it, against the request that was sent. done (fetchPack, packStream, fetchBody, negotiate) is true, false or left out (the default, true); any other value (null, 0, '') is bad_request before any request, where it used to send the request without done and judge the answer as if done had been sent. After a request that sent done, an acknowledgments section is protocol ("expected packfile, received acknowledgments") even when a pack follows it; such an answer used to be ok.
A negotiate() round (a request without done) that the server answers with ready and no packfile fails at that round: protocol, "the server said ready and sent no packfile section", as git's fetch-pack dies there ("expected packfile to be sent after 'ready'"). It used to go on to the final done request and could end ok. The round is fetchPack with done: false, which refuses the same answer when called directly. A round that ends on its acknowledgments without ready is still a round: negotiation goes on.
verifyFetchAnswer(request, answer) (and so cachingFetch with verifyBeforeStore, which stores an answer only once verifyFetchAnswer accepted it whole) judges a stored answer the same way, by the done of the request that produced it. After a request that sent done, an answer with an acknowledgments section does not verify (protocol), with or without a pack after it; one with a pack after it used to verify. After a request without done, git's own answer (acknowledgments with ACK and ready, then the pack) verifies, as it always has, and an answer with no pack never does: a round that ends on its acknowledgments is protocol ("answer: no packfile section").
Shape
parseOid returns a 40-character lowercase hex object id as an Oid (bad_request otherwise). parseCommitId is that check and also rejects ZERO_OID. git's rev-parse also accepts abbreviations, ref names, and uppercase hex; ply does not. MODE_BLOB, MODE_EXEC, MODE_LINK, MODE_TREE, MODE_COMMIT, and BLOB_MODES are the modes git writes in a tree (BLOB_MODES is the file modes: blob, executable, symlink).
Two entry points, one codebase. ply/edit is the pipeline and imports only the free functions it uses; ply is the full client (negotiation, delta resolution, multi-ref pushes, advertisements). Nothing is a class on the hot path — createTransport() returns a record and lsRefs, packStream, fetchObject, fetchPack, negotiate, push, discover are functions over it — so a bundler keeps only what you import. GitHttp wraps all of them for scripts and tests: GitHttp.create(url, opts) is a Result (a bad URL is its Err), and each method answers with the free function's Result. test/bundle.test.js asserts the edit bundle carries no resolver, negotiation, advertisement or class code and stays under budget (39 KB min / 15 KB gz; full: 58 KB / 21 KB).
edit.js is pure decisions between thin effects: validateSpec, decideHead, lookupEntry, buildCommitObjects, memFromScan are functions of their arguments and unit-tested against git without a server (test/pure.test.js); ls-refs, fetch, the blob stream, push and verify are the only places the client is touched.
Limits
Every bound is a field of limits (opts.limits, any call). DEFAULT_LIMITS is sized for a git client's heap: one object up to 64 MiB (maxObjectSize), 128 MiB of pack per fetch or push (maxPackBytes), 128 MiB of files per pushTree or commitChanges (maxPushBytes), 256 MiB held from one buffered pack (maxInflatedTotal), 100 000 objects per pack (maxPackObjects), 200 000 entries per tree (maxTreeEntries), 2^32 diff steps per merged file (maxMergeWork: CPU, not memory, about 25 s of it at the ~6 ns a step measured, sized so that a file git itself merges cleanly in about 5 s is merged, a 130,000-line file with 13,000 scattered one-line edits included; a file both sides changed whose line merge needs more is a merge_conflict with reason too large to merge, as one over maxMergeBlobBytes is). withLimits({ ... }) overrides some of them; a field that is missing, NaN, infinite or negative is bad_request, never an open cap. A bound hit is limit_exceeded with what (the budget), got and max. maxReportLines (10 000) bounds receive-pack's report, but never below what git sends for the commands pushed (one unpack line plus one status per command, five per command with report-status-v2), so a push of up to maxRefs commands is never cut off by its own report; a report past the cap is ambiguous (the push was sent). Two more limits bound what is kept of receive-pack's answer and never change a push's outcome: maxReportReasonBytes (4096) is how much of one refusal reason (ng <ref> <reason>, or an unpack <status>) is kept, so a longer one is cut there, the ref keeps its status and the error's code is read from the kept part (never fewer bytes than git's own longest reason, so a reason git writes is never cut), and whether a host's unpack status is echoed on a ref is read from the whole status and reason before the cut, so a pair that differs past the limit stays ambiguous; maxReportProgressBytes (8 MiB) is how much band-2 output (progress, hook text) is decoded, anything past it is dropped, the report is still read and hookOutput is the last 4 KiB of what was decoded. Keepalives and the answer as a whole are held to maxPackBytes and the timers. rebaseBranch makes two walks to find its base, each under its own limit: the branch is walked from its tip to maxRebaseCommits (10 000) + 2 commits, or to maxMergeDepth where that is deeper (a base that mergeBranch's search finds is found here), and onto to maxMergeDepth (1024) commits, as mergeBranch, mergeBase and readLog are. A chain known to be longer than maxRebaseCommits is limit_exceeded with what: 'rebase chain', max: maxRebaseCommits and got: max + 1 however long the chain is: the search stops one past the limit and does not count the rest. It is known when the base was found, or when the onto walk reached the root of onto's history and more than maxRebaseCommits commits of the branch are outside it. When both walks end without a shared commit and the onto walk was cut at maxMergeDepth, the refusal is what: 'merge-base search depth' with max: maxMergeDepth and got twice that, the fields mergeBranch reports: a commit of the branch walk may still be an ancestor of onto beyond the cut, so a short branch whose onto has moved more than maxMergeDepth commits past the base and a long chain look the same, and no request is spent to tell them apart. Raising maxMergeDepth until both walks reach the base settles it either way (the rebase, or 'rebase chain'); maxMergeDepth: 0 refuses every rebase before any search. A walk that has reached the root, or its cap, is not fetched again. A refusal costs no more requests under WORKER_LIMITS than the merge-base search alone (ls-refs and two walks at each of the 8 depths to 1024: 17), and up to 9 more under DEFAULT_LIMITS (26 measured: past maxMergeDepth the branch walk goes on in windows of maxMergeDepth commits from the cut frontier, one window held at a time as parent lists, so it holds no more than the merge-base search did), both asserted in test/rebase.test.js on a repository whose onto history is deeper than maxMergeDepth. A rebase costs one request for ls-refs, two per doubling of the search (8, 16, …), the replay and the push. What the replay costs depends on what its commits touch: about one request per commit whose files onto did not change, more for each file that must be line-merged with onto (three shapes of a 256-commit chain are measured at 268, 781 and 2,581 requests: WORKER_LIMITS, below). No limit bounds the requests of a rebase: maxRebaseCommits bounds the commits, not the files each one merges.
The byte budgets count what an object costs, not only its bytes: each object parsed from a pack (parsePack, and the room resolvePack has left; so every fetch, checkoutTree, and pushRepo's local packs), each local object pushRepo holds, each file filesFromDir reads, and each file or change pushTree/commitChanges takes is charged its bytes plus LIMIT_OBJECT_OVERHEAD (3 KiB, above the 1.0 to 2.4 KiB of heap and RSS one tiny object was measured to cost; the method is in src/limits.ts). So a pack of 100 000 three-byte blobs (1.4 MB on the wire, which git index-pack accepts) is limit_exceeded (what: 'pack inflated bytes') under the defaults, and 100 000 eight-byte files are limit_exceeded (what: 'push bytes'), where counting bytes alone let both run a 128 MiB heap out of memory. On the defaults that is about 87 000 tiny objects per pack and 43 000 tiny files per push; got includes the overhead. stats.inflated is still the declared sum git reports.
Time is bounded per exchange by four timers (#255, #273), all fields of limits; 0 turns one off:
firstByteTimeoutMs(60 s): from the request to the response headers. For a streamed request body (pushPack, aStreamBody), it starts when the upload ends, which for ply is when the platform has taken the last piece. The platform and the kernel may still be sending what they buffered (about 2 MiB on Node over loopback, measured), so on a slow link this limit also has to cover that tail: a link that cannot drain it in time fails asfirstByteTimeoutMs. Once the response headers have arrived this limit cannot fire, whatever the upload does after (a server may answer before it has read the whole request).idleTimeoutMs(60 s): the longest wait on the network with no progress, either no upload piece taken by the platform or no response chunk arriving. A streamed upload is handed to the platform in pieces of at most 64 KiB, so one large chunk is many progress marks; a mark means the platform took a piece, not that it reached the server, and marks arrive in bursts as the platform's and the kernel's buffers drain (with Node's fetch over loopback at 2.5 MiB/s: gaps up to about 0.5 s). The split has a cost for a source whose chunks are larger than 64 KiB: such a chunk costs what the same bytes cost as 64 KiB chunks, measured on Node 24 over loopback as about 0.13 to 0.15 ms more client CPU and 0.09 to 0.12 ms more wall time per MiB uploaded than handing each chunk over whole; a source of 64 KiB chunks measures level with that. ply does not measure upload progress below fetch:idleTimeoutMsandfirstByteTimeoutMsfire on what ply can see (the platform stops taking pieces; no response after the last piece is handed over). For a bound on the upload as a whole, whatever the platform has buffered, the request timeout (requestTimeoutMs, off by default) or the caller'ssignalis what bounds a stalled upload. A server that keeps sending (upload-pack sends keepalives while it counts objects) is never cut. Idle time measures the network, not the consumer: while the consumer holds a chunk and has not asked for the next one, no idle time is charged;heldTimeoutMsbounds that instead.heldTimeoutMs(240 s, 4 x the idle default,LIMIT_HELD_TIMEOUT_MS): the longest the consumer may hold one chunk, from taking it to asking for the next, before the exchange is cut with codetimeoutandlimit: 'heldTimeoutMs'and the upstream body is cancelled. A consumer that holds just under it is not cut, and network idle is not charged while it holds. Precision: the take reads no clock (the hold adds no clock read per chunk), so the hold starts at the first clock read after the take (the exchange's pending timer firing, or the take arming one when none is due by then); the cut is never before take +heldTimeoutMs, and late by at most one timer interval:idleTimeoutMsorheldTimeoutMs, whichever is smaller (heldTimeoutMswhen idle is off), plus the platform's timer latency, which is fine against a 240 s default. 0 turns it off, leaving a consumer that stops reading bounded only by the caller'ssignalorrequestTimeoutMs.requestTimeoutMs(0, off): an opt-in cap on the whole exchange, body included. Before #255 this was the only timer, at 60 s, so a large streamed fetch died at 60 s however steadily bytes arrived. A caller who passes it keeps that behaviour.
Each of the four is a whole number of milliseconds from 0 to 2147483647 (the range of the platform's timer, 24.8 days); a larger value is refused as bad_request before any request, and 0 turns that timer off.
With the defaults there is no total cap: an exchange that keeps making progress runs as long as it takes, unless the caller sets requestTimeoutMs or passes a signal. Network stalls are still bounded by the two network timers above, and a consumer that stalls by heldTimeoutMs.
A timeout is the typed timeout error with what naming the limit that fired. The exchange span records git.timeout.limit and git.timeout.ms as well as git.limits.first_byte_timeout_ms, git.limits.idle_timeout_ms, git.limits.held_timeout_ms and git.limits.request_timeout_ms. There is no total cap by default, matching stock git, which has none (http.lowSpeedLimit is off by default). For a wall-clock bound, pass requestTimeoutMs or your own signal. Body reads end on abort even when a fetch wrapper does not tie the body to the signal. In a Worker, timers fire while a body read is pending (tested under workerd).
WORKER_LIMITS is the preset for a 128 MiB isolate (a Cloudflare Worker): maxObjectSize and maxDeltaResult 16 MiB (one object peaks near twice its size), maxPackBytes, maxPushBytes and maxLsRefsBytes 32 MiB, maxInflatedTotal 64 MiB (about 21 000 tiny objects), maxResolveWork 512 MiB, maxHarvestBytes 8 MiB, maxMergeBlobBytes 2 MiB, maxMergeWork 2^26 steps (the worst files found under maxMergeBlobBytes are refused in 1.0 to 1.7 s of CPU on a loaded 16-core laptop, up to 0.9 s of which is splitting the three sides into lines, which no step budget covers; a 70,000-line file with 3,500 scattered one-line edits needs about 362 million steps, so in a Worker it is a conflict with reason too large to merge; withLimits({ ...WORKER_LIMITS, maxMergeWork: 2 ** 30 }) merges it), maxTreeEntries 32 768, maxRebaseCommits 256, maxReportReasonBytes 1024 (a push of 10 000 refused refs keeps 10 MiB of reasons, not 40); the rest are the defaults. 256 bounds the length of the chain, not the number of requests: what a chain costs depends on what its commits touch, and a Worker request may make 1,000 subrequests (standard plan). The cheapest shape is the one test/rebase.test.js measures: a 256-commit branch whose every commit changes one file that onto did not touch is measured at 268 requests (at most 800 is asserted), and a branch one commit longer is refused (what: 'rebase chain', got: 257, max: 256) in at most 17 requests. The same 256 commits are measured at 781 requests when every commit changes one file that onto also changed (each replay line-merges it), and at 2,581 when every commit line-merges three files in three directories. The first two are under a Worker's ceiling (781 leaves the caller 219 for everything else its request does); the third is 2.6 times past it, and ply has no request budget that would refuse it by name. A Worker that rebases branches over changes to the same files lowers maxRebaseCommits or raises its subrequest limit. All three were counted where requests leave the transport, against git http-backend (a tree:0 server) under WORKER_LIMITS, with src/ as of 6edf6a0; the first two end in the tree git rebase writes (the third was not compared), only the first is held by a test, and nothing here was run on workerd. The limit sweep (npm run sweep -- --full, nightly) runs it at --max-old-space-size=128: every worker.* cell refuses or succeeds, none runs out of memory.
maxResolveWork is resolvePackRange's hard work ceiling, applied exactly as given. It must be at least the record's own maxInflatedTotal: below it, parseLimits (and every limits option) is bad_request with what: 'maxResolveWork'. A record that leaves maxResolveWork out (a partial record, withLimits) gets 8 × its maxInflatedTotal, capped at Number.MAX_SAFE_INTEGER but never below maxInflatedTotal itself ({ maxInflatedTotal: 1e18 } gets 1e18). A spread of a preset carries the preset's number, not a derived one: { ...DEFAULT_LIMITS, maxInflatedTotal: 16 MiB } is still bounded at 2 GiB, and { ...WORKER_LIMITS, maxInflatedTotal: 1 GiB } is bad_request (512 MiB is below 1 GiB). Set maxResolveWork beside the changed maxInflatedTotal, or take the preset's number out with withDerivedWork: withDerivedWork({ ...DEFAULT_LIMITS, maxInflatedTotal: 16 MiB }) is bounded at 128 MiB. null is bad_request on every key, maxResolveWork included.
import { pushTree, WORKER_LIMITS, withLimits } from 'ply';
const r = await pushTree(url, spec, { limits: withLimits({ ...WORKER_LIMITS, maxPackBytes: 62 * 1024 * 1024 }) });Memory
Peak per invocation is one pkt-line (≤ 64 KB) + one inflate chunk (16 KB) + |find|−1 carry + the replacement bytes. Measured over 446 fuzzed edits including 1.4 MB blobs: mem.alloc.max_single max = 16384. The blob is never resident; the delta is three ops computed from the match offset, and the new blob's oid comes from a streaming SHA-1 over the transformed stream (the exactly-one-match contract makes newLen known up front).
Every fetch reads its pack as the band-1 bytes arrive, through one deflate decoder (inflatePull, of which inflate() is a collector): the pack's bytes and its zlib members are dropped once inflated, so a fetch holds what it keeps plus the decoder's hold, the 32 KiB window, one 16 KiB chunk and one pkt-line (114,672 B, src/streambound.ts). Measured (test/stream-memory.test.js, node --expose-gc, live arrayBuffers sampled every 256 KiB allocated): fetchObject through the blob:none fallback, a pack of 2,000 4 KiB trees, all retained (R = 8,192,000 B), peaks at R + 241,366 B where it peaked at R + 12,201,108 B with the pack joined first (fetchPack of the same pack: R + 241,345 B, was R + 12,201,108 B); with 62 256 KiB blobs in the pack too (an unfiltered fallback; a tree want drops them as their headers arrive) R + 257,434 B where it was R + 28,621,712 B. The response's own share of those figures (frames in flight, read with every chunk dropped) is 451,094 B. inflate() of a 64 MiB member in hand holds the output and 82,236 B.
The pulls are exported for a caller that streams on its own: inflateInit/inflateFeed/inflatePull/inflateEnd (bytes in, chunks of at most 16 KiB out), parsePackInit/parsePackFeed/parsePackPull/parsePackEnd (a pack's header, each object's header with its parsed base, its inflated chunks, its end, the trailer) and sidebandStep (one packfile-section frame demultiplexed). Each pull answers need when it wants more input; a refusal is a Result error, and every later pull returns it again.
What a zlib member may be is git's call: the decoder accepts a member stock zlib accepts as git links it, and refuses what it refuses. A zlib header's CINFO above 7 is pack_corrupt; a smaller CINFO is not enforced (zlib's inflate.c checks a distance against the declared window only under INFLATE_STRICT, which stock builds do not define), so a match that reaches past the declared window and stays inside the output already produced is read, as git cat-file and git index-pack read it. Before this, inflate(), parsePack and the pulls answered pack_corrupt (inflate: distance too far back) for such a member. A match that reaches before the first byte of output is still pack_corrupt.
A dynamic block whose code-length, literal/length or distance code set is over-subscribed or incomplete is pack_corrupt at the block's header, with zlib's message (inflate: invalid code lengths set, inflate: invalid literal/lengths set, inflate: invalid distances set) and by zlib's rule: an incomplete set is allowed only when it has no codes, or is one 1-bit code in the literal/length or distance set. Members with such a set that an earlier version refused later now carry the message above in place of unexpected end of input, invalid huffman code or distance too far back (the code was and is pack_corrupt); members it accepted are now refused, as zlib and git refuse them. In the pulls, a member cut short after such a header is a definite refusal at the header, where the pull used to answer need.
The same decoders as streams, for a for await (#241): scanPack(source, { limits, verify, budget }) yields the scan's pieces (header, then for each object object, its inflated bytes as chunks and object-end, then trailer; never need or end), pktFrames(source) yields pkt-line frames (data, flush, delim, end) and inflateChunks(source, { bound, wrap }) yields one zlib member's inflated chunks (at most 16 KiB each). source is a ReadableStream<Uint8Array> or an AsyncIterable<Uint8Array>; each returns a ReadableStream with highWaterMark: 0, so the source is read only when you ask for the next item, one chunk at a time. A refusal (a bad header, a cut pack, a frame past 65,520 bytes, bytes after a zlib member's end, a chunk that is not a Uint8Array, bad options) errors the stream with the PlyError the pull returns, so it is thrown from the loop, and the source is cancelled. An error from the source is thrown as it is (the same object). A break, a return or a throw in the loop body cancels the stream, which cancels the source (a ReadableStream is cancelled with the reason; an iterable's return() is called). Measured (test/stream-memory.test.js, Node 22 and 24, live arrayBuffers at peak): scanPack over three 96 MiB blobs 84,284 B and inflateChunks over a 96 MiB member 84,284 B (bound 114,672), pktFrames over 2,000 maximal frames 131,036 B (bound 131,040, two frames); test/pullstream.test.js checks parity with the pull API over every chunking, the reads each item costs, and each refusal and release.
import { scanPack } from 'ply';
// pack: a ReadableStream or AsyncIterable of a pack's bytes. An invalid pack errors the stream (a PlyError).
const sizes = []; // each object's inflated size, in pack order
let size = 0;
for await (const piece of scanPack(pack)) {
switch (piece.kind) {
case 'header': break; // piece.version, piece.count
case 'object': size = 0; break; // piece.type, piece.offset, piece.base
case 'chunk': size += piece.bytes.length; break; // the object's inflated bytes, in order
case 'object-end': sizes.push(size); break; // piece.compressed, piece.stats
case 'trailer': break; // piece.trailer: the pack's checksum
}
}A pack scan holds no object: its peak is the constant in src/streambound.ts (the 32 KiB window, one 16 KiB chunk, one pkt-line, plus the chunk you fed and any chunk you keep), so there is no limit to set for it. What a scan's limits bound depends on its budget. By default (packScanOpts(limits)) it refuses exactly as parsePack does, charging each declared size plus per-object overhead against maxInflatedTotal before inflating, and applying maxObjectSize: right for a caller that keeps objects. A caller that drops them passes packScanOpts(limits, verify, WORK_BUDGET), and a multi-GB pack needs no caps raised. maxInflatedTotal then means work rather than memory: bytes actually inflated may reach it, or ratio (default 32, workBudget(ratio)) times the pack bytes consumed so far if that is larger. A decompression bomb stops within one chunk of that, so lower maxInflatedTotal to spend less CPU on one. maxObjectSize applies only with workBudget(ratio, true); maxPackObjects still applies, and bounds what you keep per entry. Refusal near the ratio can vary with how the pack is chunked; memory cannot. A caller that does retain chunks under a work budget has to bound them itself.
scanPackIndex(source, { oids, content, limits, verify, budget, signal }) is that driver for the common case: it reads a ReadableStream or AsyncIterable of a pack and returns each entry's layout (offset, header bytes, compressed length, stored type, declared size, base) without resolving a delta or keeping an object. It is the streaming counterpart of describePack, under WORK_BUDGET by default. It holds the scan's constant plus SCAN_INDEX_ENTRY_BYTES (31) per entry in typed columns, and 20 more per entry for each oid column in use: whole-object oids (on by default, hashed as the bytes stream past; oids: false saves about a fifth of the time) and REF bases (once the pack has a REF_DELTA). A REF-only pack, which is what Cloudflare Artifacts sends, holds 71 bytes per entry. type: null means unknown, never a guess. A REF chain whose base is itself a delta stays null, because linking it needs that delta's oid, which means applying deltas. On this repository's REF-only pack that is 4,647 of 5,675 REF deltas. Since Cloudflare Artifacts packs are REF_DELTA only, their chains deeper than one stay null here. resolvePackRange (below) resolves those. Columns grow by doubling up to the header's count. Measured (test/stream-memory.test.js): 200,000 entries with oids, 51 bytes per entry; three 96 MiB blobs, 84 KB live against the 114,672 B scan bound. Each entry's resolved type is the type of the whole object its chain rests on: an OFS chain's root, or a REF_DELTA's base when that base is a whole object in the pack and oids is on. A base outside the pack, a base that is itself a REF delta, or oids off is null, never a guess. content.select picks whole objects (a commit, say) whose bytes content.take receives in pack order, each capped by maxObjectSize. Verified while scanning: zlib, each declared size, each OFS base an earlier entry's offset, and the trailer. A refusal is a Result that cancels the source; an error from the source or from take rejects.
resolvePackRange(index, source, { limits, budget, cacheBytes, bases, signal }) is the rest of git index-pack for a pack too large to hold: every entry's oid, resolved type, chain depth and base, from scanPackIndex's index and a RangeSource over the same bytes ({ size, read(offset, length, signal) → Promise<Result<ReadableStream>> }: a file, an R2 object, or rangeFromBytes in memory; signal is an AbortSignal that is optional in the type, signal?: AbortSignal | undefined: a read of two parameters is a RangeSource, a direct caller may omit it or pass undefined, and a wrapper forwards the optional signal it was given as it is (inner.read(offset, length, opts.signal) compiles), so a read that takes it has to work without one, while ply always passes one). It works depth first from each whole object, reading each delta back through the source and applying it; of the results something rests on, the last is pinned as the next base (a linear chain builds each object once, whatever its size) and the others go to an LRU of cacheBytes (16 MiB by default). A base in neither is rebuilt over its chain, and every base made on the way is kept in the LRU, so a forked family larger than the cache walks a chain once per cache-full of siblings rather than once per sibling (151 objects forked 50 deep with a cache of 16: 235 reads and 1.56 × the object bytes of work, where it was 745 reads). With cacheBytes smaller than one object a fork still costs its depth per sibling; the work budget bounds that. A valid pack whose forked family is rebuilt past the work bound that way (cacheBytes: 0, or a cache smaller than one of its objects) is refused by design, limit_exceeded (resolve work bytes), where a cache with room for its objects resolves it. It holds one base, one pinned result, one result, one delta's instructions and the cache: at most max(maxObjectSize, maxDeltaResult) + 3 × maxDeltaResult + cacheBytes (272 MiB on the defaults, 80 MiB on WORKER_LIMITS), whatever the pack's size, depth or shape. Every oid is computed from the bytes; a base read back a second time must hash to the oid it had (a spool that changed is pack_corrupt); a thin base from bases(oid) must hash to the oid that named it. Refused: a base in neither the pack nor bases (pack_corrupt, "not found"; a REF cycle ends there too), a chain past maxDeltaChain, work past the budget (limit_exceeded, resolve work bytes). Work (stats.work) is bytes inflated from the source plus bytes of delta results made plus one per delta visited as a child of its base, so it rises by one per delta over the bytes alone (one blob and m REF deltas on it is 11 m + 6, not 10 m + 6), and a shape that visits a delta more than a constant number of times is refused by the budget rather than resolved slowly (#299). The budget follows what the pack declares (4 × its members' sizes plus each delta result made so far, never less than maxInflatedTotal), because delta-compressed history is legitimately hundreds of times its pack, and it never passes the hard ceiling, limits.maxResolveWork exactly as parsed (never below maxInflatedTotal: parseLimits refuses a smaller one): 2 GiB on DEFAULT_LIMITS, 512 MiB on WORKER_LIMITS, and 8 × the record's maxInflatedTotal when a caller's limits leave maxResolveWork out (the rule for a spread of a preset is under Limits). The ceiling is what stops a delta bomb: a 4 KB pack of 40 deltas each declaring a maximum-size result is refused after 512 MiB of work (about 2 s of CPU) under WORKER_LIMITS and after 2 GiB (about 8 s) under the defaults (test/pack-range-resolve-bound.test.js). An honest pack whose objects sum past the ceiling is refused the same way; raise maxResolveWork for it and split the work across requests. A maxResolveWork that is not a finite non-negative number is bad_request like any other limits key, whatever the budget. The result keeps RESOLVED_ENTRY_BYTES (41) per entry: oid, type, base, depth, resolved size and an oid-ordered index for find(oid). Measured (node 24, laptop): this repository's REF-only pack (3,621 entries, 3.1 MB, chains to depth 50) in 3.3 s, about 18 MB/s of resolved bytes; chains of 4 MiB blobs at about 75 MB/s of resolved bytes, peak 8.44 MB live whether the pack was 8 or 33 MB (test/resolve-memory.test.js). Split work across requests by those rates. Abort. The storage behind a RangeSource or a scanned stream is the caller's and may never answer, so scanPackIndex, resolvePackRange, loadTransferPack ({ scan, resolve, signal }) and packIdentity(source, signal) take an AbortSignal: when it aborts the call returns aborted at once, whether or not the read in flight ever settles; the range or stream in flight is asked to cancel (not waited for), the signal passed as read's third argument aborts, and whatever the storage answers later is dropped (a range that opens late is cancelled). A range whose cancel() throws, or returns something that is not a promise, changes none of this: its failure to cancel is dropped. A signal that has already aborted when packIdentity or resolvePackRange is called returns aborted before anything else: no storage read is issued, for a pack of whole objects (which needs none) as for one with deltas. A packSubset stream does the same when its consumer cancels it. Without a signal these calls wait for the storage.
planPackBatches(index, resolved, { budget, select, crossBatchRef }) plans how to push those entries as several pushes when one push would be over a host's limit. It is pure: it reads the two indexes and returns plain data ({ version, trailer, budget, batches: [{ kind, entries, packBytes, objects, refRewrites }], hash }), which packSubset turns into packs and pushPack sends. Build each batch with the index the plan was made from: packSubset(source, index, batch.entries, { outsideBase: plan.crossBatchRef ? 'ref' : 'refuse', resolved }). The planner sizes and checks every entry with the builder's own rule, so a batch it plans is one packSubset builds from that same resolved; without resolved (or with another pack's) a crossBatchRef batch that cuts an OFS chain below a delta base is refused by the builder (bad_request, what: 'pack subset base'), because only resolved knows a delta's id. The budget is the caller's, every dimension: maxRequestBytes and maxObjects per push (with reserveBytes and reserveObjects held back for the command prefix and any generated objects, such as a temp commit and its tree), and maxObjectBytes (resolved size) and maxCompressedObjectBytes (the zlib member) per object. ply holds no host's numbers; measured on Cloudflare Artifacts (2026-11-09), as an example only: 67,108,864 request bytes, about 50,000 objects, 33,554,432 inflated bytes per object, about 33,553,575 compressed. Every object is checked before any batch is planned, so an object no push can carry is refused (limit_exceeded, with what, got, max) before anything is sent. Children first: a strict server (receive.fsckObjects) refuses a pushed tree whose blob it lacks, so every blob goes in a batch before the trees, and the trees, commits and tags go last in one batch. Plan v1 refuses (limit_exceeded, "tree batch") when they do not fit one push, rather than ordering trees by depth. Delta families (a whole object and every delta resting on it) stay in one batch, so each batch has its bases. A family no single push holds is refused unless crossBatchRef: then it is split in chain order, and a delta whose base is in an earlier batch is written as REF_DELTA to the base's oid. That is a thin pack resting on what the destination already has; git's receive-pack accepts it (index-pack --fix-thin), but whether a host does is the host's to say, so it is opt-in. An Artifacts pack is REF_DELTA already, so nothing is rewritten for it, but the same opt-in governs it. The id written for a cut base is resolved.oid(base), asked for only when a base is outside its delta's batch and checked there. A resolved that cannot name a cut base fails the plan (bad_request) before anything is pushed, and the message says which of three things happened: oid() answered no id, or anything but 40 lowercase hex ("cut from its base", with the entry); oid() returned nothing at all, neither an answer nor an exception ("oid() returned nothing", no cause); or calling oid threw, which a missing oid or one that is not a function also does ("oid() threw", with what was thrown as the error's cause). packSubset refuses the same entry in the same three ways (bad_request, what: 'pack subset base') before it reads a byte, so no header ever carries anything but an object id. Order against the planner's other refusals: an oid() that threw or returned nothing is reported ahead of a limit_exceeded the same plan would otherwise end with (a tree batch too big for one push, say); an answer that is not an id is reported after it. An exception out of resolved.oid() is neither swallowed nor let out: planPackBatches, packSubset, planTransfer, transferStep and runTransfer return bad_request with what it threw as the error's cause (the same object), and a transfer step that ends that way has pushed nothing. A resolved.type() that throws while a transfer reads an entry ends the same way (bad_request, what: 'entry', the cause). Sizes are counted as they will be written: an OFS_DELTA's distance at the length the largest distance in a push needs, and a REF rewrite at 20 bytes. The plan is deterministic and hash (SHA-1 of its canonical JSON: plan version, the source pack's trailer, the budget, the options and the batches; planHash recomputes it) names it, so a resumed transfer can tell its plan from another. Measured (node 24, laptop, test/pack-plan.test.js: a synthetic 200,000-entry index, 156,000 of them deltas, the two kinds alternating, median of 5 plans each, three runs of the test): planned in 47 to 51 ms when the deltas are REF_DELTA and 112 to 127 ms when they are OFS_DELTA (an OFS header's distance is sized per entry); 21 MB (OFS) and 36 MB (REF, the first plan in the process) of heap for the first plan of each kind; a 1.3 MB plan as JSON. With crossBatchRef off (the default) planning costs what it did before cut bases were checked: within 3% of main 8e3939d by the median of 15 interleaved process rounds. With crossBatchRef on, checking a cut base's id has a cost, accepted and stated here (measured at 02374d4, node 24, laptop, the 200,000-entry synthetic index above, 7 plans a process, 15 rounds alternating 8e3939d and 02374d4 processes, each process planning REF and OFS packs in turn; per-round ratio, median and range, and the ratio of the processes' minimums): a REF pack whose families are cut nowhere (50 pushes, 0 rewrites) 1.06 times (0.96 to 1.19; minimums 1.09, slower in 15 of 15 rounds); an OFS pack whose families are cut nowhere 1.03 times (0.98 to 1.12; minimums 1.04, 15 of 15); an OFS pack in which nearly every push boundary cuts a chain (blobs only, 2 objects a push, so 116,000 pushes and 76,000 cut deltas, each cut delta's base id asked of resolved and checked twice: once when it is sized in the push it opens, once when it is placed) 1.16 times (0.68 to 2.84 on a machine whose load average rose to 50 during the run; minimums 1.24, slower in 14 of 15), the fastest plan 185 ms against 245 ms. A REF pack asks for no id; the REF figures are the cost of the shared sizing path once OFS packs have been planned in the same process (a process that plans only REF packs measured 0.965 times). Run files: ofs-cross-batch-eng-bench-head.txt and ofs-cross-batch-eng-allcut-head.txt in the review-train scratch directory; an earlier check at the same commit measured 1.08 times for the REF case (ofs-cross-batch-chk-bench.txt, ofs-cross-batch-chk-bench2.txt).
Resumable transfer (copyTree, #238) puts those together: one commit's tree, read from a spooled depth-1 pack, copied to another remote as a new parentless commit, in as many pushes as a host's cap needs, each safe to retry and the whole resumable from the destination alone. The caller owns the spool and where the loop runs; ply owns every state transition. planTransfer(index, resolved, { budget, ref, commit, tempPrefix, crossBatchRef, atomic }) is pure: commit is the source commit's bytes (scanPackIndex's content callback hands them over), budget the host's per-push limits (ply adds its own reserve: 258 objects and about 68 bytes per object for the generated trees and commit). ref is refused unless git would push it, and the temp ref is a branded TempRef under tempPrefix (which ends in /). It returns plain JSON with a hash, so a Worker can keep it between requests; checkTransferPlan(plan, { ref, tempPrefix }) refuses a plan read back that is edited, stale or malformed (any field a step reads: an id, a ref, a step, the pack plan's budget, selection or batches) and is total: a stored value of any shape is bad_request, never a throw; a hole in one of its arrays (steps, pack.batches, pack.select, a batch's entries: a structured-clone store can hand one back, JSON cannot) is a corrupt plan (what: 'plan'). transferStep and runTransfer answer a commit that is not a Uint8Array with bad_request (what: 'commit') before anything is read from it or sent. A stored plan is untrusted, so the caller names the destination ref on every call that takes a stored plan (checkTransferPlan, transferStatus, transferStep, runTransfer; types PlanExpect, PlanExpectConfig, StepCommit): the plan's ref must equal it, and a call that names no ref is refused (both bad_request, what: 'ref'). This is a breaking change: transferStatus(dst, plan), runTransfer(dst, from, plan, commit) and transferStep(…, step, commit) with bare bytes, as earlier versions took them, are now bad_request. The temp ref is not a free field either: it must be the name the plan's key gives under tempPrefix (what: 'tempRef'), so a plan made with a custom tempPrefix is resumed by naming that prefix again on every call. The plan is checked once per call, before anything is read or sent; the plan object the call then holds is trusted for that call. The check is one linear pass over the plan on every stored-plan call (checkTransferPlan, transferStatus, transferStep, runTransfer): it rehashes the pack plan and walks the selection and every batch's entries, so its time and its transient memory (the pack plan's canonical JSON, one set of the selection) grow with the plan's entry count, and transferStep and runTransfer add one pass over the pack index. Measured at 04ee345 (Node 24.18, a 16-core laptop, median of 16 calls): about 21 ms for 100,000 entries and about 240 ms for 1,000,000; a caller that drives one transferStep per request pays it on each request. The plan's two hashes are unkeyed: they are integrity against corruption and stale or partial writes, not authentication against whoever can write the plan store. They do not hold the batch grouping or order: a writer of the store who regroups or reorders the batches into another partition of the same selection and recomputes what is derived from them (both hashes, the temp ref, the steps' temp commit ids) passes the check, and that plan runs. So what a plan may push is also checked directly, whatever its hashes say: its batches must partition its selection (every selected entry in exactly one batch, nothing else in any; bad_request, what: 'batches'), and transferStep and runTransfer, which hold the pack, refuse before any request a plan whose selection is not exactly the pack's trees and blobs (bad_request, what: 'pack'). Each step is a tagged variant: { kind: 'batch', temp, prev } or { kind: 'final', prev }, prev a tagged Option ({ tag: 'none' } or { tag: 'some', value }). Every batch but the last moves a temp ref (refs/ply/transfer/<key>) to a temp commit whose parent is the previous one and whose tree lists that batch's objects by id, fanned out into up to 256 subtrees by the id's first two hex digits (a flat tree was refused above about 16k entries on Cloudflare Artifacts). Everything pushed so far is reachable at every moment, and every batch is children first, so a strict server's fsck and connectivity check pass on each push. The last batch (the trees) carries the new commit and, in one atomic push, creates ref (compare-and-swap on the zero id) and deletes the temp ref; atomic: false sends it as one plain push. Every generated id is in the plan, so transferStatus(dst, plan, { ref, tempPrefix }) reads the two refs (ls-refs) and names the next step, or done; a temp ref the plan never writes, or ref at another commit, is cas_conflict. transferStep(dst, { source, pack, resolved }, plan, step, { commit, ref, tempPrefix }) is one push; every update is a compare-and-swap, so a step that landed, sent again, is refused (ng … stale ref) and moves nothing. runTransfer(dst, from, plan, commit, { ref, tempPrefix, maxSteps, retries, settle }) loops status → step → settle. Settling reads the refs back after every push, at most settle.reads times settle.delayMs apart (default 3 and 200 ms), until they show it: a host's ls-refs can lag a push it acknowledged, and a lagging read must not make the loop send the step again. An acknowledged push the refs do not show pauses the run ({ tag: 'paused', step, reason: 'settling', lastPush: 'acknowledged', lastStep: 'not_shown' }). One case trusts the server's report instead of a read-back: when the final push is acknowledged (every command in its receive-pack report ok, so ref was created and the temp ref deleted, in one push, atomic unless the plan was made with atomic: false) and a read of the refs then fails (the first settle read, or a later one after reads that did not show the push yet; a settle span whose tracer fails counts as a failed read), the run ends done (tempLeft: false) on that report alone, in either mode (the 'unread' arm of acknowledged in src/transfer.ts); the same failed read after a batch push ends the run with the read's error, because the transfer is not done. A caller that needs the destination's own word reads it with transferStatus. A push that is not a clean ok (ambiguous, rejected, partial) is judged by the refs, the only commit point: the step landed (by this push or another runner's) is progress and the run goes on or ends done; it did not land and the push was refused is that refusal; it did not land and the push was ambiguous is sent again (at most retries times in a row, within maxSteps) and then the run ends ambiguous, never paused; the refs could not be read is ambiguous with the push's own error as cause, never the read's error. A step that fails before any push request is made (ply's own refusal, such as limit_exceeded against the transport's maxPackBytes; the final push's receive-pack advertisement not read, aborted or network included; a capability the server does not advertise, unsupported) is not a push: the run ends with that error as it is, with no settle reads, it is not counted in pushes, and it is never ambiguous or a lastPush. maxSteps pauses it (reason: 'max_steps') for the next request to resume. A pause states two facts about the run's last push in two fields (types LastPush and LastStep, exported beside TransferRun), because they can differ. lastPush is what the server answered this run's own push: 'none' (the run made no push), 'acknowledged' (its report said ok), 'refused' (the server refused it) or 'unanswered' (no report reached the run). lastStep is what the refs then showed of the step that push carried, whoever landed it: 'none' (no push), 'landed' or 'not_shown'. So lastPush: 'refused', lastStep: 'landed' is a run whose push was refused because another runner had landed that step first: the step is on the destination and this run's push is not what put it there. A max_steps pause always has lastStep: 'landed' (or 'none'); a settling pause is 'acknowledged' and 'not_shown'. A run that ends ambiguous because a step did not land after N tries (or could not be read back) carries the last push's own error as cause and its code as original. Done is { tag: 'done', head, pushes, tempLeft }: tempLeft says a temp ref is still on the destination, for sweepTransfers. Spans: git.transfer.run over git.transfer.status, git.transfer.step (step index, kind, batch entries and bytes, generated objects, outcome; the push's wire spans under it) and git.transfer.settle (reads, outcome), and git.transfer.sweep, each with git.transfer.plan.hash. copyTree is plan then run. Commit policy: the new commit keeps the source's author, committer, encoding, message and other headers and drops gpgsig, gpgsig-sha256 and mergetag; temp commits are written by ply transfer <ply-transfer@invalid> 0 +0000, so the same plan always gives the same ids. sweepTransfers(dst, { prefix, keep }) deletes temp refs an abandoned transfer left: only names of a temp ref's shape, <prefix><40 hex key>, so a branch, a tag or a near-miss name under the prefix is never deleted. prefix (default refs/ply/transfer/) must be refs/ply/transfer/ or a namespace below it ending in /; anything else ('', refs/, refs/heads/, a prefix without its trailing /, a sibling such as refs/ply/transfer-old/) is bad_request (what: 'prefix') before any request, so a plan made with a tempPrefix outside that namespace leaves temp refs the sweep will not delete. Each request that resumes needs the pack's index and resolved columns again (rescan and resolve the spool, or keep them yourself); there is no serialized form of those yet.
Saved pack index (#260): encodeSavedIndex(index, resolved) turns scanPackIndex's index and, when given, resolvePackRange's columns into bytes the caller stores; decodeSavedIndex(bytes, { trailer, bytes }, maxDeltaChain, maxPackObjects) reads them back, and loadTransferPack(dst, source, saved, { scan, resolve }) does both for a resumed transfer (loaded is saved, resolved or scanned, and it returns the bytes to keep). resolved and saved are an Option (some(value) or none, exported from the root with isSome, isNone, matchOption and the OptionHandlers type; none is one shared object, so never assign to it). isSome and isNone answer false for a value that is not an Option. The root's matchOption(o, { some, none }) returns a Result: Ok with the branch's value, bad_request (what option or handlers) for an argument that is not an Option or a { some, none } pair of functions, and bad_request (what matchOption handler, the thrown value as cause) when the branch throws. decodeSavedIndex is the one call whose error is not a PlyError: its refusal is a typed union a caller branches on (and describeSavedIndexRefusal names), because a refused saved index is an expected outcome that means "scan again", not a failure. Stored bytes are untrusted: a saved index is refused (SavedIndexRefusal, by tag: not_saved_index; version with version; truncated with bytes and want; corrupt; other_pack with saved and want, each a PackIdentity; malformed with field and index; limit_exceeded with what, got and max; bad_argument with what, bytes or want, when decodeSavedIndex is given a bytes that is not a Uint8Array or a want that is not an object) unless it is an intact index of exactly that pack whose columns a scan plus a resolve could have produced, and loadTransferPack then scans again and says why on its span. Where the index carries ids (the default), a REF delta's base recorded as an entry must be the entry whose id it names, in the scan's baseIndex column (malformed baseIndex) and in the resolved base column (malformed resolved.base). A base recorded as not in the pack (baseIndex -1; a thin resolved base, allowed only beside that -1) is not looked up among the ids, so decoding does not show that the pack lacks the object the delta names. Where it carries none (a scan with oids: false), a REF delta with a base recorded in the baseIndex column is refused (malformed baseIndex): a scan without ids records none, and there is no id to check one against. The chain limit is the caller's, never a constant: resolved columns are held to the maxDeltaChain the caller resolves under, so an index saved under a raised limit loads under the same raised limit and is refused as malformed resolved.depth under a lower one, as a resolve would refuse the pack. loadTransferPack takes it from resolve.limits (resolve.limits and scan.limits are each parsed once, before anything is read; limits in either that do not parse are bad_request even when the saved index would have been used). A direct caller of decodeSavedIndex passes it as the third argument, the same limits.maxDeltaChain it gave resolvePackRange; left out, it is the default 64, so stored indexes of packs chained deeper than 64 need it. decodeSavedIndex does not parse that argument (pass a number; loadTransferPack passes a parsed limit). The entry count is held to maxPackObjects, the cap scanPackIndex holds a pack's header count to (100 000 by default, the fourth argument of decodeSavedIndex; loadTransferPack takes it from scan.limits, the limits its scan runs under, so a pack scanned under a raised cap resumes under the same raised cap): an index whose header counts more entries is refused as limit_exceeded (what: 'pack objects', got the header's count, max the limit) before its check is computed or any column is built. The count is read before the index's check, so it is untrusted like the rest: loadTransferPack rescans on that refusal as on any other and records it (refused, and the span's git.transfer.load.refused); a pack really over the cap is then refused by the scan's own header-count check. Decoded columns are views into the bytes passed, not copies (a Node Buffer and a Uint8Array alike; a number column is copied only where it is not aligned in its buffer or the platform is big-endian), so a decoded index holds one copy of the columns: keep the bytes unchanged while the index is in use.
packSubset(source, pack, selection, { extras, outsideBase, resolved }) builds a new pack from chosen entries of an indexed one (scanPackIndex), reading the source through a RangeSource ({ size, read(offset, length, signal) }, the signal optional as above: a file, a buffer, an object store's ranged get; rangeFromBytes wraps bytes) and copying each entry's compressed bytes unchanged. It returns { stream, length, count } with length exact before the first byte, so it feeds pushPack directly. selection is the source's entry indices in the order to write them, which may differ from the source's: each OFS_DELTA's distance is recomputed for its new position, and a REF_DELTA passes through as it is (a Cloudflare Artifacts pack is all REF). An OFS base must be written earlier in the new pack; one left out or written later is refused, or with outsideBase: 'ref' written as a REF_DELTA to the base's id when that id is known. The scan index knows only a whole object's id (oids on). resolved (default null) is resolvePackRange's result for the same pack, and it knows every entry's id, so with it a chain is cut anywhere, below a delta base too; one with another entry count is refused (bad_request, what: 'pack subset resolved'), and an id it gives is checked before it is written (40 lowercase hex, or the entry is refused as above). An oid() that returns nothing at all is refused in those words (bad_request, what: 'pack subset base', "oid() returned nothing", no cause); one that throws, with what it threw as the cause ("oid() threw"). resolved.oid(base) is asked once for each entry rewritten as a REF_DELTA, and the answer that was checked is the one the header carries, so an index that answers differently on a later call changes nothing. Write order: without resolved it is exactly selection. With resolved the pack is written base first: a selected base is moved before the first selected entry that rests on it, through any chain, and entries with no such tie keep the caller's order, so the order written can differ from selection (the ids and the bytes of each entry do not). That matters for REF_DELTA: stock git refuses a thin pack in which a REF_DELTA comes before its base when that base is itself a delta the receiver already holds (index-pack --strict --fix-thin: "The same object … appears twice in the pack"). Without resolved a REF_DELTA's base inside the selection cannot be told from one outside it, so that order is the caller's to get right, and a selection listing such a delta before its base still builds a pack strict git refuses; planPackBatches batches are base first either way. A REF base outside the selection makes the pack thin: the receiver supplies the base or refuses. extras are small objects ply encodes (a commit, a generated tree), deflated up front and written last; their base may be none or a REF. An extra a pack cannot hold is refused (bad_request, what: 'pack subset extras') before anything is read or deflated, never thrown: extras itself when it is not an array (null, a number, an array-like; left out or undefined is no extras), one that is not an object (null, undefined), data that is not a Uint8Array, a whole object whose type is not 1 to 4 (commit, tree, blob, tag), an OFS base, a REF base that is not a 40-hex id. Consecutive source entries are one range read; the SHA-1 trailer is computed while streaming; a range that serves the wrong number of bytes errors the stream (pack_corrupt) before the trailer. selection is copied at the call, so changing the array afterwards changes nothing that is written. Cancel. packSubset takes no signal (a signal key in its options is not read): it is cancelled through the stream it returns. Cancelling the stream settles at once, whether or not the source ever answers: the signal given to read aborts with the consumer's reason (an AbortError when it gave none), the range in flight is cancelled with that same reason and not waited for, and a range that opens afterwards is cancelled too. A range whose getReader is the platform's own (ReadableStream.prototype.getReader: a ReadableStream, or a subclass that does not define its own) is read through that reader (its cancel() settles a read in flight, so each chunk is read with no added promise); any other range, a ReadableStream subclass that defines its own getReader included, is read through the reader its own getReader() returns. A range that is refused (it served more bytes than were asked for) or left unread is cancelled with null. A source that inspects the reason used to see undefined. Held: 17 bytes per selected entry (the copied index, its kind, its base's position, its new offset), 5 per source entry, the 20-byte base id of each entry rewritten as a REF_DELTA (kept in a map until the stream ends; from the code, not measured), the extras, and the chunk in flight; with resolved, also the base-first order (a second array of entry numbers, 4 bytes per selected entry, kept until the stream ends) and 1 more byte per source entry while ordering (these two from the code, not measured). Measured without resolved (test/pack-subset-child.mjs, Node 24): half of a 537 MB source, 268 MB written, 6 KB live.
Things the oracle taught us (would have been wrong otherwise)
The whole fetch product space (haves, shallow, deepen-since/not, blob:limit, combine, thin, negotiation) is in
SAFETY.md; the short version: git has two object-selection modes (bitmap = exact set difference; traversal = edge-tree heuristics),--thinchanges which objects are excluded, shallow boundaries are grafts rather than negative refs, andhaveprocessing is order-dependent.filter tree:Nincludes blobs at depth < N. It is not a subset ofblob:none;combine:blob:none+tree:Nis. (test/oracle.test.js)git's
patch_deltarejects deltas shorter thanDELTA_SIZE_MIN= 4 bytes, which is exactly what "delete the whole file" encodes to. Degenerate deltas are sent as full objects. (found by fuzz seed 3359247)receive-packunpacks the pack before checkingold, so a lost CAS race leaves dangling objects server-side. The conflict is still atomic for the ref. (test/concurrency.test.js)Identical replacement would have produced an empty commit. Now a
noop. (fuzz)
Test loop
npm test runs the push matrix as a seeded 1-in-8 sample (~2 min; the seed rotates daily, PUSH_MATRIX_SEED=<n> reproduces a day); npm run test:push-full runs all 1,400 cells (~20 min). Coverage: 100% of lines across every src/ module (npm run coverage), with the matrix excluded because it adds time, not lines.
npm run lint # oxlint; no-magic-numbers on the wire decoders (0 and 1 are the only allowed literals)
npm run test:props # ~5 s: pure step functions — chunking invariance, codec roundtrips, node:zlib/crypto oracles
npm run test:mutate # Stryker across src/. Full run locally and on main; a PR mutates only the src lines it changes
npm run fuzz:below-hash -- --n 20 --seed 1 # mutate decompressed objects, re-hash, fetch, compare with git fsck --strict
npm run test:oracle # ~5 s: real git — tree oids vs write-tree, git pack-objects (ofs-delta, 5 window/depth/compression combos) parsed to cat-file truth, verify-pack chain depths, index-pack --fix-thin accepts our thin packs, filter semantics, 6-writer CAS convergence
npm run fuzz -- --n 200 # ~30 s: steered generative cases against git http-backend
npm run test:git # ~15 min: fsck/check-ref-format/mktree compliance, clone/fetch parity with git's client, 768-cell push matrix vs git push
npm run test:protocol # ~4 min: exhaustive fetch matrix (14,256 cells) vs pack-objects + captured upload-pack invocation
npm run fuzz:protocol -- --n 500 # random wants/haves/deepen/filter/thin/negotiate/shallow on generated DAGs
npm run trace -- fuzz-out/trace.jsonl git.receive-pack "git.push.ok==false"An equivalent mutant stays only as // Stryker disable next-line <Mutator>: <reason> on that line. A blanket Stryker disable all, or dropping a parser file from the Stryker config, fails npm run test:mutate. See SAFETY.md.
The fuzzer
test/fuzz/gen.js draws from a product space of named classes: blob content (empty tiny text random repetitive boundary big binaryish), match position (start end middle chunk16k chunk32k chunk64k random), find/replace length classes (incl. >127 for insert-op chunking, 64K copy-op boundaries, empty), server core.compression 0…9/−1 (stored / fixed / dynamic Huffman blocks), path depth 1…10, sibling shape (none few many sortedge: names that sort differently as dir vs file, unicode, leading -), history depth (so deepen 1 reports shallow), file mode, and intended outcome (ok noop zero_matches two_matches missing_path not_a_file cas_conflict — the CAS case injects a competing push between our ls-refs and our receive-pack via fetchImpl).
Each case is checked against git: ref advanced to our commit, cat-file bytes equal the expected splice, diff --name-only -z touches exactly the path, parent/author/message, tree oid, mode preserved, fsck --strict, plus two efficiency properties — push bytes ≤ 220 + 80·depth + |replace| + ⌈|replace|/127⌉ + 5·⌈|replace|/16K⌉ + 16·⌈|blob|/64K⌉ and max single allocation ≤ 70 KB regardless of blob size — then a second edit that must hit the tree cache at every level. Failures write fuzz-out/fail-<seed>.jsonl and print --case <seed> to replay.
Steering
After each case the spans are bucketized (buckets() in run.mjs): inflate block types seen, pkt-line carry across TCP reads, max-size pkts, sideband frames, multi-chunk scans, matches straddling a chunk, delta op counts, chain depths, tree sizes, outcomes, push ratio, allocation high-water. 55% of cases target the least-covered bucket via a bucket→knob map (TARGETS), 20% mutate one knob of a case that hit a rare bucket, 25% are uniform. The run prints the coverage table and any TARGETS never reached.
Layout
src/sha1.js streaming SHA-1 (subtle.digest can't stream)
src/inflate.js zlib/deflate inflate that returns bytes consumed (packs have no length prefix)
src/pktline.js pkt-line encode; decoder as pure (state, chunk) → {state, frames}
src/pack.js pack parse/resolve, delta apply/generate, thin pack build
src/objects.js blob/tree/commit codecs, tree sort (dir-as-slash)
src/client.js v2 ls-refs/fetch (streamed sideband), v0 receive-pack; request bodies & response state machine are pure
src/edit.js the pipeline; single-object pack stream + find/replace scanner as pure step functions
src/otel.js OTLP/JSON tracer, one ExportTraceServiceRequest per line
src/bytes.js alloc accounting (Mem), concat, indexOfProd lib is ~1100 lines. Tests are the rest.