Artifactspublic-v0

ply

main
ply4 git calls10 ms102 KiB3 cachedprotocol v2
832 lines176 KiBRaw

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:

sh
npm install github:ivarvong/ply              # the default branch, as of now
npm install github:ivarvong/ply#<commit-sha>  # recommended: pin a commit for reproducible builds

It 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 managerdefault--ignore-scripts
npm 11.16.0builds dist/; imports workexits 0, no dist/
pnpm 8.15.9builds 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.22exits 0 without running prepare, no dist/exits 0, no dist/
bun 1.2.18exits 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.getRandomValues and Uint8Array (a browser works behind a CORS proxy). ply/tree-node, ply/checkout-node and ply/repo-node are Node only (node:fs).
  • TypeScript (optional): the shipped declarations compile with skipLibCheck: false under lib: ["ES2022"] with @types/node 20, 22 or 24, under the DOM lib, and under @cloudflare/workers-types. npm run check:dist and test/dist-types.test.js compile each of those five consumers (pinned: @types/node 20.19.43, 22.20.5 and 24.19.2, @cloudflare/workers-types 5.20260916.1, TypeScript 7.0.2, nodenext resolution) 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 true to push; nothing else). A stock git server works: without uploadpack.allowFilter its advertisement has no filter, 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 as unsupported (what: 'protocol version') on the first ls-refs.
  • Auth, per call in opts.auth: { token } (HTTP Basic with user x-access-token, which GitHub tokens use), { token, user } (a host that wants a username: GitLab oauth2 for an OAuth token, your Gitea/Forgejo user), { bearer }, or { header } (an Authorization value sent as is). Or userinfo in the URL (https://<token>@host/…), sent as git sends it. No auth and 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.

js
// 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 empty

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

js
// 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 at

Read a commit, a directory, and a file (streamed, hash-checked as it is read).

js
// 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.

js
// 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 pushed

Several changes in one commit, applied in order.

js
// 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 change

Branches: 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).

js
// 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).

js
// 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 names

Rebase, cherry-pick, revert. Each replays commits with the same three-way merge and pushes with the old tip as the compare-and-swap.

js
// 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 main

History, first parent, newest first (git log --first-parent).

js
// 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).

js
// 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 outDir

Delete 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).

js
// 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:

js
// 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.

js
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.noop

Every 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 passederror.whaterror.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 overafter
throws a value that is not a PlyErrorbad_request, what: 'callback', cause the thrown valueambiguous, 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 PlyErrorthat PlyError, as itselfambiguous, what: 'callback', cause the thrown error, its code in original (a thrown ambiguous is itself)
returns a Resultthat Result, as it isthat 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):

ts
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

#RequestResponseWhy
1v2 ls-refs with ref-prefixone linehead oid
2v2 fetch want <commit> filter tree:0 deepen 1 done1-object packcommit only (~300 B)
3…N+2v2 fetch want <tree> filter tree:0 per level1-object pack eachonly the trees on the path; cached by oid (immutable)
N+3v2 fetch want <blob>1-object pack, streamedinflate → scan → SHA-1, never materialized
N+4v0 receive-pack thin packunpack ok / ngcommit 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 }) as fetchImpl: 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 under sha256(url, credential, body). The answer streams to the caller and, through a verifier, into cache.put; without verifyBeforeStore nothing on the cache path holds a whole answer (with it, a MISS holds up to three times limits.maxPackBytes, below). The verifier keeps one pkt-line frame of state and errors the body handed to put at the first violation or at the end: pkt-line framing complete to the final flush, no ERR packet, no sideband channel-3 message and, when there is a packfile section, a PACK v2/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 to limits.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 has crypto.DigestStream (Workers) it is the native digest, not measured here. An acknowledgments-only fetch answer (a round that ends on its NAK/ACK lines, to a request without done) is refused and not stored, as verifyFetchAnswer refuses it ("answer: no packfile section"). The answer to another command a caller's own shouldCache admits (ls-refs) is checked for framing and ERR only, and is cacheable. A failed or cut answer still reaches the caller and is not stored, so one bad exchange is not replayed: PackCache.put takes 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 in stats.verifyFailed with the reason in stats.verifyError (git.pack.cache.verify.failed / .verify.error on the span). A delete that fails there, by rejecting or by throwing, is ignored and does not reject the promise handed to waitUntil. The store never paces the caller: the cache branch queues at most CACHE_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.parsed counts 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, protocol or remote_error: a flipped pack byte, a cut or empty entry, a wrong pack trailer, a stored ERR) is deleted and asked for once more from the origin (x-ply-cache: bust, answered x-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, unless verifyBeforeStore: true: that widens the rule to every wants-only fetch and stores an answer only after verifyFetchAnswer accepted the whole of it (every want present, every object hashed; openBlob has 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 times limits.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's shouldCache), is not stored and is counted in stats.verifyFailed (nothing was put, so no key is deleted); stats.verifyOk counts only the answers handed to put, not every answer the streaming verifier passed. When the put is called differs: without the flag it is called inside the fetch on every MISS, before the fetch answers (a put that throws when called is that fetch's 'cache.put' Err, and the answer is cancelled first); with it, only once verifyFetchAnswer accepted the answer, after the fetch answered, so a put that throws or rejects then is stats.putFailed (putError the '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 most maxBytes of bodies and header text (default LIMIT_MEMORY_CACHE_BYTES, 64 MiB) in at most maxEntries entries (default LIMIT_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.5 is 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 last newCommit). 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.hint is '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.

js
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:

js
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: an ERR line (capabilities, ls-refs, fetch), band 3 (fetch; push, in the ambiguous message), 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 attribute git.push.band2.tail is escaped the same way. These still carry the server's text as received, so escape them before printing: the span attributes git.push.remote.messages, git.push.ng.reason, git.fetch.sections and the fetch progress text (git.sideband.progress.tail), hookOutput, the lines and rejected detail fields, the ng reason quoted in a push_rejected, cas_conflict or push_partial message, and the object-format name in an unsupported message. A credential the server echoes in an ERR line (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, sidebandStep and parseCapabilitiesV2 take 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: frames fills the span you pass with git.service, git.request.bytes (a StreamBody's length), http.request.method, url.full (redacted), http.response.status_code, git.response.bytes, git.response.first_byte_ms and 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):

js
// 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.

js
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 tag

Refspecs 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):

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

js
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 .git

Every 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 on base's head and creates ref (zero old-oid: the CAS means "must not exist yet").

  • mergeBranch(url, { ref, from, author }) lands from into ref: merge-base via commit-only packs, then up_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 is merge_conflict with 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. .gitattributes merge drivers apply when you say which tree supplies them — attributes: 'ours' (what git merge in a worktree reads), 'theirs', 'base', a ref or commit (attr.tree), or null (default: none, as git ≥ 2.46 does in a bare repository): -merge/binary conflict, merge=union keeps 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 is merge_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). conflicts lists 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 at limits.maxMergeWork steps per merged file (2^32 in DEFAULT_LIMITS, 2^26 in WORKER_LIMITS), answering too 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/diffScript take maxWork (the same budget, absolute, for that call) and a meter ({ steps }) to change and read it. The count is kept inside the call, from zero: the meter is only written (its steps is 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 over maxBytes, driver: 'binary') and never read, so one meter reused across files, or one that is not an object (an array is one and gets a steps property; a function is ignored), changes no result, and a meter whose write throws (a setter, a Proxy's set trap, a revoked Proxy) is dropped with the result unchanged; a maxWork that is not a non-negative finite number (NaN, Infinity, a negative, a string) reads as the default, and a limits.maxMergeWork that is not one is bad_request like any other limit. Neither function throws on any meter or maxWork value (an unknown driver still 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-line a/b/c files: 5,370,282 steps for the diff) and such a file reaches too large to merge sooner.

  • createBranch(url, { ref, from }), deleteBranch(url, { ref, expected? }) and createTag(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/target is a ref name (resolved as readCommit resolves one; an annotated tag is peeled) or a 40-hex commit id the server must have. A ref that already exists is cas_conflict (expected the zero id, actual its tip), as a create is in editFile; a delete whose expected is not the tip is cas_conflict before anything is sent, and one that loses a race to another writer after ls-refs is cas_conflict with actual the ref read back (null only when it was deleted); an absent ref is not_found; what the server refuses (deleting the branch HEAD names) is its push_rejected. verify: true reads a created ref back. On a transport you already hold: fastForward(t, { ref, from, to }) and deleteRef(t, { ref, oid }).

  • rebaseBranch(url, { ref, onto, committer }) replays the branch's linear chain onto onto'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=drop does and listed in dropped. One difference from git rebase stands: git leaves out a commit whose patch id equals a commit already in onto before it replays anything (its default, --no-reapply-cherry-picks); ply computes no patch ids and replays every commit, which is git 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: true makes one commit; its default message is the replayed messages joined by blank lines (what git rebase -i writes for pick, squash, …). cherryPick / revertCommit are 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 is outcome: 'kept_empty'. The default empty: 'stop' reports outcome: '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's Revert "<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:

    opbaseourstheirscommit
    mergemerge-base treemainbranchparents [main, branch]
    rebase (per commit)commit's parent treenew tipcommitparent [new tip]
    squashmerge-base treemainbranch tipparent [main]
    cherry-pickcommit's parent tree (empty tree, if the commit is a root)targetcommitparent [target]
    revertcommit treetargetcommit'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: true opts in to editing the pointer itself.
  • Signed commits: pass signer (from ed25519Signer({ privateKey, publicKeyRaw }) or generateSigner()) and the commit carries an SSH signature (PROTOCOL.sshsig, Ed25519 via WebCrypto — Workers and node). Verified by git verify-commit and ssh-keygen -Y verify in test/sign.test.js; satisfies "require signed commits" branch protection with the public key registered as a signing key. signCommit(commitBytes, signer) and withGpgsig(commitBytes, signature) sign any encoded commit, including one with no body section (encodeCommit with no message): the signed object without its gpgsig header is the input byte for byte. (Before, such a commit came back with a blank line added after the headers, so git verify-commit rejected 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 means

Each 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 carries git.transport and server.address. git.request.bytes is 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; on git.receive-pack it is then set again to the bytes actually sent), and absent when the GET ply makes before a POST fails first. git.response.bytes is 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 carries git.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 no git.response.bytes of its own. The GET ply makes on a POST's own span (before the first POST under followRedirects: '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) sets git.response.bytes there 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 to POST for the first POST under followRedirects: 'initial', but a span re-sent after a stale redirect memo ends with http.request.method (GET, from the re-settling GET) beside the re-sent POST's status, git.request.bytes and git.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 of test/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.

js
const spans = [];
const tracer = new Tracer({ onEnd: s => spans.push(s) });  // s.attrs['git.response.bytes'] is a number; no OTLP built

Span 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_from to the span it follows, and that span carries ply.link=followed_by back if it was still open when the follower started (git.read → git.read.blob; git.checkout.blobs → each streamed git.read.blob). Links per span are capped at maxEvents, the rest counted in droppedLinksCount.
  • 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 unread fetch body.
  • 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, a StreamBody), 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 as firstByteTimeoutMs. 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: idleTimeoutMs and firstByteTimeoutMs fire 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's signal is 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; heldTimeoutMs bounds 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 code timeout and limit: '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: idleTimeoutMs or heldTimeoutMs, whichever is smaller (heldTimeoutMs when 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's signal or requestTimeoutMs.
  • 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.

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

js
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), --thin changes which objects are excluded, shallow boundaries are grafts rather than negative refs, and have processing is order-dependent.

  • filter tree:N includes blobs at depth < N. It is not a subset of blob:none; combine:blob:none+tree:N is. (test/oracle.test.js)

  • git's patch_delta rejects deltas shorter than DELTA_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-pack unpacks the pack before checking old, 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, indexOf

Prod lib is ~1100 lines. Tests are the rest.

1# ply
3Zero-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).
5Every 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.
7The hosted HTTP API and the public repository viewer live in [ply-web](https://github.com/ivarvong/ply-web) (the Cloudflare Worker `ply`). This repository is the git client.
9## Install
11ply is not on npm (the npm name `ply` belongs to another package). Install it from GitHub; npm builds `dist/` on install:
13```sh
14npm install github:ivarvong/ply # the default branch, as of now
15npm install github:ivarvong/ply#<commit-sha> # recommended: pin a commit for reproducible builds
16```
18It 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.
20ply 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`).
22The 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:
24| package manager | default | `--ignore-scripts` |
25|---|---|---|
26| npm 11.16.0 | builds `dist/`; imports work | exits 0, no `dist/` |
27| 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/` |
28| yarn 1.22.22 | exits 0 without running `prepare`, no `dist/` | exits 0, no `dist/` |
29| 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/` |
31With 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.
33## Beta
35ply 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](#telemetry-contract)).
37## Requirements
39- **Runtime**: Node ≥ 20, Cloudflare Workers, or any runtime with `fetch`, `CompressionStream`/`DecompressionStream`, `crypto.getRandomValues` and `Uint8Array` (a browser works behind a CORS proxy). `ply/tree-node`, `ply/checkout-node` and `ply/repo-node` are Node only (`node:fs`).
40- **TypeScript** (optional): the shipped declarations compile with `skipLibCheck: false` under `lib: ["ES2022"]` with `@types/node` 20, 22 or 24, under the `DOM` lib, and under `@cloudflare/workers-types`. `npm run check:dist` and `test/dist-types.test.js` compile each of those five consumers (pinned: `@types/node` 20.19.43, 22.20.5 and 24.19.2, `@cloudflare/workers-types` 5.20260916.1, TypeScript 7.0.2, `nodenext` resolution) 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.
41- **A git smart-HTTP server**: GitHub, GitLab, Gitea/Forgejo, Cloudflare Artifacts, or self-hosted `git http-backend` (`http.receivepack true` to push; nothing else). A stock git server works: without `uploadpack.allowFilter` its advertisement has no `filter`, 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 as `unsupported` (`what: 'protocol version'`) on the first ls-refs.
42- **Auth**, per call in `opts.auth`: `{ token }` (HTTP Basic with user `x-access-token`, which GitHub tokens use), `{ token, user }` (a host that wants a username: GitLab `oauth2` for an OAuth token, your Gitea/Forgejo user), `{ bearer }`, or `{ header }` (an `Authorization` value sent as is). Or userinfo in the URL (`https://<token>@host/…`), sent as git sends it. No `auth` and no userinfo: anonymous. Credentials never reach a span or an error message; redirects are not followed. Details in "Credentials" under [More detail](#more-detail).
44What 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](#guards-and-policy)); 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).
46## Quick start: a repo end to end
48Every 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.
50```js
51// quick-start: setup
52const url = 'https://git.example.com/acme/site.git'; // an existing repository, empty or not
53const opts = { auth: { token: process.env['GIT_TOKEN'] } }; // add tracer: new Tracer({ exporter }) to export spans
54const author = { name: 'Release Bot', email: 'bot@example.com' }; // time defaults to now, tz to +0000
55const outDir = './site-checkout'; // checkoutDir writes here; it must be absent or empty
56```
58**First 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.
60```js
61// quick-start: first-commit
62import { pushTree } from 'ply';
64const first = await pushTree(url, {
65 ref: 'refs/heads/main',
66 files: {
67 'README.md': '# site\n',
68 'src/config.ts': 'export const VERSION = "1.2.3";\n',
69 'bin/build': { data: '#!/bin/sh\necho build\n', mode: '100755' },
70 },
71 author, message: 'Initial commit',
72}, opts);
73if (!first.ok) throw first.error;
74console.log(first.value.newCommit); // the commit id main now points at
75```
77**Read** a commit, a directory, and a file (streamed, hash-checked as it is read).
79```js
80// quick-start: read
81import { readCommit, listTree, readFile } from 'ply';
83const head = await readCommit(url, { ref: 'main' }, opts);
84if (!head.ok) throw head.error;
85if ('empty' in head.value) throw new Error('main has no commits yet');
86console.log(head.value.oid, head.value.tree, head.value.parents, head.value.message);
88const listing = await listTree(url, { ref: 'main', path: 'src' }, opts);
89if (!listing.ok) throw listing.error;
90for (const e of listing.value.entries) console.log(e.mode, e.type, e.oid, e.name); // as git ls-tree prints them
92const file = await readFile(url, { ref: 'main', path: 'src/config.ts' }, opts);
93if (!file.ok) throw file.error;
94const config = await new Response(file.value.stream).text(); // read the stream to the end (or cancel it)
95console.log(file.value.size, config);
96```
98**Edit one file**: find exactly one occurrence and replace it. The blob streams through; the push is a delta.
100```js
101// quick-start: edit
102import { editFile } from 'ply';
104const bump = await editFile(url, {
105 ref: 'refs/heads/main', path: 'src/config.ts',
106 find: 'VERSION = "1.2.3"', replace: 'VERSION = "1.2.4"',
107 author, message: 'Bump version to 1.2.4',
108}, opts);
109if (!bump.ok) throw bump.error; // match_count when find is not there exactly once
110console.log(bump.value.newCommit, bump.value.noop); // noop: find === replace, nothing pushed
111```
113**Several changes in one commit**, applied in order.
115```js
116// quick-start: commit-changes
117import { commitChanges } from 'ply';
119const change = await commitChanges(url, {
120 ref: 'refs/heads/main',
121 changes: [
122 { kind: 'create', path: 'docs/intro.md', content: '# Intro\n' }, // refuses a path that exists
123 { kind: 'write', path: 'README.md', content: '# site\n\nHello.\n' }, // creates or overwrites
124 { kind: 'edit', path: 'src/config.ts', find: '1.2.4', replace: '1.3.0' }, // exactly one match
125 { kind: 'delete', path: 'bin/build' }, // a file or a whole directory
126 { kind: 'rename', from: 'docs/intro.md', to: 'docs/index.md' },
127 ],
128 author, message: 'Docs; version 1.3.0',
129}, opts);
130if (!change.ok) throw change.error;
131console.log(change.value.outcome, change.value.oid); // 'commit', or 'noop' when the tree did not change
132```
134**Branches**: 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).
136```js
137// quick-start: branch-merge
138import { createBranch, mergeBranch } from 'ply';
140const feature = await createBranch(url, { ref: 'refs/heads/feature', from: 'main' }, opts);
141if (!feature.ok) throw feature.error; // cas_conflict when the branch already exists
143const work = await commitChanges(url, {
144 ref: 'refs/heads/feature',
145 changes: [{ kind: 'create', path: 'src/feature.ts', content: 'export const feature = true;\n' }],
146 author, message: 'Add feature flag',
147}, opts);
148if (!work.ok) throw work.error;
150const hotfix = await editFile(url, { // main moves on meanwhile
151 ref: 'refs/heads/main', path: 'README.md', find: 'Hello.', replace: 'Hello, world.', author, message: 'Fix greeting',
152}, opts);
153if (!hotfix.ok) throw hotfix.error;
155const merged = await mergeBranch(url, { ref: 'refs/heads/main', from: 'refs/heads/feature', author }, opts);
156if (!merged.ok) throw merged.error;
157console.log(merged.value.outcome, merged.value.oid); // 'merge': a commit with parents [main, feature]
158```
160**Tags**: lightweight (the ref names the commit) or annotated (a tag object with a tagger and message).
162```js
163// quick-start: tag
164import { createTag } from 'ply';
166const release = await createTag(url, { name: 'v1.3.0', target: 'refs/heads/main' }, opts);
167if (!release.ok) throw release.error;
168const notes = await createTag(url, { name: 'v1.3.0-notes', target: release.value.commit, message: 'Release 1.3.0', tagger: author }, opts);
169if (!notes.ok) throw notes.error;
170console.log(notes.value.oid, notes.value.commit); // the tag object, and the commit it names
171```
173**Rebase, cherry-pick, revert.** Each replays commits with the same three-way merge and pushes with the old tip as the compare-and-swap.
175```js
176// quick-start: rebase-pick-revert
177import { rebaseBranch, cherryPick, revertCommit } from 'ply';
179const topic = await createBranch(url, { ref: 'refs/heads/topic', from: 'refs/heads/main' }, opts);
180if (!topic.ok) throw topic.error;
181const 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);
182if (!onTopic.ok) throw onTopic.error;
183const onMain = await commitChanges(url, { ref: 'refs/heads/main', changes: [{ kind: 'create', path: 'CHANGELOG.md', content: '1.3.0\n' }], author, message: 'Changelog' }, opts);
184if (!onMain.ok) throw onMain.error;
186const rebased = await rebaseBranch(url, { ref: 'refs/heads/topic', onto: 'refs/heads/main', committer: author }, opts);
187if (!rebased.ok) throw rebased.error; // topic's commits replayed onto main's tip
189const picked = await cherryPick(url, { ref: 'refs/heads/main', commit: rebased.value.oid, committer: author }, opts);
190if (!picked.ok) throw picked.error; // outcome 'ok', or 'empty' when main already has the change (nothing written)
192const reverted = await revertCommit(url, { ref: 'refs/heads/main', commit: picked.value.oid, committer: author }, opts);
193if (!reverted.ok) throw reverted.error; // a 'Revert "Add topic"' commit on main
194```
196**History**, first parent, newest first (`git log --first-parent`).
198```js
199// quick-start: history
200import { readLog } from 'ply';
202const log = await readLog(url, { ref: 'refs/heads/main', limit: 10 }, opts);
203if (!log.ok) throw log.error;
204for (const c of log.value.commits) console.log(c.oid.slice(0, 7), c.parents.length, c.message.split('\n')[0]);
205```
207**Check out a whole tree**: as streams (Workers-safe), or into a directory (Node, laid out as `git clone` would, without `.git`).
209```js
210// quick-start: checkout
211import { checkoutTree } from 'ply';
212import { checkoutDir } from 'ply/checkout-node';
214const tree = await checkoutTree(url, { ref: 'v1.3.0' }, opts);
215if (!tree.ok) throw tree.error;
216for await (const f of tree.value.files) {
217 if (f.stream) console.log(f.path, f.mode, (await new Response(f.stream).arrayBuffer()).byteLength); // read each stream
220const written = await checkoutDir(url, { dir: outDir, ref: 'main' }, opts);
221if (!written.ok) throw written.error;
222console.log(written.value.written.files); // files written under outDir
223```
225**Delete 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`).
227```js
228// quick-start: refs
229import { listRefs, deleteBranch, deleteTag } from 'ply';
231const refs = await listRefs(url, {}, opts); // branches and tags; { prefixes: ['refs/heads/'] } for branches only
232if (!refs.ok) throw refs.error;
233console.log(refs.value.head, refs.value.refs.map(r => r.name)); // 'refs/heads/main', [ 'refs/heads/feature', … ]
235const gone = await deleteBranch(url, { ref: 'refs/heads/feature', expected: work.value.oid }, opts);
236if (!gone.ok) throw gone.error; // cas_conflict when feature moved off that commit; not_found when it is gone
237const untagged = await deleteTag(url, { name: 'v1.3.0-notes' }, opts);
238if (!untagged.ok) throw untagged.error;
239```
241**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:
243```js
244// quick-start: errors
245import { assertNever } from 'ply';
247const stale = await editFile(url, {
248 ref: 'refs/heads/main', path: 'src/config.ts', find: 'VERSION = "9.9.9"', replace: 'VERSION = "10.0.0"', author, message: 'Bump',
249}, opts);
250if (!stale.ok) {
251 const e = stale.error;
252 switch (e.code) {
253 case 'cas_conflict': // the ref moved between read and push (editFile already redid it once): read again, redo
254 console.warn('moved', e.expected, e.actual); break;
255 case 'match_count': // find matched e.matches times, not once: the file is not what you expected
256 console.warn('matches', e.matches); break;
257 case 'not_found': // e.miss.kind: 'ref' | 'path' | 'repository' | 'head_unborn' | 'commit' | …
258 console.warn('missing', e.miss.kind); break;
259 case 'auth': // 401/403: the credential is missing, wrong, or lacks write access
260 console.warn('auth'); break;
261 case 'limit_exceeded': // a limits.* bound (e.what, e.got, e.max): raise it with withLimits, or do less per call
262 console.warn('limit', e.what, e.got, e.max); break;
263 case 'ambiguous': // the push was sent and may have landed: read the ref back before doing anything else
264 console.warn('unknown outcome'); break;
265 case 'network': case 'timeout': case 'rate_limited': case 'upstream_5xx': case 'protocol': case 'pack_corrupt':
266 console.warn('transient: retry with backoff', e.code); break; // isRetryable(e) is true for exactly these
267 case 'merge_conflict': case 'not_fast_forward': case 'not_linear': case 'unrelated_histories':
268 console.warn('history needs a human', e.code); break;
269 case 'push_rejected': case 'push_partial': case 'remote_error': // a hook, branch protection, or the server said no
270 console.warn('refused', e.message); break;
271 case 'bad_request': case 'unsupported': case 'lfs_pointer': case 'http': case 'not_git': case 'aborted': case 'internal':
272 console.warn('fix the call or the setup', e.code, e.message); break;
273 default:
274 assertNever(e);
275 }
277```
279`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.
281## More detail
283`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.
285`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.
287`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`.
289**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.
291`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](https://github.com/ivarvong/ply-web) also uses these entry-point exports: `validateIdent`, `validateRef`, `validatePath`, `concat`, `limitError`, `isFilterRejection`, `fromAny`, `packParseOpts`.
293```js
294import { editFile, Tracer, consoleExporter } from 'ply';
296const 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] }] }] }
297const cache = new Map(); // trees by oid, reused across edits
298const r = await editFile('https://github.com/o/r.git', {
299 ref: 'refs/heads/main', path: 'src/config.ts',
300 find: 'VERSION = "1.2.3"', replace: 'VERSION = "1.2.4"',
301 author: { name: 'bot', email: 'bot@x' }, message: 'bump',
302}, { auth: { token: process.env.GIT_TOKEN }, tracer, cache });
303if (!r.ok) {
304 switch (r.error.code) { /* exhaustive over Code: every case, no default, then assertNever(r.error) */ }
306// r.value.newCommit, r.value.pushBytes (≈ 300 + |replace| + 80·depth), r.value.noop
307```
309Every public function returns a `Result` (0.2.0): `{ ok: true, value }` or `{ ok: false, error }`, never a throw. `error`
310is a `PlyError`: an `Error` with a `code` from a closed union, so `switch (r.error.code)` with no `default` is checked
311exhaustive by the compiler. The one exception is `decodeSavedIndex`, whose `error` is the typed `SavedIndexRefusal`
312(a plain object; `switch (r.error.tag)` over its eight tags, see Saved pack index below), because a refused saved index
313means "scan again", not a failure. A stream (`readFile`'s `stream`, `checkoutTree`'s `files`) reports a failure the way a
314stream does: it errors, with that same `PlyError`.
316Your own code failing is an `Err` too. When a function you passed throws or rejects, the `Err` carries the thrown
317value, untouched, as `error.cause` (ply writes nothing on it), and `error.what` says whose it was. These are named:
319| you passed | `error.what` | `error.code` |
320| --- | --- | --- |
321| `signer` (its `sign` fails, or returns a non-string) | `'signer'` | `bad_request` |
322| `filter` (`pushDir` / `filesFromDir`) | `'filter'` | `bad_request` |
323| `transport`: `frames()` throws, or its stream rejects | `'transport.frames'` | `bad_request` on a read request; `ambiguous` on the push request |
324| `transport`: `advertise()` throws or rejects | `'transport.advertise'` | `bad_request` |
325| `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` |
326| `cachingFetch`'s `shouldCache`, `waitUntil`, or the cache's `match` / `delete` / `put` throws when called | `'shouldCache'`, `'waitUntil'`, `'cache.match'`, `'cache.delete'`, `'cache.put'` | `bad_request` |
328Every other function you pass ends in the backstop: a throw from it that reaches the end of an operation (`editFile`,
329`commitChanges`, `pushTree`, merge, rebase, pick, and an `operation()` body together with every callback reached from
330it) is `what: 'callback'` with the thrown value as `error.cause`. For an `operation()` body this is a **breaking change
331since #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
332whose `match` or `delete` promise rejects is a miss, a `put` that rejects is counted in `stats` (`putFailed`,
333`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),
334and 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
335error, as it is. The outcome class follows the push: before the push request was handed to the transport nothing can
336have moved, so the failure is definite (the code in the table; the backstop is `bad_request`, retry `no`); once it
337was, the ref may have moved, so it is `ambiguous` (read the ref back): a named failure on a later read is then the
338`cause` of that `ambiguous`, and the backstop puts the replaced code, if the thrown value had one, in
339`error.original`. `pushDir` and `filesFromDir` also return node:fs's own failures (a missing directory, an unreadable
340file) as `bad_request` with `what: 'dir'` and the node error (its `code` such as `ENOENT` or `EACCES`, its `path`) as
341`error.cause`. This holds whatever the thrown value is: one that cannot be described (a null-prototype object, an
342object whose `message` getter or `toString` throws, a revoked Proxy) still ends as that `Err`, whose message says
343`a value with no string form` and whose `cause` is the value. Telemetry callbacks are different: they never change the
344outcome at all (see `onTelemetryError`).
346### `operation()`: your body's outcomes
348**Breaking change since #277.** In `operation(op, url, opts, body)`, a throw from `body` (or from any callback
349reached from it) never reaches you as a throw or a rejection. This covers `body` only: a caller tracer whose `start()`
350throws, or an `opts.link` whose `span` is null or undefined (or whose `traceId`/`spanId` getter throws), still rejects
351before `body` runs. What you get back depends only on what was thrown and on whether a push request had been handed to
352the transport (the first `t.frames()` call for a service other than `git-upload-pack`) when it was thrown:
354| `body` … | before the push request was handed over | after |
355| --- | --- | --- |
356| 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) |
357| throws a `PlyError` | that `PlyError`, as itself | `ambiguous`, `what: 'callback'`, `cause` the thrown error, its code in `original` (a thrown `ambiguous` is itself) |
358| returns a `Result` | that `Result`, as it is | that `Result`, as it is |
360So a callback's own throw is treated as a failure, never as an answer: a definite `cas_conflict` you learned and then
361threw after the push is reported `ambiguous`. Return expected outcomes as values, a discriminated union inside the
362`Ok` (the pattern ply-web adopted in ivarvong/ply-web#153):
364```ts
365type Bump = { tag: 'bumped'; commit: string } | { tag: 'conflict'; reason: 'ref_exists' | 'stale_expected' };
366const r = await operation<Bump>('bump', url, opts, async ({ t, root, outcome }) => {
367 // … read refs over t …
368 if (exists) return outcome('conflict', { tag: 'conflict', reason: 'ref_exists' });
369 // … push over t …
370 return outcome('ok', { tag: 'bumped', commit });
371});
372if (!r.ok) return status(r.error); // ply's failure, or your crash (what: 'callback')
373if (r.value.tag === 'conflict') return conflict409(r.value.reason);
374```
376`test/operation-callback-contract.test.js` pins each row.
378### Upgrading from 0de5ad4-era releases
380Before #277 a value thrown from an `operation()` body reached the caller unchanged, so some consumers threw their own
381errors through it for control flow (ply-web's `ref_exists` and `stale_expected` 409s). Those now arrive as
382`bad_request` (`what: 'callback'`, your value in `error.cause`), or as `ambiguous` when thrown after the push request
383was handed over; nothing fails to compile and nothing throws, the answer just changes. Return them as values instead
384(above). Reading `error.cause` of a `what: 'callback'` Err works as a stopgap before the hand-over, but after it the
385code is `ambiguous` and the ref may have moved.
387Credentials: `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 `Location`s, 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 `Location`s 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.
389Outcomes 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.
391## Wire sequence
393| # | Request | Response | Why |
394|---|---|---|---|
395| 1 | v2 `ls-refs` with `ref-prefix` | one line | head oid |
396| 2 | v2 `fetch want <commit> filter tree:0 deepen 1 done` | 1-object pack | commit only (~300 B) |
397| 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) |
398| N+3 | v2 `fetch want <blob>` | 1-object pack, **streamed** | inflate → scan → SHA-1, never materialized |
399| N+4 | v0 `receive-pack` thin pack | `unpack ok` / `ng` | commit full + N tree `REF_DELTA`s + blob `REF_DELTA`; `old new ref` line is the CAS |
401With a warm tree cache (root tree oid unchanged) steps 3…N+2 vanish: 3 roundtrips + push.
403## Fewer round trips on repeat edits
405Two ideas from [gitgrep](https://github.com/ivarvong/gitgrep):
407- `cachingFetch(fetch, caches.default, { waitUntil })` as `fetchImpl`: 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 under `sha256(url, credential, body)`. The answer streams to the caller and, through a verifier, into `cache.put`; without `verifyBeforeStore` nothing on the cache path holds a whole answer (with it, a MISS holds up to three times `limits.maxPackBytes`, below). The verifier keeps one pkt-line frame of state and errors the body handed to `put` at the first violation or at the end: pkt-line framing complete to the final flush, no `ERR` packet, no sideband channel-3 message and, when there is a packfile section, a `PACK` v2/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 to `limits.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 has `crypto.DigestStream` (Workers) it is the native digest, not measured here. An acknowledgments-only fetch answer (a round that ends on its `NAK`/`ACK` lines, to a request without `done`) is refused and not stored, as `verifyFetchAnswer` refuses it ("answer: no packfile section"). The answer to another command a caller's own `shouldCache` admits (ls-refs) is checked for framing and `ERR` only, and is cacheable. A failed or cut answer still reaches the caller and is not stored, so one bad exchange is not replayed: `PackCache.put` takes 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 in `stats.verifyFailed` with the reason in `stats.verifyError` (`git.pack.cache.verify.failed` / `.verify.error` on the span). A delete that fails there, by rejecting or by throwing, is ignored and does not reject the promise handed to `waitUntil`. The store never paces the caller: the cache branch queues at most `CACHE_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.parsed` counts 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`, `protocol` or `remote_error`: a flipped pack byte, a cut or empty entry, a wrong pack trailer, a stored `ERR`) is deleted and asked for once more from the origin (`x-ply-cache: bust`, answered `x-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, unless `verifyBeforeStore: true`: that widens the rule to every wants-only fetch and stores an answer only after `verifyFetchAnswer` accepted the whole of it (every want present, every object hashed; `openBlob` has 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 times `limits.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's `shouldCache`), is not stored and is counted in `stats.verifyFailed` (nothing was put, so no key is deleted); `stats.verifyOk` counts only the answers handed to `put`, not every answer the streaming verifier passed. When the `put` is called differs: without the flag it is called inside the fetch on every MISS, before the fetch answers (a `put` that throws when called is that fetch's `'cache.put'` Err, and the answer is cancelled first); with it, only once `verifyFetchAnswer` accepted the answer, after the fetch answered, so a `put` that throws or rejects then is `stats.putFailed` (`putError` the `'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 most `maxBytes` of bodies and header text (default `LIMIT_MEMORY_CACHE_BYTES`, 64 MiB) in at most `maxEntries` entries (default `LIMIT_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.5` is 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.
408- `head`: the oid you believe the ref points at (your last `newCommit`). 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.hint` is `'used' | 'stale' | null`).
410Against github.com: 4 rtt / 549 ms cold → 3 rtt / 73 ms with both.
412`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.
414Also: `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.
416## Reading without a clone
418`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.
420The 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.
422### One object by id: `fetchObject`
424`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.
426### Recent history: `readLog`
428`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.
430## Pushing a whole tree (deploy from a directory, no git binary)
432`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.
434```js
435import { pushTree } from 'ply/tree'; // Workers-safe
436import { pushDir } from 'ply/tree-node'; // Node: walks a directory (node:fs)
438await pushTree(url, { ref: 'refs/heads/main', author, message: 'deploy', files: {
439 'index.html': '<h1>hi</h1>', // string or Uint8Array → 100644
440 'bin/build': { data: script, mode: '100755' },
441 'latest': { mode: '120000', data: 'v2/index.html' }, // symlink: the target is the blob
442 'vendor/lib': { mode: '160000', oid: submoduleCommit }, // gitlink: no data; the server need not have the commit
443} }, { auth, tracer, head: lastCommit });
444await pushDir(url, { dir: './dist', ref: 'refs/heads/main', author, message: 'deploy' }, { auth, tracer });
445```
447`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.
449`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`.
451`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).
453Repeat 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).
455`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).
457**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.
459## Push a pack you already have (`pushPack`)
461A 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:
463```js
464const r = await pushPack(transport, {
465 commands: [{ ref: 'refs/heads/main', oldOid: ZERO_OID, newOid: head }],
466 pack: stream, // header, entries, trailer; read once
467 length: packBytes, // optional: the pack alone, without the commands
468 atomic: true, // optional, checked against the advertisement (as are pushOptions)
469});
470```
472Memory 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`).
474A 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.
476## Custom exchanges on a transport (`frames`)
478Every 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:
480- **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;
481- **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: an `ERR` line (capabilities, ls-refs, fetch), band 3 (fetch; push, in the `ambiguous` message), 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 attribute `git.push.band2.tail` is escaped the same way. These still carry the server's text as received, so escape them before printing: the span attributes `git.push.remote.messages`, `git.push.ng.reason`, `git.fetch.sections` and the fetch progress text (`git.sideband.progress.tail`), `hookOutput`, the `lines` and `rejected` detail fields, the ng reason quoted in a `push_rejected`, `cas_conflict` or `push_partial` message, and the object-format name in an `unsupported` message. A credential the server echoes in an `ERR` line (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`, `sidebandStep` and `parseCapabilitiesV2` take 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;
482- **spans**: `frames` fills the span you pass with `git.service`, `git.request.bytes` (a `StreamBody`'s `length`), `http.request.method`, `url.full` (redacted), `http.response.status_code`, `git.response.bytes`, `git.response.first_byte_ms` and the rest of the HTTP attributes (the telemetry contract below);
483- the transport's **redirect policy**, **limits**, **timeouts** (first byte, idle) and `signal`;
484- **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).
486What 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):
488```js
489// custom-exchange: receive-pack
490import { createTransport, Tracer, KIND, ZERO_OID, TYPE, buildPack, hashObject, encodeTree, encodeCommit } from 'ply';
491import { frames } from 'ply/transport';
492import { pushBody, streamInit, streamStep, streamFinish, classifyReport } from 'ply/push';
494// what to send: a root commit holding one file
495const file = new TextEncoder().encode('hello\n');
496const tree = encodeTree([{ mode: '100644', name: 'hello.txt', oid: hashObject('blob', file) }]);
497if (!tree.ok) throw tree.error;
498const made = encodeCommit({ tree: hashObject('tree', tree.value), author: 'Me <me@example.com> 1700000000 +0000', message: 'hello\n' });
499if (!made.ok) throw made.error;
500const commit = hashObject('commit', made.value);
501const objects = [{ type: TYPE.BLOB, data: file }, { type: TYPE.TREE, data: tree.value }, { type: TYPE.COMMIT, data: made.value }];
503const spans = [];
504const t = createTransport(url, { ...opts, tracer: new Tracer({ onEnd: s => spans.push(s) }) });
505if (!t.ok) throw t.error;
506// the request: the commands as pkt-lines and a flush, then the pack, as one stream of known length
507const commands = [{ ref: 'refs/heads/main', oldOid: ZERO_OID, newOid: commit }];
508const prefix = pushBody({ commands, caps: ['report-status', 'side-band-64k', 'agent=me/1'] });
509if (!prefix.ok) throw prefix.error;
510const { pack } = await buildPack(objects);
511const stream = new ReadableStream({ start(c) { c.enqueue(prefix.value); c.enqueue(pack); c.close(); } });
512const body = { stream, length: prefix.value.length + pack.length };
513const span = t.value.tracer.start('custom receive-pack', { kind: KIND.CLIENT, scrub: t.value.scrub });
514let reply = streamInit(true); // side-band-64k: the report in band 1, progress in band 2
515try {
516 for await (const f of frames(t.value, 'git-receive-pack', body, span)) {
517 const stepped = streamStep(reply, f);
518 if (!stepped.ok) throw stepped.error;
519 reply = stepped.value;
520 }
521} catch (e) { span.error(e); throw e; } finally { span.end(); }
522const done = streamFinish(reply);
523if (done.tag !== 'report') throw new Error(`no report: ${done.why}`);
524const report = classifyReport(done.lines, commands); // { tag: 'statuses', refs: [{ ref, ok: true, reason: '' }] }
525if (report.tag !== 'statuses' || !report.refs.every(r => r.ok)) throw new Error(`refused: ${JSON.stringify(report)}`);
526```
528**`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.
530**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.
532## Push a whole local repository (history, no git binary)
534`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`](examples/push-repo.mjs).
536```js
537import { pushRepo } from 'ply/repo-node'; // Node: reads .git (node:fs)
539const r = await pushRepo('./repo', url, { refspecs: ['main', 'v1.0', '+wip:refs/heads/backup', ':stale'] }, { auth });
540if (r.ok && r.value.upToDate) console.log('Everything up-to-date'); // nothing was sent
541await pushRepo('./repo', url, { all: true, tags: true }, { auth }); // every branch and tag
542```
544Refspecs 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`.
546The 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).
548Memory: 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`.
550## Mirror one ref between remotes
552`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`):
554```js
555// sync-ref example
556import { syncRef } from 'ply';
558const r = await syncRef(srcUrl, dstUrl, { ref: 'refs/heads/main' }, {
559 src: { auth: { token: process.env['SRC_TOKEN'] } }, // read with one credential
560 dst: { auth: { token: process.env['DST_TOKEN'] } }, // write with another
561});
562if (!r.ok) throw r.error; // not_fast_forward: the source was rewritten (force: true follows it); cas_conflict: the mirror moved
563if (r.value.outcome === 'in_sync') console.log('in sync at', r.value.oid);
564else console.log(r.value.outcome, r.value.from, '->', r.value.to, `${r.value.objects} objects, ${r.value.pushBytes} B`);
565```
567The 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`.
569## One commit from a change list
571`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.
573`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.
575An 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'`.
577`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`.
579## Checking out a whole tree (no git binary, no clone)
581`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).
583```js
584import { checkoutTree } from 'ply/checkout'; // Workers-safe
585import { checkoutDir } from 'ply/checkout-node'; // Node: writes a directory (node:fs)
587const r = await checkoutTree(url, { ref: 'main', path: 'site' }, { auth, tracer });
588if (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 } });
589const done = await checkoutDir(url, { dir: './out', ref: 'v1.2.0' }, { auth, tracer }); // == git clone, minus .git
590```
592Every 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`.
594Measured 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.
596`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.
598## Hosts that refuse `filter tree:0` (Cloudflare Artifacts)
600Artifacts 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](https://developers.cloudflare.com/artifacts/platform/limits/) also caps a push at 50,000 objects and 1 MiB of ref updates, and a file at 32 MiB.
602## Branches and merging (git operations only)
604- `editFile(url, { ref: 'refs/heads/feature', base: 'refs/heads/main', … })` builds the commit on `base`'s head and *creates* `ref` (zero old-oid: the CAS means "must not exist yet").
605- `mergeBranch(url, { ref, from, author })` lands `from` into `ref`: merge-base via commit-only packs, then `up_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 is `merge_conflict` with 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. `.gitattributes` merge drivers apply when you say which tree supplies them — `attributes: 'ours'` (what `git merge` in a worktree reads), `'theirs'`, `'base'`, a ref or commit (`attr.tree`), or `null` (default: none, as git ≥ 2.46 does in a bare repository): `-merge`/`binary` conflict, `merge=union` keeps 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 is `merge_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). `conflicts` lists 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 at `limits.maxMergeWork` steps per merged file (2^32 in `DEFAULT_LIMITS`, 2^26 in `WORKER_LIMITS`), answering `too 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`/`diffScript` take `maxWork` (the same budget, absolute, for that call) and a `meter` (`{ steps }`) to change and read it. The count is kept inside the call, from zero: the `meter` is only written (its `steps` is 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 over `maxBytes`, `driver: 'binary'`) and never read, so one meter reused across files, or one that is not an object (an array is one and gets a `steps` property; a function is ignored), changes no result, and a meter whose write throws (a setter, a Proxy's `set` trap, a revoked Proxy) is dropped with the result unchanged; a `maxWork` that is not a non-negative finite number (`NaN`, `Infinity`, a negative, a string) reads as the default, and a `limits.maxMergeWork` that is not one is `bad_request` like any other limit. Neither function throws on any `meter` or `maxWork` value (an unknown `driver` still 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-line `a`/`b`/`c` files: 5,370,282 steps for the diff) and such a file reaches `too large to merge` sooner.
606- `createBranch(url, { ref, from })`, `deleteBranch(url, { ref, expected? })` and `createTag(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`/`target` is a ref name (resolved as `readCommit` resolves one; an annotated tag is peeled) or a 40-hex commit id the server must have. A ref that already exists is `cas_conflict` (`expected` the zero id, `actual` its tip), as a create is in `editFile`; a delete whose `expected` is not the tip is `cas_conflict` before anything is sent, and one that loses a race to another writer after ls-refs is `cas_conflict` with `actual` the ref read back (null only when it was deleted); an absent ref is `not_found`; what the server refuses (deleting the branch HEAD names) is its `push_rejected`. `verify: true` reads a created ref back. On a transport you already hold: `fastForward(t, { ref, from, to })` and `deleteRef(t, { ref, oid })`.
607- `rebaseBranch(url, { ref, onto, committer })` replays the branch's linear chain onto `onto`'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=drop` does and listed in `dropped`. One difference from `git rebase` stands: git leaves out a commit whose patch id equals a commit already in `onto` before it replays anything (its default, `--no-reapply-cherry-picks`); ply computes no patch ids and replays every commit, which is `git 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: true` makes one commit; its default message is the replayed messages joined by blank lines (what `git rebase -i` writes for pick, squash, …). `cherryPick` / `revertCommit` are 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 is `outcome: 'kept_empty'`. The default `empty: 'stop'` reports `outcome: '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's `Revert "<subject>"` message, and the committer stamp is the caller's.
608- One primitive underneath all of it — the three-way tree merge, with the line merge for files both sides changed — with different arguments:
610 | op | base | ours | theirs | commit |
611 |---|---|---|---|---|
612 | merge | merge-base tree | main | branch | parents `[main, branch]` |
613 | rebase (per commit) | commit's parent tree | new tip | commit | parent `[new tip]` |
614 | squash | merge-base tree | main | branch tip | parent `[main]` |
615 | cherry-pick | commit's parent tree (empty tree, if the commit is a root) | target | commit | parent `[target]` |
616 | revert | commit tree | target | commit's parent tree (empty tree, if the commit is a root) | parent `[target]` |
618- A pull request is a GitHub API object around such a branch; that call is outside this library.
620## SSH
622SSH transport removed 2026-10-31; history on branch archive/ssh.
624## Guards and policy
626- **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: true` opts in to editing the pointer itself.
627- **Signed commits**: pass `signer` (from `ed25519Signer({ privateKey, publicKeyRaw })` or `generateSigner()`) and the commit carries an SSH signature (PROTOCOL.sshsig, Ed25519 via WebCrypto — Workers and node). Verified by `git verify-commit` and `ssh-keygen -Y verify` in `test/sign.test.js`; satisfies "require signed commits" branch protection with the public key registered as a signing key. `signCommit(commitBytes, signer)` and `withGpgsig(commitBytes, signature)` sign any encoded commit, including one with no body section (`encodeCommit` with no `message`): the signed object without its `gpgsig` header is the input byte for byte. (Before, such a commit came back with a blank line added after the headers, so `git verify-commit` rejected its signature.)
628- We identify as `ply/0.2.0`, not as git.
630## Layers
632```
633operations edit · push tree · merge · rebase · cherry-pick · revert operation.js: root span, transport, outcome, verify rule
634commands lsRefs · packStream/fetchObject · fetchPack/negotiate · push · discover · receiveCaps free functions over a transport
635transport the contract (transport.js): t.frames(service, body, span, hints) · t.advertise(service, span)
636 implementation: http.js (one POST per command)
637protocol pure step functions: pktStep · v2Step · spStep · scanStep · streamStep · reportStep · threeWay · decideHead
638codecs pktline · inflate · sha1 · objects · pack (delta/build) · validate
639errors errors.js: every code, its retry policy; errors-doc.js: what each means
640```
642Each 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`.
644## Telemetry conventions (enforced by `test/pure.test.js` and `test/span-contract.test.js`)
646- 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.
647- Attribute keys: dotted lowercase under `git.` `http.` `url.` `server.` `mem.` `error.` `ply.` `exception.`.
648- Every trace root (operation roots and the spans that follow them, below) carries `<name>.outcome` (`ok`, `noop`, `fast_forward`, `cancelled`, …, or the error code).
649- On the HTTP transport (`createTransport`), every wire span carries `git.transport` and `server.address`. `git.request.bytes` is 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; on `git.receive-pack` it is then set again to the bytes actually sent), and absent when the GET ply makes before a POST fails first. `git.response.bytes` is 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 carries `git.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 no `git.response.bytes` of its own. The GET ply makes on a POST's own span (before the first POST under `followRedirects: '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) sets `git.response.bytes` there 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 to `POST` for the first POST under `followRedirects: 'initial'`, but a span re-sent after a stale redirect memo ends with `http.request.method` (`GET`, from the re-settling GET) beside the re-sent POST's status, `git.request.bytes` and `git.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.
651### Telemetry contract
653Span names, kinds, parent/child structure, links and attribute keys (with their value types) are public API. [`test/span-contract.json`](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.
655- **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.
656- **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 of `test/span-contract.json`.
658### In-process consumers: `onEnd`
660An 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
661process (a list kept for one request, spans mirrored onto a platform tracer) usually wants plain values instead, and
662would otherwise pay to build the OTLP form and then `flattenLine` it straight back. `new Tracer({ onEnd })` calls
663`onEnd(span)` with an `EndedSpan` as each span ends: exactly the `FlatSpan` that `flattenLine` reads back from the line
664the exporter would get (ids, name, kind, `durationMs`, status, attributes as plain values, credential-scrubbed; events;
665links), plus `startTimeUnixNano`, `endTimeUnixNano` and `otlp()`, which builds that OTLP span on first call (and
666returns the same object after). `onEnd` runs before the exporter. A tracer with `onEnd` and no exporter builds no OTLP
667at all unless `otlp()` is called; one with neither builds nothing. A subclass that overrides `export` still gets every
668span. `test/otel-ended.test.js` holds the EndedSpan equal to `flattenLine` of the exported line over random attribute
669records of every value kind.
671```js
672const spans = [];
673const tracer = new Tracer({ onEnd: s => spans.push(s) }); // s.attrs['git.response.bytes'] is a number; no OTLP built
674```
676### Span lifetimes
678Some 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:
680- Each is the root of a trace of its own, with an OTLP link `ply.link=follows_from` to the span it follows, and that span carries `ply.link=followed_by` back if it was still open when the follower started (`git.read` → `git.read.blob`; `git.checkout.blobs` → each streamed `git.read.blob`). Links per span are capped at `maxEvents`, the rest counted in `droppedLinksCount`.
681- 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 unread `fetch` body.
682- Every other span ends within its parent: no child outlives its parent (asserted over every trace in the contract test).
684Why 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.
686## Errors
688An 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).
690Every 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`).
692A 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.
694A `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.
696`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").
698## Shape
700`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).
702Two 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).
704`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.
706## Limits
708Every 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.
710The 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.
712Time is bounded per exchange by four timers (#255, #273), all fields of `limits`; 0 turns one off:
714- `firstByteTimeoutMs` (60 s): from the request to the response headers. For a streamed request body (`pushPack`, a `StreamBody`), 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 as `firstByteTimeoutMs`. 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).
715- `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: `idleTimeoutMs` and `firstByteTimeoutMs` fire 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's `signal` is 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; `heldTimeoutMs` bounds that instead.
716- `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 code `timeout` and `limit: '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: `idleTimeoutMs` or `heldTimeoutMs`, whichever is smaller (`heldTimeoutMs` when 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's `signal` or `requestTimeoutMs`.
717- `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.
719Each 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.
721**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`.
723A 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).
725`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.
727`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.
729```js
730import { pushTree, WORKER_LIMITS, withLimits } from 'ply';
731const r = await pushTree(url, spec, { limits: withLimits({ ...WORKER_LIMITS, maxPackBytes: 62 * 1024 * 1024 }) });
732```
734## Memory
736Peak 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).
738Every 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.
740The 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.
742What 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`.
744A 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`.
746The 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 `chunk`s 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.
748<!-- scanpack-loop: test/readme-scanpack.test.js runs this block -->
749```js
750import { scanPack } from 'ply';
752// pack: a ReadableStream or AsyncIterable of a pack's bytes. An invalid pack errors the stream (a PlyError).
753const sizes = []; // each object's inflated size, in pack order
754let size = 0;
755for await (const piece of scanPack(pack)) {
756 switch (piece.kind) {
757 case 'header': break; // piece.version, piece.count
758 case 'object': size = 0; break; // piece.type, piece.offset, piece.base
759 case 'chunk': size += piece.bytes.length; break; // the object's inflated bytes, in order
760 case 'object-end': sizes.push(size); break; // piece.compressed, piece.stats
761 case 'trailer': break; // piece.trailer: the pack's checksum
762 }
764```
766A 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.
768`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.
770`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.
772`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`).
774**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.
776**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.
778`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.
780## Things the oracle taught us (would have been wrong otherwise)
782- 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), `--thin` changes which objects are excluded, shallow boundaries are grafts rather than negative refs, and `have` processing is order-dependent.
784- `filter tree:N` **includes blobs** at depth < N. It is not a subset of `blob:none`; `combine:blob:none+tree:N` is. (`test/oracle.test.js`)
785- git's `patch_delta` rejects deltas shorter than `DELTA_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)
786- `receive-pack` unpacks the pack before checking `old`, so a lost CAS race leaves dangling objects server-side. The conflict is still atomic for the ref. (`test/concurrency.test.js`)
787- Identical replacement would have produced an empty commit. Now a `noop`. (fuzz)
789## Test loop
791`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.
793```
794npm run lint # oxlint; no-magic-numbers on the wire decoders (0 and 1 are the only allowed literals)
795npm run test:props # ~5 s: pure step functions — chunking invariance, codec roundtrips, node:zlib/crypto oracles
796npm run test:mutate # Stryker across src/. Full run locally and on main; a PR mutates only the src lines it changes
797npm run fuzz:below-hash -- --n 20 --seed 1 # mutate decompressed objects, re-hash, fetch, compare with git fsck --strict
798npm 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
799npm run fuzz -- --n 200 # ~30 s: steered generative cases against git http-backend
800npm 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
801npm run test:protocol # ~4 min: exhaustive fetch matrix (14,256 cells) vs pack-objects + captured upload-pack invocation
802npm run fuzz:protocol -- --n 500 # random wants/haves/deepen/filter/thin/negotiate/shallow on generated DAGs
803npm run trace -- fuzz-out/trace.jsonl git.receive-pack "git.push.ok==false"
804```
806An 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.
808### The fuzzer
810`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`).
812Each 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.
814### Steering
816After 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.
818## Layout
820```
821src/sha1.js streaming SHA-1 (subtle.digest can't stream)
822src/inflate.js zlib/deflate inflate that returns bytes consumed (packs have no length prefix)
823src/pktline.js pkt-line encode; decoder as pure (state, chunk) → {state, frames}
824src/pack.js pack parse/resolve, delta apply/generate, thin pack build
825src/objects.js blob/tree/commit codecs, tree sort (dir-as-slash)
826src/client.js v2 ls-refs/fetch (streamed sideband), v0 receive-pack; request bodies & response state machine are pure
827src/edit.js the pipeline; single-object pack stream + find/replace scanner as pure step functions
828src/otel.js OTLP/JSON tracer, one ExportTraceServiceRequest per line
829src/bytes.js alloc accounting (Mem), concat, indexOf
830```
832Prod lib is ~1100 lines. Tests are the rest.
Diagnostics4 git calls · 10 ms
CallStatusSizeTime010 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B · hit4 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=4
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020038 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=38434
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=38434
git.pkt.payload.max=38339
git.sideband.band1.bytes=38338
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=63
git.pack.bytes=38338
git.pack.ofs_delta=0
git.pack.ref_delta=8
git.pack.chain.max=8
git.pack.trailer=0bc36ab7adf82d3109177f11f1ea93f1ce071f77
git.pack.full=55
Open pack map
fetch20064 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=65471
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.wants=8f6bd70370f6adac508e716ecfe5e29ceb3f0034
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=65471
git.pkt.payload.max=65450
git.sideband.band1.bytes=65449
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply.git
Ref
refs/heads/main
Commit
19912563f540228593df0c489082e5e2508e21e4
cf-ray
a5e2cb874b8d7929
Request
bd7feb15…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format