main
1// A path walk's commit and the first levels of its tree in one fetch (#218). readFile and listTree read the commit, then
2// one tree per path level, each a round trip that waits on the one before it. A server that takes
3// `filter combine:blob:none+tree:K` answers a commit want (deepen 1) with the commit and every tree at depth < K, no blobs:
4// one round trip where tree:0 takes K + 1. K is the levels the walk reads, capped at PATH_TREE_LEVELS: the levels below the
5// root's children are the whole repository's fan-out (gitlab-org/gitlab: 48 trees / 36 KB at K = 2, 566 / 526 KB at
6// K = 3, measured 2026-11-06), slower than the round trips they would save, so they are read one per level as before.
7//
8// The pack is checked as a blob:none fallback pack is (fetchWide, fetchPackTree0): every object keyed by its computed hash
9// (resolvePack), every commit and tree held to the caller's limits (checkWide, the commit the wanted object; an extra over
10// a limit is dropped, #46 / SAFETY I30; a malformed object fails the fetch), the trees harvested into the transport's
11// store, where the walk's tree:0 reads find them (objectAt). A tree that did not come is fetched by its level as before.
12//
13// Whether the server takes it is learned from its answer, never from its name (transport.ts pathTreesOf), per quirks
14// record. It is asked only of a server known to take tree:0 (an earlier request on the record settled it, transport.ts
15// tree0Taken): a host that refuses tree:0 (Artifacts: blob:none, every tree with the commit already) or takes no filter
16// (stock git: everything) never sees it, and a first contact is the tree:0 path alone, so #136's one refusal per remote
17// stands. Tree:0 taken, this one not known yet: this fetch and the tree:0 commit fetch run concurrently, so a refusal costs
18// a request and no round trip. Taken: this fetch alone. Refused (GitHub: `filter 'combine' not supported`, `tree filter
19// allows max depth 0`, git's own words under uploadpackfilter.combine.allow=false / tree.maxDepth=0): the tree:0 path
20// alone. A failure of this fetch for any other reason is not used: the tree:0 path answers, and its answer and its errors
21// are the walk's, as before.
22import type { PlyError } from './errors.js';
23import type { Transport } from './transport.js';
24import type { Oid } from './oid.js';
25import type { Result } from './result.js';
26import type { FetchedCommit } from './commit.js';
27import { commitWithTrees, isEmptyResponse, isFilterRejection } from './fetch.js';
28import { commitById } from './commit.js';
29import { parseCommit } from './objects.js';
30import { learnPathTrees, pathTreesOf, tree0Taken } from './transport.js';
31import { map } from './result.js';
32import { thrownCodeIs, thrownText } from './boundary.js';
34// The deepest tree level fetched with the commit: the root (depth 0) and its children (depth 1).
35export const PATH_TREE_LEVELS = 2;
36// git's refusal of a depth past uploadpackfilter.tree.maxDepth (list-objects-filter-options.c), as GitHub sends it.
37const DEPTH_REFUSED = 'tree filter allows max depth';
38// The server said it does not take this filter: a refusal the filter phrases name (an HTTP 400 like Artifacts', or git's
39// `filter '…' not supported`), git's depth refusal, or the empty answer of an upload-pack that takes no filter at all.
40export const isPathTreesRefusal = (e: unknown): boolean => isFilterRejection(e) || isEmptyResponse(e) || (thrownCodeIs(e, 'remote_error') && thrownText(e).includes(DEPTH_REFUSED));
42// The filter for a walk that reads `levels` tree levels (0: none, the commit alone).
43export const pathTreesFilter = (levels: number): string => `combine:blob:none+tree:${Math.min(levels, PATH_TREE_LEVELS)}`;
45// Effect: the commit and its trees at depth < K, harvested (fetch.ts commitWithTrees: a want that is not a commit, or a
46// pack without it, is that fetch's error). Ok(commit), or the fetch's error: the caller decides.
47const deepCommit = async (t: Transport, oid: Oid, levels: number): Promise<Result<FetchedCommit, PlyError>> => {
48 const got = await commitWithTrees(t, oid, pathTreesFilter(levels));
49 if (!got.ok) return got;
50 const { data } = got.value;
51 return map(parseCommit(data, t.limits), commit => ({ oid, data, commit }));
52};
54// Effect: the commit a walk of `levels` tree levels starts from, with as many of those levels as one fetch brings
55// harvested. The answer (and every error) is commitById's whenever the deep fetch is not used.
56export async function commitForWalk(t: Transport, oid: Oid, levels: number): Promise<Result<FetchedCommit, PlyError>> {
57 const known = pathTreesOf(t.quirks);
58 if (levels <= 0 || !tree0Taken(t.quirks) || known === 'refused') return commitById(t, oid);
59 if (known === 'taken') {
60 const deep = await deepCommit(t, oid, levels);
61 if (deep.ok) return deep;
62 if (isPathTreesRefusal(deep.error)) learnPathTrees(t.quirks, 'refused');
63 return commitById(t, oid);
64 }
65 const [deep, narrow] = await Promise.all([deepCommit(t, oid, levels), commitById(t, oid)]);
66 if (deep.ok) { learnPathTrees(t.quirks, 'taken'); return deep; }
67 if (isPathTreesRefusal(deep.error)) learnPathTrees(t.quirks, 'refused');
68 return narrow;
69}
Diagnostics4 git calls · 30 ms
CallStatusSizeTime030 ms
discover200152 B4 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 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 · hit3 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=3 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=24 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=55Open pack map
fetch2002.1 KiB · hit24 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=2137 git.response.cache=HIT git.response.duration_ms=24 git.fetch.wants=ccc6861904af9184959451a9ede8aa3575a56d4c 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=2137 git.pkt.payload.max=2116 git.sideband.band1.bytes=2115 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
- a5e2732bf973d806
- Request
- 79bb0ec9…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format