Artifactspublic-v0

ply

main
ply4 git calls229 ms62 KiB2 cachedprotocol v2
866 lines76 KiBRaw

SPACE.md — the decision spaces

A living document. Each section takes one decision ply makes, defines every axis the decision depends on as a tagged union of value classes justified from git's source, takes the product, and gives the expected outcome of every cell. The code is the source of truth: the axes, the product, the renderers and the expected outcome live in test/space/<decision>.space.js, the enumerator runs every cell through ply's real code path, and the generated part of each section is checked against the code by the test, so the two cannot drift. Fuzzing samples a space; this enumerates it. Add a decision point as a new section (and a new test/space/*.space.js).

Push outcome

Decision. After push() has sent the commands and the pack, what may it tell the caller? One of:

outcomemeaningcode (retry)
landedevery commanded ref was updated— (resolves)
rejectedno ref was updated; the reasons are the server'scas_conflict (fresh) when every refusal is a lost compare-and-swap, else push_rejected (no)
partiala non-atomic multi-ref push: the refs in landed were updated, those in rejected were notpush_partial (no)
ambiguousthe refs may or may not have moved: read them back firstambiguous (read)
preSendply refused before sending a byte; definite: nothing changedbad_request / limit_exceeded (no)

Principle. Once any request byte may have reached the server, a definite answer (landed, rejected, partial) needs positive evidence in exactly the shape git's receive-pack writes; every other post-send state is ambiguous. Before the request is sent, ply's own refusals are definite. The code is shaped the same way (src/push.ts): the wire is read into a tagged union of stream shapes (streamStep: report | broken), the report by a step machine (reportStep: unpack → refs | malformed, the one report parser) into a tagged union of report shapes (classifyReport: statuses | unpackFailed | malformed), decideOutcome is an exhaustive match over those tags whose only fallthrough is ambiguous (landed | rejected with a code and each refused ref's reason class | partial | ambiguous), and outcomeResult turns the outcome into the Result a caller matches on. Every step is an allowlist.

git's shape, from the source (git v2.50.0):

  • builtin/receive-pack.c report() writes unpack <status> (ok when unpack_status is NULL), then for each command in request order ok <ref> or ng <ref> <error_string>, then a flush; report_v2() writes the same and adds option refname|old-oid|new-oid|forced-update lines after an ok only for a command a proc-receive hook reported (cmd->report), repeating ok <ref> for each further report of the same command.
  • unpack() returns one of eight fixed strings (parse_pack_header: "eof before pack header was fully read", "protocol error (pack signature mismatch detected)", "protocol error (pack version unsupported)", "unknown error in parse_pack_header"; "unable to create temporary object directory", "unpack-objects abnormal exit", "index-pack fork failed", "index-pack abnormal exit"). execute_commands() then marks every command unpacker error and returns; nothing else sets that string. cmd_receive_pack() skips unpack entirely when delete_only(), so a delete-only push always reports unpack ok.
  • execute_commands_atomic(): a failure inside the transaction marks every other command atomic push failure (or atomic transaction failed / transaction failed to start); commands already refused before the transaction (reject_updates_to_hidden, connectivity, check_aliased_updates) are skipped and the rest still commit. So an atomic push can produce a git-shaped split (observed below: a hidden ref).
  • With side-band (use_sideband), the report buffer goes out as band-1 packets (send_sideband, chunked at LARGE_PACKET_MAX), hook and unpack stderr as band 2 (copy_to_sideband, also post-receive after the report), empty band-1 packets 0005\1 as keepalives while hooks run (copy_to_sideband; use_keepalive is KEEPALIVE_ALWAYS from execute_commands on, so keepalives also follow the report during post-receive: observed), and a final outer flush (cmd_receive_pack: if (use_sideband) packet_flush(1)). Without side-band the report's flush is the last byte and hook output goes to stderr, not the wire. receive-pack never writes band 3 or ERR.
  • send-pack.c receive_unpack_status() / receive_status() and sideband.c demultiplex_sideband(): git's own client fails the push on a missing unpack line, an invalid status word, EOF before the flush ("unexpected disconnect"), band 3 ("remote error"), or an ERR packet (PACKET_READ_DIE_ON_ERR_PACKET). It tolerates (warns on) status lines for unknown refs and accepts repeated statuses; ply does not: those are not shapes receive-pack writes.

Equivalences (not axes, with the reason). Create (zero old oid) — report() never reads old_oid; a create differs from an update only in the reason text of an ng, which is the ng payload. A delete beside an update — delete_only() is false, so it is the withPack class. Push options — they change only the request (read_push_options); check_cert_push_options can refuse them only for a signed push, which ply never sends; an invalid option is a refused event. The order of status lines — receive-pack writes them in request order; ply matches each line to its ref and does not require the order (a reordering takes more than one byte to make, and every ref still needs exactly one exact line). The text of an ng reason — any printable ASCII is accepted (hooks, hosts and proc-receive choose it); it decides only cas_conflict versus push_rejected (rejectionCode, over the refused refs' classes), never landed versus not.

Judgment calls (where git's behaviour is clear but the outcome is a choice):

  1. Atomic split. An atomic push answered with some ok and some ng is ambiguous, even though git can produce it (a hidden ref is refused before the transaction and the other refs commit: observed, hidden ref, atomic). The caller asked for all-or-nothing; ply does not turn that into a partial success, and the read-back shows what landed.
  2. Option lines. An ok followed by option lines (proc-receive, report-status-v2) means the server updated something other than the commanded ref and oid (refname, new-oid); ply does not model proc-receive, so it is ambiguous. Under v1 they are not git's at all.
  3. Unknown unpack failure text. A non-ok unpack status that is not one of git's eight strings is ambiguous, even with every ref ng unpacker error: a server that is not git may word it differently, and the cost is one read. One exception, on positive evidence (#246): every commanded ref refused with the unpack status itself as its reason (unpack <s>, then ng <ref> <s> for each ref) is push_rejected. Cloudflare Artifacts writes exactly that for a pack it cannot unpack (observed 2026-11-10 on prod, plain and side-band, one and two refs, atomic or not: "invalid pack entry type 0", "invalid zlib member", "pack stream incomplete at finish", "invalid pack signature"). It is never one byte from a definite cell of another outcome: the status must equal every ref's reason and not be ok (the boundary enumeration, unchanged). No ref lines, a ref that does not echo the status, an ok beside it, or a delete-only push stay ambiguous. Before this, such a report was ambiguous and a single-ref update was read back: an invalid pack whose ref had not moved came back cas_conflict, and a caller retried a pack that cannot land.
  4. Anything after the final flush (a second report, a transport error) is ambiguous, although the report before it was complete.
  5. A connection failure before any response byte is ambiguous even when the request was cut before the pack (the server then changes nothing: observed). ply cannot tell how much of the body the server consumed.
  6. A delete-only push answered with an unpack failure is ambiguous: receive-pack never unpacks for it.

Found while observing. A delete whose old oid names an object the server does not have is applied regardless: update() warns "allowing deletion of corrupt ref", drops the old oid, deletes, and reports ok (observed: delete with an unknown old oid). The report is truthful (landed); the compare-and-swap is not. SAFETY.md I22 is narrowed accordingly.

Where main (a7a724e) disagreed with the table (the enumerator run with PUSH_SPACE_SRC=<git archive a7a724e src>): 412,008 of 4,331,598 cells.

cellstable → maincause
276,312ambiguous → limit_exceeded (retry: no)every flood cell: a report-line limit hit after the send kept its pre-send code
19,456 + 1,152 + 192ambiguous → rejected / cas_conflict / landedplain stream with no final flush: main never required the report's flush
14,592 + 864 + 144ambiguous → rejected / cas_conflict / landedside-band report without its own flush inside band 1
19,456 + 1,152 + 192ambiguous → rejected / cas_conflict / landeda second flush after the final flush
29,184 + 1,728 + 288ambiguous → rejected / cas_conflict / landedband 1 carrying a partial pkt or a second flush after the report's flush
14,592 + 864 + 144ambiguous → rejected / cas_conflict / landedan ERR packet before the report (main skipped the line), with any delivery
12,880ambiguous → push_rejectedunpack near-miss (ok*): issue #33, the ref had moved
12,712ambiguous → push_rejecteda git unpack failure beside ref lines that are not all unpacker error (incl. ok), or for a delete-only push
2,688 + 280 + 168ambiguous → rejected / cas_conflict / landedoption lines after ok (v1, or v2 proc-receive)
2,128ambiguous → push_rejectedng <ref> unpacker error beside unpack ok, or beside other statuses
560 + 280partial → push_rejected / cas_conflictnon-atomic mixed ok/ng: main said "rejected" while some refs had landed

Boundary enumeration on main: 2,520 single-bit flips turn a landed cell into push_rejected (e.g. unpack ok → unpack nk); on the new code: none.

Enumeration. test/space/push-outcome.test.js runs every cell through push() over a fake transport that frames the bytes as http.js does (no network, no randomness) and asserts the table's outcome; it fails on a cell without an expected outcome or with a different one, and prints cells explored / total. test/space/push-outcome-boundary.js (run as four slice files, push-outcome-boundary.<0-3>.test.js, base j in slice j % 4, partition checked by push-outcome-boundary.plan.test.js) takes the canonical bytes of every definite cell and enumerates every single-bit flip, single-byte deletion, single-byte insertion from {00 01 02 0a 20 30 6f ff} and truncation; each mutant must be the cell's own outcome or ambiguous (a cas_conflict may soften to push_rejected, never the reverse). Measured 2026-10-30 (a laptop, 4 workers, other test jobs running alongside): 4,331,598 cells in 32.6 s (the test file, with 65 real-git scenarios, 54 s); 2,772 distinct definite cells, 7,419,600 mutants in 43.3 s, 0 violations. Since #251 (the host-echoed unpack failure, #246) the space is 4,592 distinct definite cells and 12,981,904 mutants; measured 2026-11-10 on a 4-core box (taskset 0-3, 4 workers per slice): each slice alone 44-49 s, all four slices at once (vitest's 3 forks, then the fourth) 148-149 s per slice, 0 violations (#263). PUSH_SPACE=quick (the mutation gate) explores the 19,782 cells with at most two deviations from git's canonical answer (7 s on one worker).

Axes (tagged unions)

event — what else happens around the exchange (14 variants)

  • clean — nothing else
  • progress — band 2 before the report (unpack/hook stderr via copy_to_sideband) and after it (post-receive)
  • keepalive — an empty band-1 packet "0005\1" before and after the report: copy_to_sideband sends it while hooks run (use_keepalive is KEEPALIVE_ALWAYS from execute_commands on, so post-receive too)
  • band3Before — band 3 before the report: demultiplex_sideband reports "remote error"; receive-pack itself never writes band 3
  • band3After — band 3 after the report, before the outer flush
  • errPkt — an "ERR " pkt before the report: packet_read dies (PACKET_READ_DIE_ON_ERR_PACKET in send_pack)
  • dropBeforePack — the connection fails after the commands, before the pack: the server unpacks nothing ("eof before pack header")
  • dropMidPack — the connection fails inside the pack: index-pack/unpack-objects fails, nothing is updated
  • dropAfterPack — the connection fails after the pack, before any response byte: the server may have updated the refs
  • refused (what="ref") — ply refuses before sending: validateRef refuses the ref name
  • refused (what="oid") — ply refuses before sending: an old/new oid that is not 40-hex
  • refused (what="maxRefs") — ply refuses before sending: more commands than limits.maxRefs
  • refused (what="packBytes") — ply refuses before sending: the built pack exceeds limits.maxPackBytes
  • refused (what="pushOption") — ply refuses before sending: a push option containing LF

framing — how the report is carried (2 variants)

  • plain — no side-band: report() write_or_die(1, …); hook output goes to stderr, not the wire
  • sideband — side-band-64k: report pkts + flush inside one band-1 packet (send_sideband), then an outer flush (cmd_receive_pack)

delivery — what reaches the client of the framed response (13 variants)

  • complete — every byte, then end of stream
  • band1Split — one band-1 packet per inner pkt: send_sideband() chunks at LARGE_PACKET_MAX; the client reassembles band 1 as a stream
  • noFinalFlush — the stream ends before the final flush: git dies (packet_read: "the remote end hung up") / demultiplex_sideband "unexpected disconnect"
  • noReportFlush — the report's own flush is missing inside band 1, the outer flush present
  • cutAfterUnpack — the stream ends cleanly after the unpack line (a cut at a pkt boundary)
  • cutMidPkt — the stream ends inside the last data pkt
  • trailingPkt — a second copy of the report after the final flush
  • throwAfter — every byte, then the transport fails (connection reset after the flush)
  • flood — 16 extra report lines: exceeds the client's report-line cap
  • trailingFlush — a second flush after the final flush
  • band1Trailing (extra="partial") — band 1 carries two more bytes after the report's flush (a pkt cut inside band 1)
  • band1Trailing (extra="flush") — band 1 carries a second report flush
  • wrongBand (band=5) — the report on band 5: one bit from band 1 (demultiplex_sideband: "bad band")

refs — number of commanded refs (3 variants)

  • one — single-ref push (the edit pipeline)
  • two — smallest multi-ref push: first and last ref differ
  • three — a ref with neighbours on both sides (an interior position)

commands — what the commands ask for; decides whether a pack is sent (2 variants)

  • withPack — some new oid is non-zero: cmd_receive_pack runs unpack_with_sideband()
  • deleteOnly — every new oid is zero: delete_only() skips unpack, so the status is always "unpack ok"

atomic — the atomic capability (2 variants)

  • off — execute_commands_non_atomic(): one transaction per ref
  • on — execute_commands_atomic(): one transaction; a failure inside it marks every other command "atomic push failure"

format — report-status v1 or v2, and option lines (4 variants)

  • v1 — report(): unpack line, one ok/ng line per command, flush
  • v2 — report_v2() without proc-receive: byte-identical to report()
  • v2Options — report_v2(): "option forced-update" after each ok, written only for proc-receive reports
  • v1Options — option lines when report-status-v2 was not negotiated: report() never writes them

unpack — the unpack line (7 variants)

  • ok — report(): "unpack ok" when unpack_status is NULL
  • gitError (status="unpack-objects abnormal exit") — unpack(): one of git's fixed failure strings (observed with a corrupted pack)
  • hostError (status="invalid pack entry type 0") — a host's own unpack failure text (Cloudflare Artifacts, observed with a pack entry of type 0, #246): definite only when every ref echoes it
  • absent — no unpack line: send-pack.c receive_unpack_status fails
  • unreadable — status bytes 0xff 0xfe: not text
  • nearMiss (status="ok*") — one flip from "ok" (issue #33): neither "ok" nor a git failure string
  • duplicated — two "unpack ok" lines: receive_unpack_status reads one; the second is an invalid ref status

status — every commanded ref's status (a mixed report overrides one ref, see spread) (11 variants)

  • ok — report(): "ok <ref>" when cmd->error_string is NULL
  • ngCas (reason="failed to update ref") — execute_commands_non_atomic(): ref_transaction_commit failed (stale old oid; observed from git 2.50)
  • ngHook (reason="hook declined") — update(): the update hook refused (observed)
  • ngAtomic (reason="atomic push failure") — execute_commands_atomic(): the innocent members of a failed atomic push (observed)
  • ngUnpacker (reason="unpacker error") — execute_commands(): every command, and only when unpack failed
  • ngEcho (reason="invalid pack entry type 0") — a host (Cloudflare Artifacts) refuses every ref with its unpack status as the reason (observed, #246); after "unpack ok" it is an ordinary refusal
  • missing — no status line for a commanded ref: report() writes one per command, so never git
  • duplicate — the ref's "ok" line twice: report() writes one per command; report_v2 repeats "ok" only with option lines (proc-receive)
  • unexpected — the ref's line names refs/heads/zz, a ref not commanded (send-pack.c receive_status: "unknown ref")
  • unreadable — the status word is not text (0xff 0xfe): send-pack.c receive_status "invalid ref status"
  • nearMiss — "ng <ref>" with no reason: report() always writes a reason; send-pack.c would read it as "failed"

spread — statuses across refs: uniform, or one ref (at index at) differs (34 variants)

  • uniform — every ref has status
  • mixed — at ∈ {0, 1, 2} × odd ∈ the 11 status tags: 33 variants (the odd ref's status overrides status for ref at)

Product

Raw product: 14 × 2 × 13 × 3 × 2 × 2 × 4 × 7 × 11 × 34 = 45,741,696 (event × framing × delivery × refs × commands × atomic × format × unpack × status × spread).

removedwhyraw cells
impossibleplain framing has no band 1, 2 or 3 (use_sideband=0: hook output goes to stderr)7,791,168
impossiblea delete-only push sends no pack, so it cannot be cut inside or after one, nor refused for its size188,496
impossibleone ref cannot be mixed3,821,664
impossiblethe odd ref index is beyond the commanded refs1,273,888
impossiblea mixed report whose odd status equals the common status is the uniform cell579,040
collapsedno response is read (refused before sending, or the connection failed first): the response axes are irrelevant (framing, delivery, format, unpack, status, spread keep their first variant)25,949,538

Cells: 6,137,902. Expected outcomes: ambiguous 6,128,160, rejected(push_rejected) 6,944, rejected(cas_conflict) 1,456, partial 1,120, landed 168, preSend(bad_request) 36, preSend(limit_exceeded) 18.

Observed from git (63 cells; the other 6,137,839 are derived)

  • clean/plain/complete/one/withPack/off/v1/ok/ok/uniform — all ok one/plain/v1/atomic off
  • clean/plain/complete/one/withPack/on/v1/ok/ok/uniform — all ok one/plain/v1/atomic on
  • clean/plain/complete/one/withPack/off/v2/ok/ok/uniform — all ok one/plain/v2/atomic off
  • clean/plain/complete/one/withPack/on/v2/ok/ok/uniform — all ok one/plain/v2/atomic on
  • clean/sideband/complete/one/withPack/off/v1/ok/ok/uniform — all ok one/sideband/v1/atomic off
  • clean/sideband/complete/one/withPack/on/v1/ok/ok/uniform — all ok one/sideband/v1/atomic on
  • clean/sideband/complete/one/withPack/off/v2/ok/ok/uniform — all ok one/sideband/v2/atomic off
  • clean/sideband/complete/one/withPack/on/v2/ok/ok/uniform — all ok one/sideband/v2/atomic on
  • clean/plain/complete/two/withPack/off/v1/ok/ok/uniform — all ok two/plain/v1/atomic off
  • clean/plain/complete/two/withPack/on/v1/ok/ok/uniform — all ok two/plain/v1/atomic on
  • clean/plain/complete/two/withPack/off/v2/ok/ok/uniform — all ok two/plain/v2/atomic off
  • clean/plain/complete/two/withPack/on/v2/ok/ok/uniform — all ok two/plain/v2/atomic on
  • clean/sideband/complete/two/withPack/off/v1/ok/ok/uniform — all ok two/sideband/v1/atomic off
  • clean/sideband/complete/two/withPack/on/v1/ok/ok/uniform — all ok two/sideband/v1/atomic on
  • clean/sideband/complete/two/withPack/off/v2/ok/ok/uniform — all ok two/sideband/v2/atomic off
  • clean/sideband/complete/two/withPack/on/v2/ok/ok/uniform — all ok two/sideband/v2/atomic on
  • clean/plain/complete/three/withPack/off/v1/ok/ok/uniform — all ok three/plain/v1/atomic off
  • clean/plain/complete/three/withPack/on/v1/ok/ok/uniform — all ok three/plain/v1/atomic on
  • clean/plain/complete/three/withPack/off/v2/ok/ok/uniform — all ok three/plain/v2/atomic off
  • clean/plain/complete/three/withPack/on/v2/ok/ok/uniform — all ok three/plain/v2/atomic on
  • clean/sideband/complete/three/withPack/off/v1/ok/ok/uniform — all ok three/sideband/v1/atomic off
  • clean/sideband/complete/three/withPack/on/v1/ok/ok/uniform — all ok three/sideband/v1/atomic on
  • clean/sideband/complete/three/withPack/off/v2/ok/ok/uniform — all ok three/sideband/v2/atomic off
  • clean/sideband/complete/three/withPack/on/v2/ok/ok/uniform — all ok three/sideband/v2/atomic on
  • clean/plain/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 two/plain/v1; hidden ref, non-atomic plain
  • clean/plain/complete/two/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic two/plain/v1
  • clean/plain/complete/two/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 two/plain/v2
  • clean/plain/complete/two/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic two/plain/v2
  • progress/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 two/sideband/v1
  • progress/sideband/complete/two/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic two/sideband/v1
  • progress/sideband/complete/two/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 two/sideband/v2
  • progress/sideband/complete/two/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic two/sideband/v2
  • clean/plain/complete/three/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 three/plain/v1
  • clean/plain/complete/three/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic three/plain/v1
  • clean/plain/complete/three/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 three/plain/v2
  • clean/plain/complete/three/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic three/plain/v2
  • progress/sideband/complete/three/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 three/sideband/v1
  • progress/sideband/complete/three/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic three/sideband/v1
  • progress/sideband/complete/three/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook) — update hook refuses r1 three/sideband/v2
  • progress/sideband/complete/three/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook) — update hook refuses r1, atomic three/sideband/v2
  • clean/plain/complete/two/withPack/off/v1/ok/ngHook(reason=hook declined)/uniform — pre-receive refuses plain
  • clean/plain/complete/one/withPack/off/v1/ok/ngCas(reason=failed to update ref)/uniform — stale old oid plain
  • clean/plain/complete/two/withPack/off/v1/ok/ok/mixed(at=0,odd=ngCas) — stale old oid, two refs plain
  • clean/plain/complete/one/withPack/off/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform — corrupted pack plain
  • clean/plain/complete/two/withPack/on/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform — corrupted pack, two refs, atomic plain
  • clean/plain/complete/one/deleteOnly/off/v1/ok/ok/uniform — delete plain; delete with an unknown old oid plain
  • clean/plain/complete/two/deleteOnly/off/v1/ok/ok/mixed(at=1,odd=ngCas) — delete two, one stale plain
  • clean/plain/complete/two/withPack/on/v1/ok/ok/mixed(at=1,odd=ngHook) — hidden ref, atomic plain
  • progress/sideband/complete/two/withPack/off/v1/ok/ngHook(reason=hook declined)/uniform — pre-receive refuses sideband
  • progress/sideband/complete/one/withPack/off/v1/ok/ngCas(reason=failed to update ref)/uniform — stale old oid sideband
  • progress/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=0,odd=ngCas) — stale old oid, two refs sideband
  • progress/sideband/complete/one/withPack/off/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform — corrupted pack sideband
  • progress/sideband/complete/two/withPack/on/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform — corrupted pack, two refs, atomic sideband
  • clean/sideband/complete/one/deleteOnly/off/v1/ok/ok/uniform — delete sideband
  • progress/sideband/complete/two/deleteOnly/off/v1/ok/ok/mixed(at=1,odd=ngCas) — delete two, one stale sideband
  • progress/sideband/complete/one/deleteOnly/off/v1/ok/ok/uniform — delete with an unknown old oid sideband
  • clean/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook) — hidden ref, non-atomic sideband
  • clean/sideband/complete/two/withPack/on/v1/ok/ok/mixed(at=1,odd=ngHook) — hidden ref, atomic sideband
  • progress/sideband/complete/two/withPack/off/v1/ok/ok/uniform — noisy hooks, band 2 before and after the report
  • keepalive/sideband/complete/one/withPack/off/v1/ok/ok/uniform — slow hooks: keepalives before and after the report
  • dropBeforePack/plain/complete/one/withPack/off/v1/ok/ok/uniform — connection fails: dropBeforePack
  • dropMidPack/plain/complete/one/withPack/off/v1/ok/ok/uniform — connection fails: dropMidPack
  • dropAfterPack/plain/complete/one/withPack/off/v1/ok/ok/uniform — connection fails: dropAfterPack

Fsck tree entries

Decision. Given the bytes of a tree object (every read path parses one: readFile, listTree, editFile, pushTree, merge, rebase, checkoutTree; src/objects.js parseTree), does ply read it or refuse it (pack_corrupt), and what mode does it report for each entry? Then, given an accepted entry, may checkoutDir write it to disk?

Principle. ply reads exactly the trees git fsck --strict reports no error for, and reports each entry's mode as git's tree readers see it (object.h canon_mode on the low 16 bits; git ls-tree prints the same). A warning git exits 0 on (INFO under --strict) is decided per msgId below. checkoutDir writes exactly what git's checkout (read-cache.c verify_path) writes on that platform. The source is git v2.50.0: fsck.c fsck_tree, fsck_finish/fsck_blobs (the .gitmodules and .gitattributes it collects), verify_ordered; tree-walk.c decode_tree_entry; object.h parse_mode and canon_mode; utf8.c is_hfs_dot; path.c is_ntfs_dot; read-cache.c verify_path/verify_dotfile; compat/mingw.c is_valid_win32_path.

git's shape, from the source.

  • Modes. parse_mode reads octal digits into an unsigned int and stores a uint16_t, so only the low 16 bits exist: 7100644 and 300644 are 100644 to git, with not even a warning. fsck_tree's switch accepts 100755, 100644, 120000, 40000, 160000; 100664 only without --strict; anything else is badFilemode, which is INFO, so a warning even under --strict. Every other reader canonicalises: a regular file is 100755 if the owner-execute bit is set, else 100644; a type git does not know (1, 140000, 200644, 777777) is a gitlink. A leading 0 is zeroPaddedFilemode (WARN).
  • Names. An empty name never reaches fsck_tree's emptyName: decode_tree_entry refuses it ("empty filename in tree entry") and fsck reports badTree. .git is refused in every spelling HFS+ or NTFS resolves to it, on every platform: ASCII case, NTFS trailing dots and spaces, an NTFS stream (.git:x), the short name git~1 (only ~1: git puts .git first), the HFS+ ignorable code points anywhere, an invalid UTF-8 sequence after .git (next_hfs_char reads it as the end), and the same NTFS spellings after any backslash. A name over 4096 bytes is largePathname.
  • Dotfiles. .gitmodules in any HFS/NTFS spelling (gitmod~1, the fallback gi7eba~N, even ~1234567, and after a backslash) as a symlink is gitmodulesSymlink (ERROR); as anything else its object is checked in fsck_finish, so a tree there is gitmodulesBlob and a gitlink (whose commit is never in the repository) gitmodulesMissing. .gitattributes likewise (gitattributesBlob, gitattributesMissing; but as a symlink only gitattributesSymlink, INFO). .gitignore and .mailmap as symlinks are INFO.
  • Checkout. verify_path, with core.protectNTFS on by default everywhere and core.protectHFS on macOS, refuses a subset of what fsck --strict refuses, on Linux and macOS: the enumerator checks every accepted (name, mode) with git read-tree under both protections. On Windows a backslash is a separator and is refused outright, and is_valid_win32_path refuses reserved device names, : < > " | ? *, controls and a trailing space or period: derived from the source (no git for Windows runs here), held by checkoutPathRefusal.

Judgment calls.

  1. badFilemode is accepted and reported canonically. Real repositories carry 100664 from git's first weeks, and git checks them out (the enumerator's end-to-end test: git clone and checkoutDir of 100600, 100664, 100700, 7100644, 40755, 1 and 140000 are diff -r identical).
  2. A symlinked .gitattributes, .gitignore or .mailmap is accepted (INFO). merge reads a symlinked .gitattributes as its blob, as attr.c read_attr_from_blob does (no mode check).
  3. A .gitmodules or .gitattributes gitlink is refused, although fsck_finish would accept one whose oid happened to name a blob in the repository: ply cannot see the object's type when it parses the tree, and a gitlink's commit is not in the repository it points from.
  4. .gitattributes contents over git's caps (a line of 2048 bytes or more, a blob over 100 MiB) are an fsck error in the blob, not the tree; ply never parses blob contents as objects, and where it reads .gitattributes (merge) it ignores such a line or blob exactly as attr.c does (>=, one byte stricter than fsck's > on the size). Checked against git check-attr --source at 2047, 2048 and 2049 bytes, blob and symlink (FSCK_TREE_LARGE=1 adds 100 MiB - 1, 100 MiB and 100 MiB + 1; run 2026-10-31, all 9 cells agree).
  5. On Windows checkoutDir refuses (unsupported) a path git for Windows refuses; on Linux a backslash is a name byte and is written as git writes it.

Where main (c2ccba2) and train/1 (77eb2c0) disagreed with the table (FSCK_TREE_SRC=<git archive REV src>): main 5,056 of 24,864 cells, train/1 4,094.

cells main / train/1table → plycause
2,922 / 2,874refuse → acceptno check for nullSha1, largePathname, gitmodulesSymlink, gitmodulesBlob/Missing, gitattributesBlob/Missing; hasDotgit missed for .git:x, git~1:x, .git\xff, .git + an encoded surrogate, a\.git, a\git~1
72 / 72accept → refusegit~2 refused as .git (only git~1 is .git's short name)
836 / 836accept, wrong modethe raw mode returned (100664, 40755, 7100644, 1, ...): readers comparing with 40000 or 100644 saw a different type than git
1,176 / 312refuse, under a msgId git did not reportboth: git~2 called a bad name where git refuses the tree for another reason (264), a zero-padded entry with an empty name called zero-padded where git says badTree (48); main also: duplicates called "not sorted" (#34, fixed on train/1)
50 / 0namesmain: non-UTF-8 names decoded lossily (#43, fixed on train/1)

Security. On main and train/1, checkoutDir wrote a .gitmodules symlink (git refuses to check one out: CVE-2018-11235's class), and on Windows would have written a\.git\hooks\… into a nested .git and ..\x outside the target directory (git for Windows refuses any backslash). Both are refused now: the first by parseTree, the others by validatePath and checkoutPathRefusal.

Enumeration. test/space/fsck-tree.test.js builds every cell byte for byte, writes the space as packs (node:zlib, git index-pack without --strict, which judges nothing) and every 40th cell loose with git hash-object --literally, and runs git fsck --strict (both streams, exit code, every error in/warning in line, each pinned to the cell that owns an oid in it). It fails on any cell where the model's msgIds differ from git's, where ply's verdict differs from the table, where ply's refusal names no msgId git reported, or where an accepted entry's mode is not canon_mode. Measured 2026-10-31 (laptop, git 2.50.0): 24,864 cells, 31,365 objects, 0 disagreements, about 4 s.

Axes (tagged unions)

trigger — the other entry in the tree, carrying one fsck_tree msgId's trigger (19 variants)

  • alone — a one-entry tree
  • plain 100644 m — an ordinary sibling
  • nullSha1 100644 n — is_null_oid
  • fullPathname 100644 m/n — strchr(name, '/')
  • emptyName 100644 — an empty name: badTree (decode_tree_entry)
  • malformedMode 10x644 m — parse_mode: a non-octal digit, "malformed mode in tree entry": badTree
  • hasDot 100644 . — "."
  • hasDotdot 100644 .. — ".."
  • hasDotgit 100644 .git — is_hfs_dotgit || is_ntfs_dotgit
  • zeroPaddedFilemode 0100644 m — the mode's first byte is '0'
  • badFilemode 100664 m — S_IFREG|0664 under --strict
  • gitmodulesSymlink 120000 .gitmodules — S_ISLNK on a .gitmodules
  • gitmodulesBlob 40000 .gitmodules — a .gitmodules that is a tree: fsck_finish "non-blob found at .gitmodules"
  • gitattributesSymlink 120000 .gitattributes — S_ISLNK on a .gitattributes (INFO)
  • gitattributesMissing 160000 .gitattributes — a .gitattributes gitlink: fsck_finish cannot read the blob
  • gitignoreSymlink 120000 .gitignore — S_ISLNK on a .gitignore (INFO)
  • mailmapSymlink 120000 .mailmap — S_ISLNK on a .mailmap (INFO)
  • largePathname 100644 m×4097 — tree_entry_len > 4096
  • duplicateEntries — the cell's own name again, as 100644: verify_ordered TREE_HAS_DUPS

mode — the cell entry's mode bytes: every class fsck_tree's switch and parse_mode tell apart (14 variants)

  • blob 100644 — S_IFREG|0644: standard
  • exec 100755 — S_IFREG|0755: standard
  • symlink 120000 — S_IFLNK: standard
  • tree 40000 — S_IFDIR: standard
  • gitlink 160000 — S_IFGITLINK: standard
  • group 100664 — S_IFREG|0664: "we had a few of these early on"; badFilemode only under --strict
  • private 100600 — S_IFREG|0600: badFilemode (INFO); canon_mode 100644
  • dir755 40755 — S_IFDIR|0755: badFilemode; S_ISDIR, so it sorts and reads as a tree
  • gitlinkPerm 160644 — S_IFGITLINK|0644: badFilemode; canon_mode 160000
  • zeroPadded 0100644 — a leading 0: zeroPaddedFilemode (WARN), and the value is still 100644
  • zeroPaddedTree 040000 — the zero-padded tree mode old tools wrote: zeroPaddedFilemode
  • truncated 7100644 — parse_mode keeps 16 bits: 07100644 & 0xffff is 0100644, a standard mode (no report at all)
  • unknownType 1 — type bits 0: badFilemode; canon_mode makes it a gitlink
  • allBits 777777 — 0177777: badFilemode; type 0170000 is no type git knows, so a gitlink

name — the cell entry's name bytes: every spelling fsck_tree and verify_path tell apart (48 variants)

  • plain "a" — an ordinary name
  • dot "." — hasDot
  • dotdot ".." — hasDotdot
  • empty "" — decode_tree_entry: "empty filename in tree entry", so badTree (emptyName is unreachable)
  • slash "a/b" — fullPathname
  • dotgit ".git" — hasDotgit
  • DOTGIT ".GIT" — is_ntfs_dotgit and is_hfs_dotgit fold ASCII case
  • DotGit ".Git" — mixed case
  • short1 "git~1" — is_ntfs_dotgit: the 8.3 short name of .git
  • SHORT1 "GIT~1" — the short name, upper case
  • short2 "git~2" — not .git: git guarantees .git takes ~1 (path.c), so ~2 is an ordinary name
  • short10 "git~10" — git~1 followed by a digit: an ordinary name
  • trailDot ".git." — NTFS trims trailing dots
  • trailSpace ".git " — NTFS trims trailing spaces
  • trailMixed ".git. ." — dots and spaces, any mix
  • stream ".git:x" — an NTFS alternate data stream of .git
  • shortStream "git~1:x" — a stream of the short name
  • dotgitx ".gitx" — a longer name: ordinary
  • hfsZwnj ".g\xe2\x80\x8cit" — HFS+ ignores U+200C
  • hfsBom "\xef\xbb\xbf.git" — HFS+ ignores U+FEFF, also in front
  • hfsLrm ".git\xe2\x80\x8e" — HFS+ ignores U+200E, also at the end
  • hfsBadTail ".git\xff" — next_hfs_char reads an invalid sequence as the end of the name: .git
  • hfsSurrogate ".git\xed\xa0\x80" — a UTF-8-encoded surrogate is invalid to pick_one_utf8_char: the end, so .git
  • badLead "\xff.git" — invalid UTF-8 before the dot: not .git to HFS, not to NTFS
  • overlongDot "\xc0\xaegit" — an overlong "." is invalid, never a dot
  • backslash "a.git" — fsck_tree reads a backslash as a separator (is_ntfs_dotgit after it) on every platform
  • backslashShort "a\git~1" — the short name after a backslash
  • backslashDotdot "..\x" — fsck checks only .git after a backslash: accepted, and .. on Windows
  • gitmodules ".gitmodules" — gitmodulesSymlink as a symlink; collected for fsck_finish otherwise
  • GITMODULES ".GITMODULES" — case
  • gitmodulesTrail ".gitmodules ." — is_ntfs_dot_generic: trailing spaces and dots
  • gitmodulesStream ".gitmodules:x" — a stream
  • gitmodulesShort "gitmod~1" — the 6-character short name, ~1 to ~4
  • gitmodulesShort5 "gitmod~5" — ~5 is past the regular short names, and gitmod is not the fallback prefix: ordinary
  • gitmodulesFallback "GI7EBA~1" — the fallback short name (hash prefix gi7eba)
  • gitmodulesFallback9 "gi7eba~9" — the fallback allows ~1 to ~9
  • tildeDigits "~1234567" — is_ntfs_dot_generic's fallback loop takes a leading ~ and digits as every dotfile's short name
  • gitmodulesHfs ".gitmodu\xe2\x80\x8dles" — HFS+ ignorable inside
  • gitmodulesBackslash "a.gitmodules" — is_ntfs_dotgitmodules after a backslash
  • gitattributes ".gitattributes" — gitattributesSymlink (INFO) as a symlink
  • gitattributesShort "gi7d29~1" — its fallback short name
  • gitattributesBackslash "a.gitattributes" — fsck_tree checks only .gitmodules after a backslash
  • gitignore ".gitignore" — gitignoreSymlink (INFO)
  • gitignoreShort "gi250a~1" — its fallback short name
  • mailmap ".mailmap" — mailmapSymlink (INFO)
  • mailmapShort "maba30~1" — its fallback short name
  • long4096 "l×4096" — max_tree_entry_len: 4096 bytes is allowed
  • long4097 "l×4097" — largePathname

position — the order of the two entries in the tree bytes (the tree is sorted or not as the names fall) (2 variants)

  • cellFirst — the cell entry, then the trigger entry
  • triggerFirst — the trigger entry, then the cell entry

Product

Raw product: 19 × 14 × 48 × 2 = 25,536 (trigger × mode × name × position); a one-entry tree has no order: 24,864 cells.

Expected: ply accepts 1,350, refuses 23,514. Cells per msgId git reports (a cell can have several):

msgIdcells
badFilemode (warning)10,058
treeNotSorted9,744
hasDotgit9,184
zeroPaddedFilemode4,432
badTree3,150
gitmodulesBlob2,320
fullPathname1,792
hasDot1,792
hasDotdot1,792
largePathname1,792
gitattributesMissing1,726
gitmodulesSymlink1,660
duplicateEntries1,568
gitattributesSymlink (warning)1,429
gitignoreSymlink (warning)1,429
mailmapSymlink (warning)1,429
gitmodulesMissing1,400
nullSha11,330
gitattributesBlob315

Decisions for the warnings git exits 0 on

  • badFilemode → accept: git reads every such mode through canon_mode (100664 → 100644, 40755 → a tree, an unknown type → a gitlink) and checks it out; real repositories carry 100664 from git's first weeks. ply returns the canonical mode, as git ls-tree prints it
  • gitattributesSymlink → accept: git reads a symlinked .gitattributes from a tree as the blob it is (attr.c read_attr_from_blob has no mode check) and only declines to follow one in a worktree; ply has no worktree, and merge reads it as git merge-tree does
  • gitignoreSymlink → accept: ply never reads .gitignore
  • mailmapSymlink → accept: ply never reads .mailmap

Decision. What does ply do with what a server says about itself (the v2 capability advertisement, the ls-refs listing, the receive-pack capability list), and with what ply asks of it (atomic, push options, fetch arguments)? Four decisions, one space (test/space/advertisement.space.js):

decisionply entry pointoutcome
capsdiscover()ok with the parsed capabilities, or unsupported / protocol / remote_error / not_git / network
refslsRefs()ok with the refs and HEAD's target, or protocol / unsupported / remote_error
pushGitHttp.push (pushWithOptions)landed, or unsupported before a byte of the push is sent, or ambiguous (push-outcome's rule)
requestfetchPack()ok with the request lines and pack-objects invocation git's own request gets, or protocol

Principle. ply proceeds when git proceeds, and gives a typed refusal when git refuses or when a feature ply needs is absent. Every cell's expected value carries both sides (git: ok or refuse; ply: the outcome), and consistent() checks the rule on every cell: ply never proceeds where git refuses, and refuses where git proceeds only for a need it names (PLY_NEEDS: v2, the fetch command, sha1).

git's reading, from the source (git v2.50.0):

  • connect.c process_capabilities_v2 reads capability lines up to a flush and dies "expected flush after capabilities" on anything else; over HTTP a pkt after that flush is handed on as the ls-refs response ("invalid ls-refs response"). server_supports_v2 (presence: key or key=…), server_feature_v2 (value: the first key=…; a bare object-format is no value, so sha1) and server_supports_feature (the first key/key=… line, its value split on whitespace by parse_feature_value) all take the first matching line. send_capabilities dies "unknown object format" on a name hash_algo_by_name does not know; get_remote_refs dies "server doesn't support 'ls-refs'".
  • process_ref_v2 splits a record on every space (a doubled space is an empty field, an empty second field a ref named ""), skips an unborn <name> … record (it records HEAD's unborn target only for a clone that asked), reads the oid with parse_oid_hex_algop (either case), keeps symref-target: and peeled: and skips every other attribute; a bad peeled oid or a record of fewer than two fields is "invalid ls-refs response". A name listed twice stays twice in the list and find_ref_by_name takes the first (observed: git fetch of it fetches the first oid).
  • pkt-line.c packet_read_with_status dies "protocol error: bad line length" once a payload is ≥ its buffer, packet_buffer[LARGE_PACKET_MAX]: it reads payloads up to 65519 bytes.
  • send-pack.c send_pack checks, before sending anything, the repository hash against object-format (absent is sha1), then --atomic against atomic, then push options against push-options. builtin/receive-pack.c honours a client's atomic / push-options only when it advertised them, and dies on commands in another hash.
  • upload-pack.c process_args accepts no-progress, include-tag and deepen-relative unconditionally and filter only with uploadpack.allowFilter; fetch-pack.c warns "filtering not recognized by server, ignoring" and fetches everything.

Judgment calls.

  1. A plain push to a sha256 repository is ambiguous. ply reads the receive-pack advertisement only when the push needs a capability (atomic, push options); a plain push saves that round trip, receive-pack dies reading the sha1 commands and writes no report. Every ply flow reads ls-refs first, which refuses a sha256 listing as unsupported.
  2. A filter the server cannot honour is refused (protocol: upload-pack dies on the unexpected filter line and the stream ends without its flush), where git warns and fetches everything: fetchObject's bounded memory rests on the filter it asked for.
  3. v0 / v1 servers, a server without fetch, and sha256 are unsupported though git ls-remote proceeds: ply is v2-only, every ply read is ls-refs then fetch, and ply is sha1-only.
  4. Precedence among refusals in discover(): the pkt framing, the protocol, the advertisement's framing, ls-refs and fetch present, the object format. git reads the object format only when it sends ls-refs, but every cell where the orders differ is a refusal on both sides.

Found (each a cell class that disagreed with git on train/1, 77eb2c0; all fixed here):

#wheretrain/1gitnow
1discover: a capability listed twicethe last line wins (sha1 after sha256 proceeds; sha256 after sha1 refuses)the first winsthe first wins
2discover: object-format with no =unsupportedsha1, proceedssha1
3discover: no flush, or a delim, after the capabilitiesproceeds"expected flush after capabilities"protocol
4discover: a pkt after the capabilities' flushread as a capability, proceedsrefusesprotocol
5discover: no ls-refs (or no fetch)proceeds"server doesn't support 'ls-refs'"unsupported
6discover: ERR as the first lineunsupported"remote error"remote_error
7every pkt-line reader: a payload of 65520–65531 bytesaccepted"bad line length"protocol
8ls-refs: an unborn … recordprotocolskippedskipped
9ls-refs: an upper-case oid or peeled oidprotocolacceptedaccepted, kept lower-case
10ls-refs: an empty name (<oid> , <oid> <name>)protocola ref named ""a ref named ""
11ls-refs: a name listed twicethe last listingthe firstthe first
12push: atomic to a server that does not advertise itsent; receive-pack ignored it and the refs landed one by one; landedrefuses before sendingunsupported before sending
13push: atomic or push options to a sha256 repositoryadvertisement read, hash ignored, pushed: ambiguousrefuses before sendingunsupported before sending

The request decision found nothing: for each of no-progress, its absence, include-tag, deepen-relative and filter, ply's request lines equal git's own request for the same fetch and upload-pack invokes pack-objects with the same argv and stdin.

Enumeration. test/space/advertisement.test.js runs every caps and refs cell through ply's real path (createTransport with an in-process fetch serving the rendered bytes) and compares the table. Observed: a synthetic smart-HTTP server serves each observed cell's advertisement and ls-refs response and forwards fetch requests to git http-backend; git ls-remote judges every caps cell within one deviation of git's default advertisement and every refs cell, git fetch the fetch-feature cells (which features git uses, read from its own requests), git push every push cell against receive-pack configured per cell, and git fetch / git clone each request cell (its request lines and upload-pack's pack-objects invocation, captured by uploadpack.packObjectsHook). ply runs over real HTTP against the same server. Six real http-backend configurations (default, uploadpack.allowFilter=false, allowRefInWant + allowSidebandAll, lsrefs.unborn=ignore, transfer.advertiseSID, a sha256 repository) advertise exactly what the renderer writes for their cell. ADV_SPACE_SRC=<dir> runs the space against another copy of src/.

Axes (tagged unions)

caps protocol (8) — v2, v0, v1, err, v2service, serviceNoFlush, html, reset; only v2 carries the capability axes

caps (v2)

  • agent (3) — the agent capability: present, absent, empty
  • objectFormat (6) — object-format, read by send_capabilities with server_feature_v2 (needs =): sha1, absent, sha256, unknown, bare, empty
  • fetch (33) — the fetch command and its features: absent, features[], features[shallow wait-for-done filter ref-in-want sideband-all] (… every subset of the five features: 32 + absent)
  • lsRefs (3) — the ls-refs command: unborn, plain, absent
  • serverOption (2) — server-option: present, absent
  • sessionId (2) — session-id: absent, present
  • malformed (9) — one malformation of the advertisement: none, noLF, unknownCap, duplicate, longMax, longOver, noFlush, delim, trailing

refs

  • record (18) — one record of the listing, added to or changed in HEAD (symref), main, a tag (peeled): plain, unknownAttr, unbornHead, unbornOther, unbornOnly, emptySymref, emptyPeeled, badPeeled, upperOid, upperPeeled, emptyName, doubleSpace, oidOnly, badOid, sha256, duplicate, capsName, err
  • eol (2) — line ends: lf, none
  • framing (6) — the end of the listing: flush, noFlush, delim, trailing, longMax, longOver

push

  • request (4) — what the push asks for: none, atomic, options, both
  • atomic (2) — receive.advertiseAtomic: on, off
  • options (2) — receive.advertisePushOptions: off, on
  • format (2) — the server repository's hash: sha1, sha256

request

  • flag (5) — one fetch argument ply can send (fetch.js fetchBody): noProgress, progress, includeTag, deepenRelative, filter
  • server (2) — uploadpack.allowFilter: filterOn, filterOff

Cells

decisioncellsobserved from gitderived
caps64,1595964,100
refs2162160
push32320
request10100
all64,41731764,100

Push ng reasons

The space of git's receive-pack rejection reasons (test/space/push-ng.space.js): every reason git v2.50.0 can write × the failing command's shape × atomic × refs. Each reason's class is data, justified by what a caller can safely do next; the report git writes for each cell is derived from receive-pack.c and checked byte for byte against real git where git can be made to write it (test/space/push-ng.observed.js).

Axes: reason(42) × command(8) × atomic(2) × refs(3) × era(2) = 4032 raw; 1057 cells after the impossible ones (192: the reason is written only by the other execute_commands_* (atomic-only or non-atomic-only); 1488: git does not write the reason for this command shape (REASONS[].commands; gone is enumerated only with the transaction's own failures, where it changes the text); 176: three commands cannot all carry the reason (REASONS[].three); 20: an aliased update needs a second command (the symref's target); 72: a push whose every command deletes sends no pack: no unpack, nothing to migrate; 1027: the batched transaction changes only the non-atomic commit failure: every other report is the same on both eras, enumerated once (v2.50)).

Observable from real git: 791 cells (git's report byte for byte = the derived one, ply's outcome = the table's, refs agree), each on the git of its era: v2.50 cells on git 2.50 (a laptop), v2.51+ cells on git >= 2.51 (CI: 2.56); a run observes its own era's cells and derives the rest. Derived from receive-pack.c only: 266 (on a run as root, the two permission recipes are derived too).

reason (receive-pack.c line)classply outcomes over its cellscells (observed)what a caller can safely do next
eof before pack header was fully read (2201)unpackrejected(push_rejected)38 (38)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server
protocol error (pack signature mismatch detected) (2204)unpackrejected(push_rejected)38 (38)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server
protocol error (pack version unsupported) (2207)unpackrejected(push_rejected)38 (38)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server
unknown error in parse_pack_header (2210)unpackrejected(push_rejected)38 (0)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server Derived: parse_pack_header() returns only the three errors above for a header it read; the default case is unreachable.
unable to create temporary object directory (2254)unpackrejected(push_rejected)38 (38)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server
unpack-objects abnormal exit (2281)unpackrejected(push_rejected)38 (38)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server
index-pack fork failed (2313)unpackrejected(push_rejected)38 (0)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server Derived: start_command() failing to fork index-pack cannot be arranged from a request.
index-pack abnormal exit (2324)unpackrejected(push_rejected)38 (38)the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server
unpacker error (1938)unpack—— (a consequence: rides on other cells)written on every command exactly when unpack failed (execute_commands): the unpack line carries the cause; nothing moved
missing necessary objects (1777)rejectedambiguous, partial, rejected(push_rejected)36 (36)the pack does not complete the new commit's history (set_connectivity_errors); the same pack is refused again, so retrying it is futile; a fresh read does not repair a pack
deny updating a hidden ref (1825)rejectedambiguous, partial, rejected(push_rejected)36 (36)receive.hideRefs covers the ref: the server never lets a client write it, whatever its value
deny deleting a hidden ref (1823)rejectedambiguous, partial, rejected(push_rejected)6 (6)receive.hideRefs covers the ref: the server never lets a client delete it, whatever its value
broken symref (1684)rejectedambiguous, partial, rejected(push_rejected)36 (36)the ref is a symbolic ref the server cannot resolve (a loop): no value of the old oid makes it writable; the repository needs repair
inconsistent aliased update (1711)rejectedambiguous, partial, rejected(push_rejected)20 (20)one push names a symbolic ref and its target with different updates: the request contradicts itself, and resending it is refused again
shallow update not allowed (2425)rejectedambiguous, partial, rejected(push_rejected)36 (36)the pushed history ends at a shallow boundary the server lacks and receive.shallowUpdate is off: the same history is refused again (ply never sends shallow lines; a git client from a shallow clone does)
funny refname (1481)rejectedpreSend(bad_request)10 (10)the server refuses the ref name itself (check_refname_format(name + 5), one level allowed only for a delete): no retry can succeed, so ply refuses the push before sending a byte (validatePushRef, #73; every name checked against git in test/space/refname.test.js); git's report is still observed byte for byte
branch is currently checked out (1501)rejectedpartial, rejected(push_rejected)28 (28)receive.denyCurrentBranch refuses the non-bare repository's checked-out branch, whatever its value
bad pack (1515)rejectedpartial, rejected(push_rejected)36 (36)the new object is not in the repository after unpack (only with the connectivity check skipped): the same pack fails again
deletion prohibited (1522)rejectedpartial, rejected(push_rejected)6 (6)receive.denyDeletes: branch deletion is off on this server
deletion of the current branch prohibited (1539)rejectedpartial, rejected(push_rejected)4 (4)receive.denyDeleteCurrent refuses deleting HEAD's branch, whatever its value
Invalid denyDeleteCurrent setting (1542)rejectedpartial, rejected(push_rejected)4 (0)a server misconfiguration: nothing a client resends can change it Derived: parse_deny_action() maps every config value to a handled deny_action, so the switch's default is unreachable.
bad ref (1562)caspartial, rejected(cas_conflict)6 (6)receive.denyNonFastForwards could not parse the old oid the command named: the server does not have it, so the ref is not at it (a stale read of a ref that has since been rewritten): a fresh read names an old oid it has (SAFETY.md I31)
non-fast-forward (1573)nffpartial, rejected(not_fast_forward)6 (6)receive.denyNonFastForwards and the new commit does not descend from the old oid the command itself named: that is true of the request whatever the ref's value, so a fresh read of the ref cannot help; only a new commit that descends from it can (it was cas_conflict: rebase's non-fast-forward push looped on it)
hook declined (1579)rejectedpartial, rejected(push_rejected)42 (42)the update hook refused the ref: server policy, not a race
failed to delete (1606)rejectedpartial, rejected(push_rejected)6 (0)the ref store would not queue the deletion: deterministic for this name Derived: ref_transaction_delete() queues a deletion and fails only on a name refname_is_safe() refuses, which check_refname_format (funny refname) refused first.
shallow error (1616)rejectedpartial, rejected(push_rejected)36 (0)receive.shallowUpdate is on and the history above the shallow boundary is incomplete (update_shallow_ref): the same pack fails again Derived: not arranged: with receive.shallowUpdate=true, a shallow line and a pack lacking a blob above the boundary, git v2.50.0 answered "ok" for one command (the ref moved to a commit whose tree lacks the blob) and, for three, "shallow error" on the first command, then a report without the others' statuses (ply: ambiguous, a missing status).
failed to update ref (1627)caspartial, rejected(cas_conflict)36 (0)the same text as the commit failure below, so the same class (the report cannot tell them apart) Derived: ref_transaction_update() queues an update and fails only on a name check_refname_format refuses, which funny refname refused first.
Up-to-date check failed (1376)rejectedpartial, rejected(push_rejected)20 (20)receive.denyCurrentBranch=updateInstead: update-index --refresh failed in the server's worktree (its index is locked); the push is refused until someone changes the server's worktree
Working directory has unstaged changes (1388)rejectedpartial, rejected(push_rejected)20 (20)receive.denyCurrentBranch=updateInstead: the server's worktree has unstaged changes; the push is refused until someone changes the server's worktree
Working directory has staged changes (1402)rejectedpartial, rejected(push_rejected)24 (24)receive.denyCurrentBranch=updateInstead: the server's worktree has staged changes; the push is refused until someone changes the server's worktree
Could not update working tree to new HEAD (1414)rejectedpartial, rejected(push_rejected)24 (24)receive.denyCurrentBranch=updateInstead: read-tree -u -m could not check out the new commit (an untracked file is in the way); the push is refused until someone changes the server's worktree
push-to-checkout hook declined (1433)rejectedpartial, rejected(push_rejected)24 (24)receive.denyCurrentBranch=updateInstead: the push-to-checkout hook refused; the push is refused until someone changes the server's worktree
denyCurrentBranch = updateInstead needs a worktree (1449)rejectedpartial, rejected(push_rejected)24 (0)a server misconfiguration: nothing a client resends can change it Derived: update() sets do_update_worktree only for a worktree that is not bare, so update_worktree() never sees a bare one.
failed to update ref (1874, 2nd site)caspartial, rejected(cas_conflict), rejected(push_rejected)30 (30)the ref is not at the old oid the command named (a stale read, a create over an existing ref, a concurrent writer holding the lock): a fresh read and a redo can land. Also written for a D/F conflict (create refs/heads/r0/sub beside refs/heads/r0, observed): a fresh retry is safe but cannot land there, and a caller's retry budget bounds it
atomic transaction failed (1909)casrejected(cas_conflict)15 (15)an atomic push's single commit failed, which for a stale old oid is git v2.50.0's only report (every ref gets this text, none gets "failed to update ref", observed): the same lost race as above, so a fresh read and a redo can land (it was push_rejected: an atomic CAS loss was never retried)
atomic push failure (1886)innocent—— (a consequence: rides on other cells)an atomic push's other members after one command failed inside update(): nothing moved, and the culprit's reason decides the class
transaction failed to start (1864)rejectedpartial, rejected(push_rejected)21 (0)the server could not open a ref transaction: a server fault, and nothing moved Derived: ref_store_transaction_begin() cannot fail in git v2.50.0 (refs.c: it only allocates).
transaction failed to start (1893, 2nd site)rejectedrejected(push_rejected)21 (0)the server could not open a ref transaction: a server fault, and nothing moved Derived: ref_store_transaction_begin() cannot fail in git v2.50.0 (refs.c: it only allocates).
pre-receive hook declined (1987)rejectedrejected(push_rejected)42 (42)the pre-receive hook refused the push: server policy, not a race
unable to migrate objects to permanent storage (2008)rejectedrejected(push_rejected)38 (38)the server could not move the received objects out of quarantine (a storage fault): nothing moved, and a retry needs the server repaired
inconsistent push options (2599)rejectedrejected(push_rejected)42 (0)the request contradicts its own certificate: resending it is refused again Derived: needs a signed push (push-cert) whose push options differ from the request's; ply never sends a push certificate.
fail to run proc-receive hook (2027)ambiguousambiguous6 (6)the hook could not be run, or did not finish after it was handed the command: it may have acted on the command (a review created) without saying, and the report cannot tell which; read before redoing
proc-receive failed to report status (1103)ambiguousambiguous6 (6)the hook was handed the command and gave no status for it: it may have acted; read before redoing
failed (1093)rejectedambiguous, partial, rejected(push_rejected)6 (6)the proc-receive hook answered "ng <ref>" with no message: it refused the command, as an update hook does

git >= 2.51 batched texts (era v2.51+, the non-atomic commit failure):

textclasswhat a caller can safely do next
incorrect old value providedcasREF_TRANSACTION_ERROR_INCORRECT_OLD_VALUE: the ref is not at the old oid the command named: a fresh read and a redo can land
reference already existscasREF_TRANSACTION_ERROR_CREATE_EXISTS: a create lost to another writer's create: a fresh read finds the ref and the redo is an update
reference does not existcasREF_TRANSACTION_ERROR_NONEXISTENT_REF: the ref was deleted since the read: a fresh read finds it absent (it was push_rejected: git >= 2.51's stale update of a deleted ref was never re-read)
refname conflictrejectedREF_TRANSACTION_ERROR_NAME_CONFLICT: a D/F conflict (refs/heads/r0/sub beside refs/heads/r0): no value of the old oid makes the name free; git >= 2.51 tells it apart from a lost race, so ply need not retry it
invalid new value providedrejecteda batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again
expected symref but found regular refrejecteda batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again
reference conflict due to case-insensitive filesystemrejecteda batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again
unknown failurerejecteda batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again

Ref names

The space of ref names a caller can hand ply (test/space/refname.space.js, #73): refs/ + 1, 2 or 3 components, each one of 16 shapes (a, @, @a, @{a, {a, ., .., .a, a., a.lock, a.lockb, -a, the empty component, a control character, a space, non-ASCII), 16 + 256 + 4,096 names, plus one name per code point U+0001–U+00FF inside a component (254, LF excluded: it cannot be framed): 4,622 cells. Every cell asks real git three questions and ply must give git's answer on every one (test/space/refname.test.js):

questiongit's oracleply
formatgit check-ref-format <name> (refs.c check_refname_format(name, 0))validateRef
createa real git receive-pack answering a create of the name: ng <name> funny refname or not (receive-pack.c update(): check_refname_format(name + 5, 0))validatePushRef(name, false); push() refuses before sending
deletethe same for a delete (check_refname_format(name + 5, REFNAME_ALLOW_ONELEVEL))validatePushRef(name, true)

Git v2.50.0 accepts 726 names as refs, 719 for a create and 725 for a delete. The create/delete gap is receive-pack's, not check-ref-format's: refs/<one level> (refs/stash is one) is a valid ref and can be deleted by a push but never created or updated, and refs/@ is a valid ref no push can touch (@ alone is refused as a whole refname). Before #73 ply validated a push's ref with validateRef alone and disagreed with receive-pack on 8 cells, all of them those two shapes; git refused them as funny refname.

Default depth

Decision. fetchObject / objectAt asks for one object by id. Which deepen goes on the wire, and what happens when the server refuses it? (src/fetch.ts objectAt: depth, ask; src/transport.ts learnShallow. Space: test/space/default-depth.space.js, run by test/space/default-depth.test.js.)

Rules (the owner's; expected() is written from these, not from the code):

  • R1 One object costs one object's worth of pack. A want that is or may be a commit (expectType left out, COMMIT or TAG) is sent with deepen 1 when the server takes shallow requests. A want named a tree or a blob gets none.
  • R2 A caller's explicit deepen is sent as given and always wins (0: no deepen line).
  • R3 Without the capability ply behaves as on main, for every refusal shape. A default-depth request (the caller gave no deepen, 1 was sent, shallow not yet known for the quirks record) refused with an empty response, an ERR line or HTTP 400 reads the advertisement once per quirks record; if fetch= lists no shallow the want is asked again without deepen, once; if it is listed the first error stands. Never when the caller gave deepen.
  • R4 No extra round trip on a success path.

git's shape, from the source (git v2.50.0). upload-pack.c: a commit want with no depth is answered with every commit reachable from it; deepen <d> cuts that at d generations (shallow.c get_shallow_commits, which peels a tag want with deref_tag and skips a want that is not a commit). filter tree:0 drops trees and blobs but not ancestors, blob:none drops blobs. git's upload-pack always lists shallow on fetch= (filter only with uploadpack.allowFilter), so a server without shallow is not git: the space renders one by taking the word off git's own advertisement and refusing or dropping the deepen line in front of git's own upload-pack. An argument git does not take makes upload-pack die: over smart HTTP that is HTTP 200 with an empty body (the empty class).

Two things main already did that the expected values use, and that predate this decision: an empty response on the tree:0 path reads the advertisement for filter (the no-filter fallback: filterUnadvertised), and the single fetch (tree:0, filter '') refuses a pack of more than one object for a want not typed COMMIT (pack_corrupt; README, fetchObject). So an annotated tag wanted on the tree:0 path is pack_corrupt at depth 1 (the tag and the commit it peels to: two objects) as it was without a depth (the tag and the history).

Outside the space: the server's filter support. Every server in the space takes the filter its path sends. What a server does with filter is main's decision, made after this one and by the same lines: the request asked again without deepen is main's request, and on the tree:0 path its answer is read as main reads it (no filter on the advertisement just read: the unfiltered pack; tree:0 refused: blob:none; an empty response: the advertisement). It is not an axis here because it does not change which deepen is sent or whether the want is asked again, only which filter the re-ask carries; as an axis it would multiply the 3 tree:0 cells of each refusal by servers the filter fallback's own tests already enumerate. The product that does matter (deepen refused as ERR, 400 or empty × a server that lists filter and takes only blob:none, or lists none and dies on one; neither lists shallow) is 6 rows in test/fetchobject-deepen-refusal.test.js, each against git with main's outcome as the expected value.

Judgment calls.

  1. A stale listed. A record taught that the server lists shallow, on a server that no longer does, refused with an ERR line or HTTP 400 (or with an empty response on a path that does not read the advertisement): the first error stands (33 cells: 3 types × (4 + 4 + 3 paths)). R3's trigger needs shallow not yet known, and main would have succeeded here; the record is corrected by the next advertisement read (discover()). On the tree:0 path an empty response reads the advertisement anyway (main's filter fallback), and what it says about shallow is believed: the want is asked again without deepen (3 cells).
  2. A stale unlisted. A record taught that the server lists no shallow, on a server that now does: no deepen is sent and the answer is the history, held to the pack limits. That is main's request; R1 says "when the server takes shallow requests" and the record says it does not. Corrected by the next advertisement read.
  3. deepen ignored. The server answers with the history as if the line were not there. One request, ok (or the pack limits' refusal): ply learns it only from the pack, and R4 forbids a second request on a success path.
  4. The caller's depth refused (R2). The error stands in every shape, with no re-ask; on the tree:0 path an empty response still costs main's advertisement read for filter.

Axes

asked — the caller's deepen (3)

  • none — left out: the default depth applies (R1)
  • 0 — explicit 0: no deepen line, the whole history (R2)
  • 2 — explicit n: deepen 2, sent as given (R2)

expectType — the type the caller names; the want is an object of that type (5)

  • none — untyped: may be a commit (the want is the tip commit)
  • COMMIT — a commit
  • TAG — may peel to a commit (the want is an annotated tag of the tip)
  • TREE — no history is reachable from a tree: no default depth
  • BLOB — nor from a blob

knowledge — what the quirks record was taught about shallow before the call (by discover()) (3)

  • unlearned — no advertisement read for this record
  • listed — an advertisement that listed shallow
  • unlisted — an advertisement that did not

advertised — whether the server's fetch= line lists shallow during the call (differs from a learned knowledge when the server changed: stored state is untrusted) (2)

  • yes — git, GitHub, GitLab, Codeberg, Artifacts
  • no — a server without shallow fetches

refusal — what the server does with a request that carries deepen (5)

  • none — takes it: git
  • empty — HTTP 200 with an empty body: git upload-pack dying on an argument it does not take
  • err — an ERR pkt-line (remote_error)
  • 400 — HTTP 400: how Artifacts refuses an argument it does not take
  • ignored — drops the line and answers as if it were not there

path — objectAt's request path (4)

  • tree:0 — the single fetch, filter tree:0 (quirks.treeFilter tree:0)
  • blob:none — the wide fetch on a record that learned blob:none (Artifacts)
  • unfiltered — the wide fetch on a record that learned no filter (the server lists no filter)
  • filter '' — the single fetch with the caller's filter ''

Product

3 × 5 × 3 × 2 × 5 × 4 = 1,800 cells (asked × expectType × knowledge × advertised × refusal × path), none removed.

requests, in order → outcomecells
POST - → ok740
POST - → pack_corrupt220
POST 2 → ok180
POST 2 → http120
POST 2 → remote_error120
POST 2 → protocol90
POST 1 → ok68
POST 2 → pack_corrupt60
POST 2, GET → protocol30
POST 1 → pack_corrupt28
POST 1, GET, POST - → ok25
POST 1 → http24
POST 1 → remote_error24
POST 1 → protocol18
POST 1, GET → protocol15
POST 1, GET, POST - → pack_corrupt14
POST 1, GET → http12
POST 1, GET → remote_error12

SSH

SSH transport removed 2026-10-31; history on branch archive/ssh.

1# SPACE.md — the decision spaces
3A living document. Each section takes one decision ply makes, defines every axis the decision depends on as a tagged
4union of value classes justified from git's source, takes the product, and gives the expected outcome of every cell.
5The code is the source of truth: the axes, the product, the renderers and the expected outcome live in
6`test/space/<decision>.space.js`, the enumerator runs every cell through ply's real code path, and the generated part
7of each section is checked against the code by the test, so the two cannot drift. Fuzzing samples a space; this
8enumerates it. Add a decision point as a new section (and a new `test/space/*.space.js`).
10## Push outcome
12**Decision.** After `push()` has sent the commands and the pack, what may it tell the caller? One of:
14| outcome | meaning | code (retry) |
15|---|---|---|
16| `landed` | every commanded ref was updated | — (resolves) |
17| `rejected` | no ref was updated; the reasons are the server's | `cas_conflict` (fresh) when every refusal is a lost compare-and-swap, else `push_rejected` (no) |
18| `partial` | a non-atomic multi-ref push: the refs in `landed` were updated, those in `rejected` were not | `push_partial` (no) |
19| `ambiguous` | the refs may or may not have moved: read them back first | `ambiguous` (read) |
20| `preSend` | ply refused before sending a byte; definite: nothing changed | `bad_request` / `limit_exceeded` (no) |
22**Principle.** Once any request byte may have reached the server, a definite answer (`landed`, `rejected`, `partial`)
23needs positive evidence in exactly the shape git's receive-pack writes; every other post-send state is `ambiguous`.
24Before the request is sent, ply's own refusals are definite. The code is shaped the same way (src/push.ts): the wire is
25read into a tagged union of stream shapes (`streamStep`: `report` | `broken`), the report by a step machine
26(`reportStep`: `unpack` → `refs` | `malformed`, the one report parser) into a tagged union of report shapes
27(`classifyReport`: `statuses` | `unpackFailed` | `malformed`), `decideOutcome` is an exhaustive match over those tags
28whose only fallthrough is `ambiguous` (`landed` | `rejected` with a code and each refused ref's reason class |
29`partial` | `ambiguous`), and `outcomeResult` turns the outcome into the `Result` a caller matches on. Every step is an
30allowlist.
32**git's shape, from the source** (git v2.50.0):
34- `builtin/receive-pack.c` `report()` writes `unpack <status>` (`ok` when `unpack_status` is NULL), then for each command
35 in request order `ok <ref>` or `ng <ref> <error_string>`, then a flush; `report_v2()` writes the same and adds
36 `option refname|old-oid|new-oid|forced-update` lines after an `ok` only for a command a proc-receive hook reported
37 (`cmd->report`), repeating `ok <ref>` for each further report of the same command.
38- `unpack()` returns one of eight fixed strings (`parse_pack_header`: "eof before pack header was fully read",
39 "protocol error (pack signature mismatch detected)", "protocol error (pack version unsupported)", "unknown error in
40 parse_pack_header"; "unable to create temporary object directory", "unpack-objects abnormal exit", "index-pack fork
41 failed", "index-pack abnormal exit"). `execute_commands()` then marks every command `unpacker error` and returns;
42 nothing else sets that string. `cmd_receive_pack()` skips unpack entirely when `delete_only()`, so a delete-only push
43 always reports `unpack ok`.
44- `execute_commands_atomic()`: a failure inside the transaction marks every other command `atomic push failure` (or
45 `atomic transaction failed` / `transaction failed to start`); commands already refused before the transaction
46 (`reject_updates_to_hidden`, connectivity, `check_aliased_updates`) are skipped and the rest still commit. So an atomic
47 push *can* produce a git-shaped split (observed below: a hidden ref).
48- With side-band (`use_sideband`), the report buffer goes out as band-1 packets (`send_sideband`, chunked at
49 LARGE_PACKET_MAX), hook and unpack stderr as band 2 (`copy_to_sideband`, also post-receive after the report), empty
50 band-1 packets `0005\1` as keepalives while hooks run (`copy_to_sideband`; `use_keepalive` is KEEPALIVE_ALWAYS from
51 `execute_commands` on, so keepalives also follow the report during post-receive: observed), and a final outer flush
52 (`cmd_receive_pack`: `if (use_sideband) packet_flush(1)`). Without side-band the report's flush is the last byte and
53 hook output goes to stderr, not the wire. receive-pack never writes band 3 or `ERR`.
54- `send-pack.c` `receive_unpack_status()` / `receive_status()` and `sideband.c` `demultiplex_sideband()`: git's own
55 client fails the push on a missing unpack line, an invalid status word, EOF before the flush ("unexpected disconnect"),
56 band 3 ("remote error"), or an `ERR` packet (`PACKET_READ_DIE_ON_ERR_PACKET`). It tolerates (warns on) status lines
57 for unknown refs and accepts repeated statuses; ply does not: those are not shapes receive-pack writes.
59**Equivalences (not axes, with the reason).** *Create* (zero old oid) — `report()` never reads `old_oid`; a create
60differs from an update only in the reason text of an `ng`, which is the `ng` payload. *A delete beside an update* —
61`delete_only()` is false, so it is the `withPack` class. *Push options* — they change only the request
62(`read_push_options`); `check_cert_push_options` can refuse them only for a signed push, which ply never sends; an
63invalid option is a `refused` event. *The order of status lines* — receive-pack writes them in request order; ply
64matches each line to its ref and does not require the order (a reordering takes more than one byte to make, and every
65ref still needs exactly one exact line). *The text of an `ng` reason* — any printable ASCII is accepted (hooks, hosts and
66proc-receive choose it); it decides only `cas_conflict` versus `push_rejected` (`rejectionCode`, over the refused refs' classes), never landed versus not.
68**Judgment calls** (where git's behaviour is clear but the outcome is a choice):
701. *Atomic split.* An atomic push answered with some `ok` and some `ng` is `ambiguous`, even though git can produce it
71 (a hidden ref is refused before the transaction and the other refs commit: observed, `hidden ref, atomic`). The
72 caller asked for all-or-nothing; ply does not turn that into a partial success, and the read-back shows what landed.
732. *Option lines.* An `ok` followed by `option` lines (proc-receive, report-status-v2) means the server updated something
74 other than the commanded ref and oid (`refname`, `new-oid`); ply does not model proc-receive, so it is `ambiguous`.
75 Under v1 they are not git's at all.
763. *Unknown unpack failure text.* A non-`ok` unpack status that is not one of git's eight strings is `ambiguous`, even
77 with every ref `ng unpacker error`: a server that is not git may word it differently, and the cost is one read.
78 One exception, on positive evidence (#246): every commanded ref refused with the unpack status itself as its reason
79 (`unpack <s>`, then `ng <ref> <s>` for each ref) is `push_rejected`. Cloudflare Artifacts writes exactly that for a
80 pack it cannot unpack (observed 2026-11-10 on prod, plain and side-band, one and two refs, atomic or not:
81 "invalid pack entry type 0", "invalid zlib member", "pack stream incomplete at finish", "invalid pack signature").
82 It is never one byte from a definite cell of another outcome: the status must equal every ref's reason and not be
83 `ok` (the boundary enumeration, unchanged). No ref lines, a ref that does not echo the status, an `ok` beside it, or
84 a delete-only push stay `ambiguous`. Before this, such a report was `ambiguous` and a single-ref update was read
85 back: an invalid pack whose ref had not moved came back `cas_conflict`, and a caller retried a pack that cannot land.
864. *Anything after the final flush* (a second report, a transport error) is `ambiguous`, although the report before it
87 was complete.
885. *A connection failure before any response byte* is `ambiguous` even when the request was cut before the pack (the
89 server then changes nothing: observed). ply cannot tell how much of the body the server consumed.
906. *A delete-only push answered with an unpack failure* is `ambiguous`: receive-pack never unpacks for it.
92**Found while observing.** A delete whose old oid names an object the server does not have is applied regardless:
93`update()` warns "allowing deletion of corrupt ref", drops the old oid, deletes, and reports `ok` (observed: `delete
94with an unknown old oid`). The report is truthful (`landed`); the compare-and-swap is not. SAFETY.md I22 is narrowed
95accordingly.
97**Where main (a7a724e) disagreed with the table** (the enumerator run with `PUSH_SPACE_SRC=<git archive a7a724e src>`):
98412,008 of 4,331,598 cells.
100| cells | table → main | cause |
101|---:|---|---|
102| 276,312 | ambiguous → `limit_exceeded` (retry: no) | every flood cell: a report-line limit hit after the send kept its pre-send code |
103| 19,456 + 1,152 + 192 | ambiguous → rejected / cas_conflict / landed | plain stream with no final flush: main never required the report's flush |
104| 14,592 + 864 + 144 | ambiguous → rejected / cas_conflict / landed | side-band report without its own flush inside band 1 |
105| 19,456 + 1,152 + 192 | ambiguous → rejected / cas_conflict / landed | a second flush after the final flush |
106| 29,184 + 1,728 + 288 | ambiguous → rejected / cas_conflict / landed | band 1 carrying a partial pkt or a second flush after the report's flush |
107| 14,592 + 864 + 144 | ambiguous → rejected / cas_conflict / landed | an `ERR` packet before the report (main skipped the line), with any delivery |
108| 12,880 | ambiguous → push_rejected | unpack near-miss (`ok*`): issue #33, the ref had moved |
109| 12,712 | ambiguous → push_rejected | a git unpack failure beside ref lines that are not all `unpacker error` (incl. `ok`), or for a delete-only push |
110| 2,688 + 280 + 168 | ambiguous → rejected / cas_conflict / landed | option lines after `ok` (v1, or v2 proc-receive) |
111| 2,128 | ambiguous → push_rejected | `ng <ref> unpacker error` beside `unpack ok`, or beside other statuses |
112| 560 + 280 | partial → push_rejected / cas_conflict | non-atomic mixed ok/ng: main said "rejected" while some refs had landed |
114Boundary enumeration on main: 2,520 single-bit flips turn a landed cell into `push_rejected` (e.g. `unpack ok` →
115`unpack nk`); on the new code: none.
117**Enumeration.** `test/space/push-outcome.test.js` runs every cell through `push()` over a fake transport that frames
118the bytes as http.js does (no network, no randomness) and asserts the table's outcome; it fails on a cell without an
119expected outcome or with a different one, and prints cells explored / total. `test/space/push-outcome-boundary.js`
120(run as four slice files, `push-outcome-boundary.<0-3>.test.js`, base j in slice j % 4, partition checked by
121`push-outcome-boundary.plan.test.js`) takes the canonical bytes of every definite cell and enumerates every single-bit flip, single-byte deletion, single-byte
122insertion from {00 01 02 0a 20 30 6f ff} and truncation; each mutant must be the cell's own outcome or `ambiguous`
123(a `cas_conflict` may soften to `push_rejected`, never the reverse). Measured 2026-10-30 (a laptop, 4 workers, other test jobs running alongside):
1244,331,598 cells in 32.6 s (the test file, with 65 real-git scenarios, 54 s); 2,772 distinct definite cells,
1257,419,600 mutants in 43.3 s, 0 violations. Since #251 (the host-echoed unpack failure, #246) the space is 4,592 distinct definite cells and 12,981,904 mutants; measured 2026-11-10 on a 4-core box (taskset 0-3, 4 workers per slice): each slice alone 44-49 s, all four slices at once (vitest's 3 forks, then the fourth) 148-149 s per slice, 0 violations (#263). `PUSH_SPACE=quick` (the mutation gate) explores the 19,782 cells with at most
126two deviations from git's canonical answer (7 s on one worker).
128<!-- push-outcome: generated by scripts/space-md.mjs; do not edit by hand -->
130### Axes (tagged unions)
132**event** — what else happens around the exchange (14 variants)
134- `clean` — nothing else
135- `progress` — band 2 before the report (unpack/hook stderr via copy_to_sideband) and after it (post-receive)
136- `keepalive` — an empty band-1 packet "0005\1" before and after the report: copy_to_sideband sends it while hooks run (use_keepalive is KEEPALIVE_ALWAYS from execute_commands on, so post-receive too)
137- `band3Before` — band 3 before the report: demultiplex_sideband reports "remote error"; receive-pack itself never writes band 3
138- `band3After` — band 3 after the report, before the outer flush
139- `errPkt` — an "ERR " pkt before the report: packet_read dies (PACKET_READ_DIE_ON_ERR_PACKET in send_pack)
140- `dropBeforePack` — the connection fails after the commands, before the pack: the server unpacks nothing ("eof before pack header")
141- `dropMidPack` — the connection fails inside the pack: index-pack/unpack-objects fails, nothing is updated
142- `dropAfterPack` — the connection fails after the pack, before any response byte: the server may have updated the refs
143- `refused` (what="ref") — ply refuses before sending: validateRef refuses the ref name
144- `refused` (what="oid") — ply refuses before sending: an old/new oid that is not 40-hex
145- `refused` (what="maxRefs") — ply refuses before sending: more commands than limits.maxRefs
146- `refused` (what="packBytes") — ply refuses before sending: the built pack exceeds limits.maxPackBytes
147- `refused` (what="pushOption") — ply refuses before sending: a push option containing LF
149**framing** — how the report is carried (2 variants)
151- `plain` — no side-band: report() write_or_die(1, …); hook output goes to stderr, not the wire
152- `sideband` — side-band-64k: report pkts + flush inside one band-1 packet (send_sideband), then an outer flush (cmd_receive_pack)
154**delivery** — what reaches the client of the framed response (13 variants)
156- `complete` — every byte, then end of stream
157- `band1Split` — one band-1 packet per inner pkt: send_sideband() chunks at LARGE_PACKET_MAX; the client reassembles band 1 as a stream
158- `noFinalFlush` — the stream ends before the final flush: git dies (packet_read: "the remote end hung up") / demultiplex_sideband "unexpected disconnect"
159- `noReportFlush` — the report's own flush is missing inside band 1, the outer flush present
160- `cutAfterUnpack` — the stream ends cleanly after the unpack line (a cut at a pkt boundary)
161- `cutMidPkt` — the stream ends inside the last data pkt
162- `trailingPkt` — a second copy of the report after the final flush
163- `throwAfter` — every byte, then the transport fails (connection reset after the flush)
164- `flood` — 16 extra report lines: exceeds the client's report-line cap
165- `trailingFlush` — a second flush after the final flush
166- `band1Trailing` (extra="partial") — band 1 carries two more bytes after the report's flush (a pkt cut inside band 1)
167- `band1Trailing` (extra="flush") — band 1 carries a second report flush
168- `wrongBand` (band=5) — the report on band 5: one bit from band 1 (demultiplex_sideband: "bad band")
170**refs** — number of commanded refs (3 variants)
172- `one` — single-ref push (the edit pipeline)
173- `two` — smallest multi-ref push: first and last ref differ
174- `three` — a ref with neighbours on both sides (an interior position)
176**commands** — what the commands ask for; decides whether a pack is sent (2 variants)
178- `withPack` — some new oid is non-zero: cmd_receive_pack runs unpack_with_sideband()
179- `deleteOnly` — every new oid is zero: delete_only() skips unpack, so the status is always "unpack ok"
181**atomic** — the atomic capability (2 variants)
183- `off` — execute_commands_non_atomic(): one transaction per ref
184- `on` — execute_commands_atomic(): one transaction; a failure inside it marks every other command "atomic push failure"
186**format** — report-status v1 or v2, and option lines (4 variants)
188- `v1` — report(): unpack line, one ok/ng line per command, flush
189- `v2` — report_v2() without proc-receive: byte-identical to report()
190- `v2Options` — report_v2(): "option forced-update" after each ok, written only for proc-receive reports
191- `v1Options` — option lines when report-status-v2 was not negotiated: report() never writes them
193**unpack** — the unpack line (7 variants)
195- `ok` — report(): "unpack ok" when unpack_status is NULL
196- `gitError` (status="unpack-objects abnormal exit") — unpack(): one of git's fixed failure strings (observed with a corrupted pack)
197- `hostError` (status="invalid pack entry type 0") — a host's own unpack failure text (Cloudflare Artifacts, observed with a pack entry of type 0, #246): definite only when every ref echoes it
198- `absent` — no unpack line: send-pack.c receive_unpack_status fails
199- `unreadable` — status bytes 0xff 0xfe: not text
200- `nearMiss` (status="ok*") — one flip from "ok" (issue #33): neither "ok" nor a git failure string
201- `duplicated` — two "unpack ok" lines: receive_unpack_status reads one; the second is an invalid ref status
203**status** — every commanded ref's status (a mixed report overrides one ref, see spread) (11 variants)
205- `ok` — report(): "ok <ref>" when cmd->error_string is NULL
206- `ngCas` (reason="failed to update ref") — execute_commands_non_atomic(): ref_transaction_commit failed (stale old oid; observed from git 2.50)
207- `ngHook` (reason="hook declined") — update(): the update hook refused (observed)
208- `ngAtomic` (reason="atomic push failure") — execute_commands_atomic(): the innocent members of a failed atomic push (observed)
209- `ngUnpacker` (reason="unpacker error") — execute_commands(): every command, and only when unpack failed
210- `ngEcho` (reason="invalid pack entry type 0") — a host (Cloudflare Artifacts) refuses every ref with its unpack status as the reason (observed, #246); after "unpack ok" it is an ordinary refusal
211- `missing` — no status line for a commanded ref: report() writes one per command, so never git
212- `duplicate` — the ref's "ok" line twice: report() writes one per command; report_v2 repeats "ok" only with option lines (proc-receive)
213- `unexpected` — the ref's line names refs/heads/zz, a ref not commanded (send-pack.c receive_status: "unknown ref")
214- `unreadable` — the status word is not text (0xff 0xfe): send-pack.c receive_status "invalid ref status"
215- `nearMiss` — "ng <ref>" with no reason: report() always writes a reason; send-pack.c would read it as "failed"
217**spread** — statuses across refs: uniform, or one ref (at index `at`) differs (34 variants)
219- `uniform` — every ref has `status`
220- `mixed` — at ∈ {0, 1, 2} × odd ∈ the 11 `status` tags: 33 variants (the odd ref's status overrides `status` for ref `at`)
222### Product
224Raw product: 14 × 2 × 13 × 3 × 2 × 2 × 4 × 7 × 11 × 34 = **45,741,696** (event × framing × delivery × refs × commands × atomic × format × unpack × status × spread).
226| removed | why | raw cells |
227|---|---|---:|
228| impossible | plain framing has no band 1, 2 or 3 (use_sideband=0: hook output goes to stderr) | 7,791,168 |
229| impossible | a delete-only push sends no pack, so it cannot be cut inside or after one, nor refused for its size | 188,496 |
230| impossible | one ref cannot be mixed | 3,821,664 |
231| impossible | the odd ref index is beyond the commanded refs | 1,273,888 |
232| impossible | a mixed report whose odd status equals the common status is the uniform cell | 579,040 |
233| collapsed | no response is read (refused before sending, or the connection failed first): the response axes are irrelevant (framing, delivery, format, unpack, status, spread keep their first variant) | 25,949,538 |
235**Cells: 6,137,902.** Expected outcomes: ambiguous 6,128,160, rejected(push_rejected) 6,944, rejected(cas_conflict) 1,456, partial 1,120, landed 168, preSend(bad_request) 36, preSend(limit_exceeded) 18.
237### Observed from git (63 cells; the other 6,137,839 are derived)
239- `clean/plain/complete/one/withPack/off/v1/ok/ok/uniform` — all ok one/plain/v1/atomic off
240- `clean/plain/complete/one/withPack/on/v1/ok/ok/uniform` — all ok one/plain/v1/atomic on
241- `clean/plain/complete/one/withPack/off/v2/ok/ok/uniform` — all ok one/plain/v2/atomic off
242- `clean/plain/complete/one/withPack/on/v2/ok/ok/uniform` — all ok one/plain/v2/atomic on
243- `clean/sideband/complete/one/withPack/off/v1/ok/ok/uniform` — all ok one/sideband/v1/atomic off
244- `clean/sideband/complete/one/withPack/on/v1/ok/ok/uniform` — all ok one/sideband/v1/atomic on
245- `clean/sideband/complete/one/withPack/off/v2/ok/ok/uniform` — all ok one/sideband/v2/atomic off
246- `clean/sideband/complete/one/withPack/on/v2/ok/ok/uniform` — all ok one/sideband/v2/atomic on
247- `clean/plain/complete/two/withPack/off/v1/ok/ok/uniform` — all ok two/plain/v1/atomic off
248- `clean/plain/complete/two/withPack/on/v1/ok/ok/uniform` — all ok two/plain/v1/atomic on
249- `clean/plain/complete/two/withPack/off/v2/ok/ok/uniform` — all ok two/plain/v2/atomic off
250- `clean/plain/complete/two/withPack/on/v2/ok/ok/uniform` — all ok two/plain/v2/atomic on
251- `clean/sideband/complete/two/withPack/off/v1/ok/ok/uniform` — all ok two/sideband/v1/atomic off
252- `clean/sideband/complete/two/withPack/on/v1/ok/ok/uniform` — all ok two/sideband/v1/atomic on
253- `clean/sideband/complete/two/withPack/off/v2/ok/ok/uniform` — all ok two/sideband/v2/atomic off
254- `clean/sideband/complete/two/withPack/on/v2/ok/ok/uniform` — all ok two/sideband/v2/atomic on
255- `clean/plain/complete/three/withPack/off/v1/ok/ok/uniform` — all ok three/plain/v1/atomic off
256- `clean/plain/complete/three/withPack/on/v1/ok/ok/uniform` — all ok three/plain/v1/atomic on
257- `clean/plain/complete/three/withPack/off/v2/ok/ok/uniform` — all ok three/plain/v2/atomic off
258- `clean/plain/complete/three/withPack/on/v2/ok/ok/uniform` — all ok three/plain/v2/atomic on
259- `clean/sideband/complete/three/withPack/off/v1/ok/ok/uniform` — all ok three/sideband/v1/atomic off
260- `clean/sideband/complete/three/withPack/on/v1/ok/ok/uniform` — all ok three/sideband/v1/atomic on
261- `clean/sideband/complete/three/withPack/off/v2/ok/ok/uniform` — all ok three/sideband/v2/atomic off
262- `clean/sideband/complete/three/withPack/on/v2/ok/ok/uniform` — all ok three/sideband/v2/atomic on
263- `clean/plain/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 two/plain/v1; hidden ref, non-atomic plain
264- `clean/plain/complete/two/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic two/plain/v1
265- `clean/plain/complete/two/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 two/plain/v2
266- `clean/plain/complete/two/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic two/plain/v2
267- `progress/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 two/sideband/v1
268- `progress/sideband/complete/two/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic two/sideband/v1
269- `progress/sideband/complete/two/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 two/sideband/v2
270- `progress/sideband/complete/two/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic two/sideband/v2
271- `clean/plain/complete/three/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 three/plain/v1
272- `clean/plain/complete/three/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic three/plain/v1
273- `clean/plain/complete/three/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 three/plain/v2
274- `clean/plain/complete/three/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic three/plain/v2
275- `progress/sideband/complete/three/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 three/sideband/v1
276- `progress/sideband/complete/three/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic three/sideband/v1
277- `progress/sideband/complete/three/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)` — update hook refuses r1 three/sideband/v2
278- `progress/sideband/complete/three/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)` — update hook refuses r1, atomic three/sideband/v2
279- `clean/plain/complete/two/withPack/off/v1/ok/ngHook(reason=hook declined)/uniform` — pre-receive refuses plain
280- `clean/plain/complete/one/withPack/off/v1/ok/ngCas(reason=failed to update ref)/uniform` — stale old oid plain
281- `clean/plain/complete/two/withPack/off/v1/ok/ok/mixed(at=0,odd=ngCas)` — stale old oid, two refs plain
282- `clean/plain/complete/one/withPack/off/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform` — corrupted pack plain
283- `clean/plain/complete/two/withPack/on/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform` — corrupted pack, two refs, atomic plain
284- `clean/plain/complete/one/deleteOnly/off/v1/ok/ok/uniform` — delete plain; delete with an unknown old oid plain
285- `clean/plain/complete/two/deleteOnly/off/v1/ok/ok/mixed(at=1,odd=ngCas)` — delete two, one stale plain
286- `clean/plain/complete/two/withPack/on/v1/ok/ok/mixed(at=1,odd=ngHook)` — hidden ref, atomic plain
287- `progress/sideband/complete/two/withPack/off/v1/ok/ngHook(reason=hook declined)/uniform` — pre-receive refuses sideband
288- `progress/sideband/complete/one/withPack/off/v1/ok/ngCas(reason=failed to update ref)/uniform` — stale old oid sideband
289- `progress/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=0,odd=ngCas)` — stale old oid, two refs sideband
290- `progress/sideband/complete/one/withPack/off/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform` — corrupted pack sideband
291- `progress/sideband/complete/two/withPack/on/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform` — corrupted pack, two refs, atomic sideband
292- `clean/sideband/complete/one/deleteOnly/off/v1/ok/ok/uniform` — delete sideband
293- `progress/sideband/complete/two/deleteOnly/off/v1/ok/ok/mixed(at=1,odd=ngCas)` — delete two, one stale sideband
294- `progress/sideband/complete/one/deleteOnly/off/v1/ok/ok/uniform` — delete with an unknown old oid sideband
295- `clean/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)` — hidden ref, non-atomic sideband
296- `clean/sideband/complete/two/withPack/on/v1/ok/ok/mixed(at=1,odd=ngHook)` — hidden ref, atomic sideband
297- `progress/sideband/complete/two/withPack/off/v1/ok/ok/uniform` — noisy hooks, band 2 before and after the report
298- `keepalive/sideband/complete/one/withPack/off/v1/ok/ok/uniform` — slow hooks: keepalives before and after the report
299- `dropBeforePack/plain/complete/one/withPack/off/v1/ok/ok/uniform` — connection fails: dropBeforePack
300- `dropMidPack/plain/complete/one/withPack/off/v1/ok/ok/uniform` — connection fails: dropMidPack
301- `dropAfterPack/plain/complete/one/withPack/off/v1/ok/ok/uniform` — connection fails: dropAfterPack
303<!-- push-outcome: end generated -->
305## Fsck tree entries
307**Decision.** Given the bytes of a tree object (every read path parses one: readFile, listTree, editFile, pushTree,
308merge, rebase, checkoutTree; `src/objects.js` parseTree), does ply read it or refuse it (`pack_corrupt`), and what mode
309does it report for each entry? Then, given an accepted entry, may checkoutDir write it to disk?
311**Principle.** ply reads exactly the trees `git fsck --strict` reports no error for, and reports each entry's mode as
312git's tree readers see it (object.h canon_mode on the low 16 bits; `git ls-tree` prints the same). A warning git exits
3130 on (INFO under --strict) is decided per msgId below. checkoutDir writes exactly what git's checkout (read-cache.c
314verify_path) writes on that platform. The source is git v2.50.0: fsck.c fsck_tree, fsck_finish/fsck_blobs (the
315.gitmodules and .gitattributes it collects), verify_ordered; tree-walk.c decode_tree_entry; object.h parse_mode and
316canon_mode; utf8.c is_hfs_dot*; path.c is_ntfs_dot*; read-cache.c verify_path/verify_dotfile; compat/mingw.c
317is_valid_win32_path.
319**git's shape, from the source.**
321- *Modes.* parse_mode reads octal digits into an `unsigned int` and stores a `uint16_t`, so only the low 16 bits exist:
322 `7100644` and `300644` are 100644 to git, with not even a warning. fsck_tree's switch accepts 100755, 100644, 120000,
323 40000, 160000; 100664 only without --strict; anything else is badFilemode, which is INFO, so a warning even under
324 --strict. Every other reader canonicalises: a regular file is 100755 if the owner-execute bit is set, else 100644; a
325 type git does not know (1, 140000, 200644, 777777) is a gitlink. A leading `0` is zeroPaddedFilemode (WARN).
326- *Names.* An empty name never reaches fsck_tree's emptyName: decode_tree_entry refuses it ("empty filename in tree
327 entry") and fsck reports badTree. `.git` is refused in every spelling HFS+ or NTFS resolves to it, on every platform:
328 ASCII case, NTFS trailing dots and spaces, an NTFS stream (`.git:x`), the short name `git~1` (only ~1: git puts .git
329 first), the HFS+ ignorable code points anywhere, an invalid UTF-8 sequence after `.git` (next_hfs_char reads it as the
330 end), and the same NTFS spellings after any backslash. A name over 4096 bytes is largePathname.
331- *Dotfiles.* `.gitmodules` in any HFS/NTFS spelling (`gitmod~1`, the fallback `gi7eba~N`, even `~1234567`, and after a
332 backslash) as a symlink is gitmodulesSymlink (ERROR); as anything else its object is checked in fsck_finish, so a tree
333 there is gitmodulesBlob and a gitlink (whose commit is never in the repository) gitmodulesMissing. `.gitattributes`
334 likewise (gitattributesBlob, gitattributesMissing; but as a symlink only gitattributesSymlink, INFO). `.gitignore` and
335 `.mailmap` as symlinks are INFO.
336- *Checkout.* verify_path, with core.protectNTFS on by default everywhere and core.protectHFS on macOS, refuses a subset
337 of what fsck --strict refuses, on Linux and macOS: the enumerator checks every accepted (name, mode) with `git read-tree`
338 under both protections. On Windows a backslash is a separator and is refused outright, and is_valid_win32_path refuses
339 reserved device names, `: < > " | ? *`, controls and a trailing space or period: derived from the source (no git for
340 Windows runs here), held by checkoutPathRefusal.
342**Judgment calls.**
3441. *badFilemode is accepted* and reported canonically. Real repositories carry 100664 from git's first weeks, and git
345 checks them out (the enumerator's end-to-end test: `git clone` and checkoutDir of 100600, 100664, 100700, 7100644,
346 40755, 1 and 140000 are `diff -r` identical).
3472. *A symlinked .gitattributes, .gitignore or .mailmap is accepted* (INFO). merge reads a symlinked .gitattributes as its
348 blob, as attr.c read_attr_from_blob does (no mode check).
3493. *A .gitmodules or .gitattributes gitlink is refused*, although fsck_finish would accept one whose oid happened to name
350 a blob in the repository: ply cannot see the object's type when it parses the tree, and a gitlink's commit is not in
351 the repository it points from.
3524. *.gitattributes contents over git's caps* (a line of 2048 bytes or more, a blob over 100 MiB) are an fsck error in
353 the blob, not the tree; ply never parses blob contents as objects, and where it reads .gitattributes (merge) it
354 ignores such a line or blob exactly as attr.c does (`>=`, one byte stricter than fsck's `>` on the size). Checked
355 against `git check-attr --source` at 2047, 2048 and 2049 bytes, blob and symlink (FSCK_TREE_LARGE=1 adds 100 MiB - 1,
356 100 MiB and 100 MiB + 1; run 2026-10-31, all 9 cells agree).
3575. *On Windows checkoutDir refuses (`unsupported`)* a path git for Windows refuses; on Linux a backslash is a name byte
358 and is written as git writes it.
360**Where main (c2ccba2) and train/1 (77eb2c0) disagreed with the table** (`FSCK_TREE_SRC=<git archive REV src>`): main
3615,056 of 24,864 cells, train/1 4,094.
363| cells main / train/1 | table → ply | cause |
364|---:|---|---|
365| 2,922 / 2,874 | refuse → accept | no check for nullSha1, largePathname, gitmodulesSymlink, gitmodulesBlob/Missing, gitattributesBlob/Missing; hasDotgit missed for `.git:x`, `git~1:x`, `.git\xff`, `.git` + an encoded surrogate, `a\.git`, `a\git~1` |
366| 72 / 72 | accept → refuse | `git~2` refused as .git (only `git~1` is .git's short name) |
367| 836 / 836 | accept, wrong mode | the raw mode returned (100664, 40755, 7100644, 1, ...): readers comparing with `40000` or `100644` saw a different type than git |
368| 1,176 / 312 | refuse, under a msgId git did not report | both: `git~2` called a bad name where git refuses the tree for another reason (264), a zero-padded entry with an empty name called zero-padded where git says badTree (48); main also: duplicates called "not sorted" (#34, fixed on train/1) |
369| 50 / 0 | names | main: non-UTF-8 names decoded lossily (#43, fixed on train/1) |
371**Security.** On main and train/1, checkoutDir wrote a `.gitmodules` symlink (git refuses to check one out: CVE-2018-11235's
372class), and on Windows would have written `a\.git\hooks\…` into a nested `.git` and `..\x` outside the target
373directory (git for Windows refuses any backslash). Both are refused now: the first by parseTree, the others by validatePath
374and checkoutPathRefusal.
376**Enumeration.** `test/space/fsck-tree.test.js` builds every cell byte for byte, writes the space as packs (node:zlib,
377`git index-pack` without --strict, which judges nothing) and every 40th cell loose with `git hash-object --literally`,
378and runs `git fsck --strict` (both streams, exit code, every `error in`/`warning in` line, each pinned to the cell that
379owns an oid in it). It fails on any cell where the model's msgIds differ from git's, where ply's verdict differs from the
380table, where ply's refusal names no msgId git reported, or where an accepted entry's mode is not canon_mode. Measured
3812026-10-31 (laptop, git 2.50.0): 24,864 cells, 31,365 objects, 0 disagreements, about 4 s.
383<!-- fsck-tree: generated by scripts/space-md.mjs; do not edit by hand -->
385### Axes (tagged unions)
387**trigger** — the other entry in the tree, carrying one fsck_tree msgId's trigger (19 variants)
389- `alone` — a one-entry tree
390- `plain` `100644 m` — an ordinary sibling
391- `nullSha1` `100644 n` — is_null_oid
392- `fullPathname` `100644 m/n` — strchr(name, '/')
393- `emptyName` `100644 ` — an empty name: badTree (decode_tree_entry)
394- `malformedMode` `10x644 m` — parse_mode: a non-octal digit, "malformed mode in tree entry": badTree
395- `hasDot` `100644 .` — "."
396- `hasDotdot` `100644 ..` — ".."
397- `hasDotgit` `100644 .git` — is_hfs_dotgit || is_ntfs_dotgit
398- `zeroPaddedFilemode` `0100644 m` — the mode's first byte is '0'
399- `badFilemode` `100664 m` — S_IFREG|0664 under --strict
400- `gitmodulesSymlink` `120000 .gitmodules` — S_ISLNK on a .gitmodules
401- `gitmodulesBlob` `40000 .gitmodules` — a .gitmodules that is a tree: fsck_finish "non-blob found at .gitmodules"
402- `gitattributesSymlink` `120000 .gitattributes` — S_ISLNK on a .gitattributes (INFO)
403- `gitattributesMissing` `160000 .gitattributes` — a .gitattributes gitlink: fsck_finish cannot read the blob
404- `gitignoreSymlink` `120000 .gitignore` — S_ISLNK on a .gitignore (INFO)
405- `mailmapSymlink` `120000 .mailmap` — S_ISLNK on a .mailmap (INFO)
406- `largePathname` `100644 m×4097` — tree_entry_len > 4096
407- `duplicateEntries` — the cell's own name again, as 100644: verify_ordered TREE_HAS_DUPS
409**mode** — the cell entry's mode bytes: every class fsck_tree's switch and parse_mode tell apart (14 variants)
411- `blob` `100644` — S_IFREG|0644: standard
412- `exec` `100755` — S_IFREG|0755: standard
413- `symlink` `120000` — S_IFLNK: standard
414- `tree` `40000` — S_IFDIR: standard
415- `gitlink` `160000` — S_IFGITLINK: standard
416- `group` `100664` — S_IFREG|0664: "we had a few of these early on"; badFilemode only under --strict
417- `private` `100600` — S_IFREG|0600: badFilemode (INFO); canon_mode 100644
418- `dir755` `40755` — S_IFDIR|0755: badFilemode; S_ISDIR, so it sorts and reads as a tree
419- `gitlinkPerm` `160644` — S_IFGITLINK|0644: badFilemode; canon_mode 160000
420- `zeroPadded` `0100644` — a leading 0: zeroPaddedFilemode (WARN), and the value is still 100644
421- `zeroPaddedTree` `040000` — the zero-padded tree mode old tools wrote: zeroPaddedFilemode
422- `truncated` `7100644` — parse_mode keeps 16 bits: 07100644 & 0xffff is 0100644, a standard mode (no report at all)
423- `unknownType` `1` — type bits 0: badFilemode; canon_mode makes it a gitlink
424- `allBits` `777777` — 0177777: badFilemode; type 0170000 is no type git knows, so a gitlink
426**name** — the cell entry's name bytes: every spelling fsck_tree and verify_path tell apart (48 variants)
428- `plain` "a" — an ordinary name
429- `dot` "." — hasDot
430- `dotdot` ".." — hasDotdot
431- `empty` "" — decode_tree_entry: "empty filename in tree entry", so badTree (emptyName is unreachable)
432- `slash` "a/b" — fullPathname
433- `dotgit` ".git" — hasDotgit
434- `DOTGIT` ".GIT" — is_ntfs_dotgit and is_hfs_dotgit fold ASCII case
435- `DotGit` ".Git" — mixed case
436- `short1` "git~1" — is_ntfs_dotgit: the 8.3 short name of .git
437- `SHORT1` "GIT~1" — the short name, upper case
438- `short2` "git~2" — not .git: git guarantees .git takes ~1 (path.c), so ~2 is an ordinary name
439- `short10` "git~10" — git~1 followed by a digit: an ordinary name
440- `trailDot` ".git." — NTFS trims trailing dots
441- `trailSpace` ".git " — NTFS trims trailing spaces
442- `trailMixed` ".git. ." — dots and spaces, any mix
443- `stream` ".git:x" — an NTFS alternate data stream of .git
444- `shortStream` "git~1:x" — a stream of the short name
445- `dotgitx` ".gitx" — a longer name: ordinary
446- `hfsZwnj` ".g\xe2\x80\x8cit" — HFS+ ignores U+200C
447- `hfsBom` "\xef\xbb\xbf.git" — HFS+ ignores U+FEFF, also in front
448- `hfsLrm` ".git\xe2\x80\x8e" — HFS+ ignores U+200E, also at the end
449- `hfsBadTail` ".git\xff" — next_hfs_char reads an invalid sequence as the end of the name: .git
450- `hfsSurrogate` ".git\xed\xa0\x80" — a UTF-8-encoded surrogate is invalid to pick_one_utf8_char: the end, so .git
451- `badLead` "\xff.git" — invalid UTF-8 before the dot: not .git to HFS, not to NTFS
452- `overlongDot` "\xc0\xaegit" — an overlong "." is invalid, never a dot
453- `backslash` "a\.git" — fsck_tree reads a backslash as a separator (is_ntfs_dotgit after it) on every platform
454- `backslashShort` "a\git~1" — the short name after a backslash
455- `backslashDotdot` "..\x" — fsck checks only .git after a backslash: accepted, and `..` on Windows
456- `gitmodules` ".gitmodules" — gitmodulesSymlink as a symlink; collected for fsck_finish otherwise
457- `GITMODULES` ".GITMODULES" — case
458- `gitmodulesTrail` ".gitmodules ." — is_ntfs_dot_generic: trailing spaces and dots
459- `gitmodulesStream` ".gitmodules:x" — a stream
460- `gitmodulesShort` "gitmod~1" — the 6-character short name, ~1 to ~4
461- `gitmodulesShort5` "gitmod~5" — ~5 is past the regular short names, and gitmod is not the fallback prefix: ordinary
462- `gitmodulesFallback` "GI7EBA~1" — the fallback short name (hash prefix gi7eba)
463- `gitmodulesFallback9` "gi7eba~9" — the fallback allows ~1 to ~9
464- `tildeDigits` "~1234567" — is_ntfs_dot_generic's fallback loop takes a leading ~ and digits as every dotfile's short name
465- `gitmodulesHfs` ".gitmodu\xe2\x80\x8dles" — HFS+ ignorable inside
466- `gitmodulesBackslash` "a\.gitmodules" — is_ntfs_dotgitmodules after a backslash
467- `gitattributes` ".gitattributes" — gitattributesSymlink (INFO) as a symlink
468- `gitattributesShort` "gi7d29~1" — its fallback short name
469- `gitattributesBackslash` "a\.gitattributes" — fsck_tree checks only .gitmodules after a backslash
470- `gitignore` ".gitignore" — gitignoreSymlink (INFO)
471- `gitignoreShort` "gi250a~1" — its fallback short name
472- `mailmap` ".mailmap" — mailmapSymlink (INFO)
473- `mailmapShort` "maba30~1" — its fallback short name
474- `long4096` "l×4096" — max_tree_entry_len: 4096 bytes is allowed
475- `long4097` "l×4097" — largePathname
477**position** — the order of the two entries in the tree bytes (the tree is sorted or not as the names fall) (2 variants)
479- `cellFirst` — the cell entry, then the trigger entry
480- `triggerFirst` — the trigger entry, then the cell entry
482### Product
484Raw product: 19 × 14 × 48 × 2 = **25,536** (trigger × mode × name × position); a one-entry tree has no order: **24,864 cells**.
486Expected: ply accepts 1,350, refuses 23,514. Cells per msgId git reports (a cell can have several):
488| msgId | cells |
489|---|---:|
490| `badFilemode (warning)` | 10,058 |
491| `treeNotSorted` | 9,744 |
492| `hasDotgit` | 9,184 |
493| `zeroPaddedFilemode` | 4,432 |
494| `badTree` | 3,150 |
495| `gitmodulesBlob` | 2,320 |
496| `fullPathname` | 1,792 |
497| `hasDot` | 1,792 |
498| `hasDotdot` | 1,792 |
499| `largePathname` | 1,792 |
500| `gitattributesMissing` | 1,726 |
501| `gitmodulesSymlink` | 1,660 |
502| `duplicateEntries` | 1,568 |
503| `gitattributesSymlink (warning)` | 1,429 |
504| `gitignoreSymlink (warning)` | 1,429 |
505| `mailmapSymlink (warning)` | 1,429 |
506| `gitmodulesMissing` | 1,400 |
507| `nullSha1` | 1,330 |
508| `gitattributesBlob` | 315 |
510### Decisions for the warnings git exits 0 on
512- `badFilemode` → accept: git reads every such mode through canon_mode (100664 → 100644, 40755 → a tree, an unknown type → a gitlink) and checks it out; real repositories carry 100664 from git's first weeks. ply returns the canonical mode, as `git ls-tree` prints it
513- `gitattributesSymlink` → accept: git reads a symlinked .gitattributes from a tree as the blob it is (attr.c read_attr_from_blob has no mode check) and only declines to follow one in a worktree; ply has no worktree, and merge reads it as git merge-tree does
514- `gitignoreSymlink` → accept: ply never reads .gitignore
515- `mailmapSymlink` → accept: ply never reads .mailmap
517<!-- fsck-tree: end generated -->
519## Advertisement
521**Decision.** What does ply do with what a server says about itself (the v2 capability advertisement, the ls-refs
522listing, the receive-pack capability list), and with what ply asks of it (atomic, push options, fetch arguments)? Four
523decisions, one space (`test/space/advertisement.space.js`):
525| decision | ply entry point | outcome |
526|---|---|---|
527| `caps` | `discover()` | `ok` with the parsed capabilities, or `unsupported` / `protocol` / `remote_error` / `not_git` / `network` |
528| `refs` | `lsRefs()` | `ok` with the refs and HEAD's target, or `protocol` / `unsupported` / `remote_error` |
529| `push` | `GitHttp.push` (`pushWithOptions`) | `landed`, or `unsupported` before a byte of the push is sent, or `ambiguous` (push-outcome's rule) |
530| `request` | `fetchPack()` | `ok` with the request lines and pack-objects invocation git's own request gets, or `protocol` |
532**Principle.** ply proceeds when git proceeds, and gives a typed refusal when git refuses or when a feature ply needs
533is absent. Every cell's expected value carries both sides (`git`: ok or refuse; `ply`: the outcome), and
534`consistent()` checks the rule on every cell: ply never proceeds where git refuses, and refuses where git proceeds only
535for a need it names (`PLY_NEEDS`: v2, the fetch command, sha1).
537**git's reading, from the source** (git v2.50.0):
539- `connect.c` `process_capabilities_v2` reads capability lines up to a flush and dies "expected flush after
540 capabilities" on anything else; over HTTP a pkt after that flush is handed on as the ls-refs response ("invalid
541 ls-refs response"). `server_supports_v2` (presence: `key` or `key=…`), `server_feature_v2` (value: the first `key=…`;
542 a bare `object-format` is no value, so sha1) and `server_supports_feature` (the first `key`/`key=…` line, its value
543 split on whitespace by `parse_feature_value`) all take the **first** matching line. `send_capabilities` dies "unknown
544 object format" on a name `hash_algo_by_name` does not know; `get_remote_refs` dies "server doesn't support 'ls-refs'".
545- `process_ref_v2` splits a record on every space (a doubled space is an empty field, an empty second field a ref
546 named ""), skips an `unborn <name> …` record (it records HEAD's unborn target only for a clone that asked), reads the
547 oid with `parse_oid_hex_algop` (either case), keeps `symref-target:` and `peeled:` and skips every other attribute; a
548 bad peeled oid or a record of fewer than two fields is "invalid ls-refs response". A name listed twice stays twice in
549 the list and `find_ref_by_name` takes the first (observed: `git fetch` of it fetches the first oid).
550- `pkt-line.c` `packet_read_with_status` dies "protocol error: bad line length" once a payload is ≥ its buffer,
551 `packet_buffer[LARGE_PACKET_MAX]`: it reads payloads up to 65519 bytes.
552- `send-pack.c` `send_pack` checks, before sending anything, the repository hash against `object-format` (absent is
553 sha1), then `--atomic` against `atomic`, then push options against `push-options`. `builtin/receive-pack.c` honours a
554 client's `atomic` / `push-options` only when it advertised them, and dies on commands in another hash.
555- `upload-pack.c` `process_args` accepts `no-progress`, `include-tag` and `deepen-relative` unconditionally and `filter`
556 only with `uploadpack.allowFilter`; `fetch-pack.c` warns "filtering not recognized by server, ignoring" and fetches
557 everything.
559**Judgment calls.**
5611. *A plain push to a sha256 repository is `ambiguous`.* ply reads the receive-pack advertisement only when the push
562 needs a capability (atomic, push options); a plain push saves that round trip, receive-pack dies reading the sha1
563 commands and writes no report. Every ply flow reads ls-refs first, which refuses a sha256 listing as `unsupported`.
5642. *A filter the server cannot honour is refused* (`protocol`: upload-pack dies on the unexpected `filter` line and the
565 stream ends without its flush), where git warns and fetches everything: `fetchObject`'s bounded memory rests on the
566 filter it asked for.
5673. *v0 / v1 servers, a server without `fetch`, and sha256* are `unsupported` though `git ls-remote` proceeds: ply is
568 v2-only, every ply read is ls-refs then fetch, and ply is sha1-only.
5694. *Precedence among refusals* in `discover()`: the pkt framing, the protocol, the advertisement's framing, ls-refs and
570 fetch present, the object format. git reads the object format only when it sends ls-refs, but every cell where the
571 orders differ is a refusal on both sides.
573**Found** (each a cell class that disagreed with git on train/1, 77eb2c0; all fixed here):
575| # | where | train/1 | git | now |
576|---|---|---|---|---|
577| 1 | discover: a capability listed twice | the last line wins (sha1 after sha256 proceeds; sha256 after sha1 refuses) | the first wins | the first wins |
578| 2 | discover: `object-format` with no `=` | `unsupported` | sha1, proceeds | sha1 |
579| 3 | discover: no flush, or a delim, after the capabilities | proceeds | "expected flush after capabilities" | `protocol` |
580| 4 | discover: a pkt after the capabilities' flush | read as a capability, proceeds | refuses | `protocol` |
581| 5 | discover: no `ls-refs` (or no `fetch`) | proceeds | "server doesn't support 'ls-refs'" | `unsupported` |
582| 6 | discover: `ERR` as the first line | `unsupported` | "remote error" | `remote_error` |
583| 7 | every pkt-line reader: a payload of 65520–65531 bytes | accepted | "bad line length" | `protocol` |
584| 8 | ls-refs: an `unborn …` record | `protocol` | skipped | skipped |
585| 9 | ls-refs: an upper-case oid or peeled oid | `protocol` | accepted | accepted, kept lower-case |
586| 10 | ls-refs: an empty name (`<oid> `, `<oid> <name>`) | `protocol` | a ref named "" | a ref named "" |
587| 11 | ls-refs: a name listed twice | the last listing | the first | the first |
588| 12 | push: `atomic` to a server that does not advertise it | sent; receive-pack ignored it and the refs landed one by one; `landed` | refuses before sending | `unsupported` before sending |
589| 13 | push: atomic or push options to a sha256 repository | advertisement read, hash ignored, pushed: `ambiguous` | refuses before sending | `unsupported` before sending |
591The request decision found nothing: for each of `no-progress`, its absence, `include-tag`, `deepen-relative` and
592`filter`, ply's request lines equal git's own request for the same fetch and upload-pack invokes pack-objects with the
593same argv and stdin.
595**Enumeration.** `test/space/advertisement.test.js` runs every caps and refs cell through ply's real path
596(`createTransport` with an in-process fetch serving the rendered bytes) and compares the table. Observed: a synthetic
597smart-HTTP server serves each observed cell's advertisement and ls-refs response and forwards fetch requests to `git
598http-backend`; `git ls-remote` judges every caps cell within one deviation of git's default advertisement and every refs
599cell, `git fetch` the fetch-feature cells (which features git uses, read from its own requests), `git push` every push
600cell against receive-pack configured per cell, and `git fetch` / `git clone` each request cell (its request lines and
601upload-pack's pack-objects invocation, captured by `uploadpack.packObjectsHook`). ply runs over real HTTP against the
602same server. Six real http-backend configurations (default, `uploadpack.allowFilter=false`, `allowRefInWant` +
603`allowSidebandAll`, `lsrefs.unborn=ignore`, `transfer.advertiseSID`, a sha256 repository) advertise exactly what the
604renderer writes for their cell. `ADV_SPACE_SRC=<dir>` runs the space against another copy of `src/`.
606<!-- advertisement: generated by scripts/space-md.mjs; do not edit by hand -->
608### Axes (tagged unions)
610**caps protocol** (8) — `v2`, `v0`, `v1`, `err`, `v2service`, `serviceNoFlush`, `html`, `reset`; only `v2` carries the capability axes
612**caps (v2)**
614- `agent` (3) — the agent capability: `present`, `absent`, `empty`
615- `objectFormat` (6) — object-format, read by send_capabilities with server_feature_v2 (needs `=`): `sha1`, `absent`, `sha256`, `unknown`, `bare`, `empty`
616- `fetch` (33) — the fetch command and its features: `absent`, `features[]`, `features[shallow wait-for-done filter ref-in-want sideband-all]` (… every subset of the five features: 32 + absent)
617- `lsRefs` (3) — the ls-refs command: `unborn`, `plain`, `absent`
618- `serverOption` (2) — server-option: `present`, `absent`
619- `sessionId` (2) — session-id: `absent`, `present`
620- `malformed` (9) — one malformation of the advertisement: `none`, `noLF`, `unknownCap`, `duplicate`, `longMax`, `longOver`, `noFlush`, `delim`, `trailing`
622**refs**
624- `record` (18) — one record of the listing, added to or changed in HEAD (symref), main, a tag (peeled): `plain`, `unknownAttr`, `unbornHead`, `unbornOther`, `unbornOnly`, `emptySymref`, `emptyPeeled`, `badPeeled`, `upperOid`, `upperPeeled`, `emptyName`, `doubleSpace`, `oidOnly`, `badOid`, `sha256`, `duplicate`, `capsName`, `err`
625- `eol` (2) — line ends: `lf`, `none`
626- `framing` (6) — the end of the listing: `flush`, `noFlush`, `delim`, `trailing`, `longMax`, `longOver`
628**push**
630- `request` (4) — what the push asks for: `none`, `atomic`, `options`, `both`
631- `atomic` (2) — receive.advertiseAtomic: `on`, `off`
632- `options` (2) — receive.advertisePushOptions: `off`, `on`
633- `format` (2) — the server repository's hash: `sha1`, `sha256`
635**request**
637- `flag` (5) — one fetch argument ply can send (fetch.js fetchBody): `noProgress`, `progress`, `includeTag`, `deepenRelative`, `filter`
638- `server` (2) — uploadpack.allowFilter: `filterOn`, `filterOff`
640### Cells
642| decision | cells | observed from git | derived |
643|---|---:|---:|---:|
644| caps | 64,159 | 59 | 64,100 |
645| refs | 216 | 216 | 0 |
646| push | 32 | 32 | 0 |
647| request | 10 | 10 | 0 |
648| **all** | **64,417** | **317** | **64,100** |
650<!-- advertisement: end generated -->
652## Push ng reasons
654The space of git's receive-pack rejection reasons (test/space/push-ng.space.js): every reason git v2.50.0 can write × the failing command's shape × atomic × refs. Each reason's class is data, justified by what a caller can safely do next; the report git writes for each cell is derived from receive-pack.c and checked byte for byte against real git where git can be made to write it (test/space/push-ng.observed.js).
656<!-- push-ng: generated by test/space/push-ng.test.js (PUSH_NG_WRITE=1); do not edit by hand -->
658Axes: reason(42) × command(8) × atomic(2) × refs(3) × era(2) = 4032 raw; 1057 cells after the impossible ones (192: the reason is written only by the other execute_commands_* (atomic-only or non-atomic-only); 1488: git does not write the reason for this command shape (REASONS[].commands; `gone` is enumerated only with the transaction's own failures, where it changes the text); 176: three commands cannot all carry the reason (REASONS[].three); 20: an aliased update needs a second command (the symref's target); 72: a push whose every command deletes sends no pack: no unpack, nothing to migrate; 1027: the batched transaction changes only the non-atomic commit failure: every other report is the same on both eras, enumerated once (v2.50)).
660Observable from real git: **791** cells (git's report byte for byte = the derived one, ply's outcome = the table's, refs agree), each on the git of its era: v2.50 cells on git 2.50 (a laptop), v2.51+ cells on git >= 2.51 (CI: 2.56); a run observes its own era's cells and derives the rest. Derived from receive-pack.c only: **266** (on a run as root, the two permission recipes are derived too).
662| reason (receive-pack.c line) | class | ply outcomes over its cells | cells (observed) | what a caller can safely do next |
663|---|---|---|---|---|
664| `eof before pack header was fully read` (2201) | unpack | rejected(push_rejected) | 38 (38) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server |
665| `protocol error (pack signature mismatch detected)` (2204) | unpack | rejected(push_rejected) | 38 (38) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server |
666| `protocol error (pack version unsupported)` (2207) | unpack | rejected(push_rejected) | 38 (38) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server |
667| `unknown error in parse_pack_header` (2210) | unpack | rejected(push_rejected) | 38 (0) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server *Derived:* parse_pack_header() returns only the three errors above for a header it read; the default case is unreachable. |
668| `unable to create temporary object directory` (2254) | unpack | rejected(push_rejected) | 38 (38) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server |
669| `unpack-objects abnormal exit` (2281) | unpack | rejected(push_rejected) | 38 (38) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server |
670| `index-pack fork failed` (2313) | unpack | rejected(push_rejected) | 38 (0) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server *Derived:* start_command() failing to fork index-pack cannot be arranged from a request. |
671| `index-pack abnormal exit` (2324) | unpack | rejected(push_rejected) | 38 (38) | the pack never entered the repository and no ref was touched: resending the same pack fails the same way; the caller needs a different pack or a repaired server |
672| `unpacker error` (1938) | unpack | — | — (a consequence: rides on other cells) | written on every command exactly when unpack failed (execute_commands): the unpack line carries the cause; nothing moved |
673| `missing necessary objects` (1777) | rejected | ambiguous, partial, rejected(push_rejected) | 36 (36) | the pack does not complete the new commit's history (set_connectivity_errors); the same pack is refused again, so retrying it is futile; a fresh read does not repair a pack |
674| `deny updating a hidden ref` (1825) | rejected | ambiguous, partial, rejected(push_rejected) | 36 (36) | receive.hideRefs covers the ref: the server never lets a client write it, whatever its value |
675| `deny deleting a hidden ref` (1823) | rejected | ambiguous, partial, rejected(push_rejected) | 6 (6) | receive.hideRefs covers the ref: the server never lets a client delete it, whatever its value |
676| `broken symref` (1684) | rejected | ambiguous, partial, rejected(push_rejected) | 36 (36) | the ref is a symbolic ref the server cannot resolve (a loop): no value of the old oid makes it writable; the repository needs repair |
677| `inconsistent aliased update` (1711) | rejected | ambiguous, partial, rejected(push_rejected) | 20 (20) | one push names a symbolic ref and its target with different updates: the request contradicts itself, and resending it is refused again |
678| `shallow update not allowed` (2425) | rejected | ambiguous, partial, rejected(push_rejected) | 36 (36) | the pushed history ends at a shallow boundary the server lacks and receive.shallowUpdate is off: the same history is refused again (ply never sends shallow lines; a git client from a shallow clone does) |
679| `funny refname` (1481) | rejected | preSend(bad_request) | 10 (10) | the server refuses the ref name itself (check_refname_format(name + 5), one level allowed only for a delete): no retry can succeed, so ply refuses the push before sending a byte (validatePushRef, #73; every name checked against git in test/space/refname.test.js); git's report is still observed byte for byte |
680| `branch is currently checked out` (1501) | rejected | partial, rejected(push_rejected) | 28 (28) | receive.denyCurrentBranch refuses the non-bare repository's checked-out branch, whatever its value |
681| `bad pack` (1515) | rejected | partial, rejected(push_rejected) | 36 (36) | the new object is not in the repository after unpack (only with the connectivity check skipped): the same pack fails again |
682| `deletion prohibited` (1522) | rejected | partial, rejected(push_rejected) | 6 (6) | receive.denyDeletes: branch deletion is off on this server |
683| `deletion of the current branch prohibited` (1539) | rejected | partial, rejected(push_rejected) | 4 (4) | receive.denyDeleteCurrent refuses deleting HEAD's branch, whatever its value |
684| `Invalid denyDeleteCurrent setting` (1542) | rejected | partial, rejected(push_rejected) | 4 (0) | a server misconfiguration: nothing a client resends can change it *Derived:* parse_deny_action() maps every config value to a handled deny_action, so the switch's default is unreachable. |
685| `bad ref` (1562) | cas | partial, rejected(cas_conflict) | 6 (6) | receive.denyNonFastForwards could not parse the old oid the command named: the server does not have it, so the ref is not at it (a stale read of a ref that has since been rewritten): a fresh read names an old oid it has (SAFETY.md I31) |
686| `non-fast-forward` (1573) | nff | partial, rejected(not_fast_forward) | 6 (6) | receive.denyNonFastForwards and the new commit does not descend from the old oid the command itself named: that is true of the request whatever the ref's value, so a fresh read of the ref cannot help; only a new commit that descends from it can (it was cas_conflict: rebase's non-fast-forward push looped on it) |
687| `hook declined` (1579) | rejected | partial, rejected(push_rejected) | 42 (42) | the update hook refused the ref: server policy, not a race |
688| `failed to delete` (1606) | rejected | partial, rejected(push_rejected) | 6 (0) | the ref store would not queue the deletion: deterministic for this name *Derived:* ref_transaction_delete() queues a deletion and fails only on a name refname_is_safe() refuses, which check_refname_format (funny refname) refused first. |
689| `shallow error` (1616) | rejected | partial, rejected(push_rejected) | 36 (0) | receive.shallowUpdate is on and the history above the shallow boundary is incomplete (update_shallow_ref): the same pack fails again *Derived:* not arranged: with receive.shallowUpdate=true, a shallow line and a pack lacking a blob above the boundary, git v2.50.0 answered "ok" for one command (the ref moved to a commit whose tree lacks the blob) and, for three, "shallow error" on the first command, then a report without the others' statuses (ply: ambiguous, a missing status). |
690| `failed to update ref` (1627) | cas | partial, rejected(cas_conflict) | 36 (0) | the same text as the commit failure below, so the same class (the report cannot tell them apart) *Derived:* ref_transaction_update() queues an update and fails only on a name check_refname_format refuses, which funny refname refused first. |
691| `Up-to-date check failed` (1376) | rejected | partial, rejected(push_rejected) | 20 (20) | receive.denyCurrentBranch=updateInstead: update-index --refresh failed in the server's worktree (its index is locked); the push is refused until someone changes the server's worktree |
692| `Working directory has unstaged changes` (1388) | rejected | partial, rejected(push_rejected) | 20 (20) | receive.denyCurrentBranch=updateInstead: the server's worktree has unstaged changes; the push is refused until someone changes the server's worktree |
693| `Working directory has staged changes` (1402) | rejected | partial, rejected(push_rejected) | 24 (24) | receive.denyCurrentBranch=updateInstead: the server's worktree has staged changes; the push is refused until someone changes the server's worktree |
694| `Could not update working tree to new HEAD` (1414) | rejected | partial, rejected(push_rejected) | 24 (24) | receive.denyCurrentBranch=updateInstead: read-tree -u -m could not check out the new commit (an untracked file is in the way); the push is refused until someone changes the server's worktree |
695| `push-to-checkout hook declined` (1433) | rejected | partial, rejected(push_rejected) | 24 (24) | receive.denyCurrentBranch=updateInstead: the push-to-checkout hook refused; the push is refused until someone changes the server's worktree |
696| `denyCurrentBranch = updateInstead needs a worktree` (1449) | rejected | partial, rejected(push_rejected) | 24 (0) | a server misconfiguration: nothing a client resends can change it *Derived:* update() sets do_update_worktree only for a worktree that is not bare, so update_worktree() never sees a bare one. |
697| `failed to update ref` (1874, 2nd site) | cas | partial, rejected(cas_conflict), rejected(push_rejected) | 30 (30) | the ref is not at the old oid the command named (a stale read, a create over an existing ref, a concurrent writer holding the lock): a fresh read and a redo can land. Also written for a D/F conflict (create refs/heads/r0/sub beside refs/heads/r0, observed): a fresh retry is safe but cannot land there, and a caller's retry budget bounds it |
698| `atomic transaction failed` (1909) | cas | rejected(cas_conflict) | 15 (15) | an atomic push's single commit failed, which for a stale old oid is git v2.50.0's only report (every ref gets this text, none gets "failed to update ref", observed): the same lost race as above, so a fresh read and a redo can land (it was push_rejected: an atomic CAS loss was never retried) |
699| `atomic push failure` (1886) | innocent | — | — (a consequence: rides on other cells) | an atomic push's other members after one command failed inside update(): nothing moved, and the culprit's reason decides the class |
700| `transaction failed to start` (1864) | rejected | partial, rejected(push_rejected) | 21 (0) | the server could not open a ref transaction: a server fault, and nothing moved *Derived:* ref_store_transaction_begin() cannot fail in git v2.50.0 (refs.c: it only allocates). |
701| `transaction failed to start` (1893, 2nd site) | rejected | rejected(push_rejected) | 21 (0) | the server could not open a ref transaction: a server fault, and nothing moved *Derived:* ref_store_transaction_begin() cannot fail in git v2.50.0 (refs.c: it only allocates). |
702| `pre-receive hook declined` (1987) | rejected | rejected(push_rejected) | 42 (42) | the pre-receive hook refused the push: server policy, not a race |
703| `unable to migrate objects to permanent storage` (2008) | rejected | rejected(push_rejected) | 38 (38) | the server could not move the received objects out of quarantine (a storage fault): nothing moved, and a retry needs the server repaired |
704| `inconsistent push options` (2599) | rejected | rejected(push_rejected) | 42 (0) | the request contradicts its own certificate: resending it is refused again *Derived:* needs a signed push (push-cert) whose push options differ from the request's; ply never sends a push certificate. |
705| `fail to run proc-receive hook` (2027) | ambiguous | ambiguous | 6 (6) | the hook could not be run, or did not finish after it was handed the command: it may have acted on the command (a review created) without saying, and the report cannot tell which; read before redoing |
706| `proc-receive failed to report status` (1103) | ambiguous | ambiguous | 6 (6) | the hook was handed the command and gave no status for it: it may have acted; read before redoing |
707| `failed` (1093) | rejected | ambiguous, partial, rejected(push_rejected) | 6 (6) | the proc-receive hook answered "ng <ref>" with no message: it refused the command, as an update hook does |
709git >= 2.51 batched texts (era v2.51+, the non-atomic commit failure):
711| text | class | what a caller can safely do next |
712|---|---|---|
713| `incorrect old value provided` | cas | REF_TRANSACTION_ERROR_INCORRECT_OLD_VALUE: the ref is not at the old oid the command named: a fresh read and a redo can land |
714| `reference already exists` | cas | REF_TRANSACTION_ERROR_CREATE_EXISTS: a create lost to another writer's create: a fresh read finds the ref and the redo is an update |
715| `reference does not exist` | cas | REF_TRANSACTION_ERROR_NONEXISTENT_REF: the ref was deleted since the read: a fresh read finds it absent (it was push_rejected: git >= 2.51's stale update of a deleted ref was never re-read) |
716| `refname conflict` | rejected | REF_TRANSACTION_ERROR_NAME_CONFLICT: a D/F conflict (refs/heads/r0/sub beside refs/heads/r0): no value of the old oid makes the name free; git >= 2.51 tells it apart from a lost race, so ply need not retry it |
717| `invalid new value provided` | rejected | a batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again |
718| `expected symref but found regular ref` | rejected | a batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again |
719| `reference conflict due to case-insensitive filesystem` | rejected | a batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again |
720| `unknown failure` | rejected | a batched rejection that is not a lost race (a bad new value, a symref expectation, a case-only clash, an unclassified failure): resending is refused again |
722<!-- push-ng: end generated -->
724## Ref names
726The space of ref names a caller can hand ply (test/space/refname.space.js, #73): `refs/` + 1, 2 or 3 components, each one of 16 shapes (`a`, `@`, `@a`, `@{a`, `{a`, `.`, `..`, `.a`, `a.`, `a.lock`, `a.lockb`, `-a`, the empty component, a control character, a space, non-ASCII), 16 + 256 + 4,096 names, plus one name per code point U+0001–U+00FF inside a component (254, LF excluded: it cannot be framed): **4,622 cells**. Every cell asks real git three questions and ply must give git's answer on every one (test/space/refname.test.js):
728| question | git's oracle | ply |
729|---|---|---|
730| format | `git check-ref-format <name>` (refs.c check_refname_format(name, 0)) | `validateRef` |
731| create | a real `git receive-pack` answering a create of the name: `ng <name> funny refname` or not (receive-pack.c update(): check_refname_format(name + 5, 0)) | `validatePushRef(name, false)`; push() refuses before sending |
732| delete | the same for a delete (check_refname_format(name + 5, REFNAME_ALLOW_ONELEVEL)) | `validatePushRef(name, true)` |
734Git v2.50.0 accepts 726 names as refs, 719 for a create and 725 for a delete. The create/delete gap is receive-pack's, not check-ref-format's: `refs/<one level>` (refs/stash is one) is a valid ref and can be deleted by a push but never created or updated, and `refs/@` is a valid ref no push can touch (`@` alone is refused as a whole refname). Before #73 ply validated a push's ref with `validateRef` alone and disagreed with receive-pack on 8 cells, all of them those two shapes; git refused them as `funny refname`.
736## Default depth
738**Decision.** `fetchObject` / `objectAt` asks for one object by id. Which `deepen` goes on the wire, and what happens
739when the server refuses it? (src/fetch.ts `objectAt`: `depth`, `ask`; src/transport.ts `learnShallow`. Space:
740test/space/default-depth.space.js, run by test/space/default-depth.test.js.)
742**Rules** (the owner's; `expected()` is written from these, not from the code):
744- **R1** One object costs one object's worth of pack. A want that is or may be a commit (`expectType` left out, COMMIT
745 or TAG) is sent with `deepen 1` when the server takes shallow requests. A want named a tree or a blob gets none.
746- **R2** A caller's explicit `deepen` is sent as given and always wins (`0`: no `deepen` line).
747- **R3** Without the capability ply behaves as on main, for every refusal shape. A default-depth request (the caller gave
748 no deepen, 1 was sent, `shallow` not yet known for the quirks record) refused with an empty response, an `ERR` line or
749 HTTP 400 reads the advertisement once per quirks record; if `fetch=` lists no `shallow` the want is asked again
750 without `deepen`, once; if it is listed the first error stands. Never when the caller gave `deepen`.
751- **R4** No extra round trip on a success path.
753**git's shape, from the source** (git v2.50.0). `upload-pack.c`: a commit want with no depth is answered with every
754commit reachable from it; `deepen <d>` cuts that at d generations (`shallow.c` `get_shallow_commits`, which peels a tag
755want with `deref_tag` and skips a want that is not a commit). `filter tree:0` drops trees and blobs but not ancestors,
756`blob:none` drops blobs. git's upload-pack always lists `shallow` on `fetch=` (`filter` only with
757`uploadpack.allowFilter`), so a server without `shallow` is not git: the space renders one by taking the word off git's
758own advertisement and refusing or dropping the `deepen` line in front of git's own upload-pack. An argument git does not
759take makes upload-pack die: over smart HTTP that is HTTP 200 with an empty body (the `empty` class).
761**Two things main already did** that the expected values use, and that predate this decision: an empty response on the
762tree:0 path reads the advertisement for `filter` (the no-filter fallback: `filterUnadvertised`), and the single fetch
763(tree:0, filter '') refuses a pack of more than one object for a want not typed COMMIT (`pack_corrupt`; README,
764`fetchObject`). So an annotated tag wanted on the tree:0 path is `pack_corrupt` at depth 1 (the tag and the commit it
765peels to: two objects) as it was without a depth (the tag and the history).
767**Outside the space: the server's `filter` support.** Every server in the space takes the filter its path sends. What
768a server does with `filter` is main's decision, made after this one and by the same lines: the request asked again
769without `deepen` is main's request, and on the tree:0 path its answer is read as main reads it (no `filter` on the
770advertisement just read: the unfiltered pack; `tree:0` refused: `blob:none`; an empty response: the advertisement). It
771is not an axis here because it does not change which `deepen` is sent or whether the want is asked again, only which
772filter the re-ask carries; as an axis it would multiply the 3 tree:0 cells of each refusal by servers the filter
773fallback's own tests already enumerate. The product that does matter (deepen refused as `ERR`, 400 or empty × a server
774that lists `filter` and takes only `blob:none`, or lists none and dies on one; neither lists `shallow`) is 6 rows in
775test/fetchobject-deepen-refusal.test.js, each against git with main's outcome as the expected value.
777**Judgment calls.**
7791. *A stale `listed`.* A record taught that the server lists `shallow`, on a server that no longer does, refused with
780 an `ERR` line or HTTP 400 (or with an empty response on a path that does not read the advertisement): the first
781 error stands (33 cells: 3 types × (4 + 4 + 3 paths)). R3's trigger needs `shallow` not yet known, and main would
782 have succeeded here; the record is corrected by the next advertisement read (`discover()`). On the tree:0 path an
783 empty response reads the advertisement anyway (main's filter fallback), and what it says about `shallow` is
784 believed: the want is asked again without `deepen` (3 cells).
7852. *A stale `unlisted`.* A record taught that the server lists no `shallow`, on a server that now does: no `deepen` is
786 sent and the answer is the history, held to the pack limits. That is main's request; R1 says "when the server takes
787 shallow requests" and the record says it does not. Corrected by the next advertisement read.
7883. *`deepen` ignored.* The server answers with the history as if the line were not there. One request, `ok` (or the
789 pack limits' refusal): ply learns it only from the pack, and R4 forbids a second request on a success path.
7904. *The caller's depth refused* (R2). The error stands in every shape, with no re-ask; on the tree:0 path an empty
791 response still costs main's advertisement read for `filter`.
793<!-- default-depth: generated by test/space/default-depth.test.js (DEFAULT_DEPTH_WRITE=1); do not edit by hand -->
795### Axes
797**asked** — the caller's deepen (3)
799- `none` — left out: the default depth applies (R1)
800- `0` — explicit 0: no `deepen` line, the whole history (R2)
801- `2` — explicit n: `deepen 2`, sent as given (R2)
803**expectType** — the type the caller names; the want is an object of that type (5)
805- `none` — untyped: may be a commit (the want is the tip commit)
806- `COMMIT` — a commit
807- `TAG` — may peel to a commit (the want is an annotated tag of the tip)
808- `TREE` — no history is reachable from a tree: no default depth
809- `BLOB` — nor from a blob
811**knowledge** — what the quirks record was taught about `shallow` before the call (by discover()) (3)
813- `unlearned` — no advertisement read for this record
814- `listed` — an advertisement that listed `shallow`
815- `unlisted` — an advertisement that did not
817**advertised** — whether the server's fetch= line lists `shallow` during the call (differs from a learned knowledge when the server changed: stored state is untrusted) (2)
819- `yes` — git, GitHub, GitLab, Codeberg, Artifacts
820- `no` — a server without shallow fetches
822**refusal** — what the server does with a request that carries `deepen` (5)
824- `none` — takes it: git
825- `empty` — HTTP 200 with an empty body: git upload-pack dying on an argument it does not take
826- `err` — an ERR pkt-line (remote_error)
827- `400` — HTTP 400: how Artifacts refuses an argument it does not take
828- `ignored` — drops the line and answers as if it were not there
830**path** — objectAt's request path (4)
832- `tree:0` — the single fetch, filter tree:0 (quirks.treeFilter tree:0)
833- `blob:none` — the wide fetch on a record that learned blob:none (Artifacts)
834- `unfiltered` — the wide fetch on a record that learned no filter (the server lists no `filter`)
835- `filter ''` — the single fetch with the caller's filter ''
837### Product
8393 × 5 × 3 × 2 × 5 × 4 = **1,800 cells** (asked × expectType × knowledge × advertised × refusal × path), none removed.
841| requests, in order → outcome | cells |
842|---|---:|
843| `POST - → ok` | 740 |
844| `POST - → pack_corrupt` | 220 |
845| `POST 2 → ok` | 180 |
846| `POST 2 → http` | 120 |
847| `POST 2 → remote_error` | 120 |
848| `POST 2 → protocol` | 90 |
849| `POST 1 → ok` | 68 |
850| `POST 2 → pack_corrupt` | 60 |
851| `POST 2, GET → protocol` | 30 |
852| `POST 1 → pack_corrupt` | 28 |
853| `POST 1, GET, POST - → ok` | 25 |
854| `POST 1 → http` | 24 |
855| `POST 1 → remote_error` | 24 |
856| `POST 1 → protocol` | 18 |
857| `POST 1, GET → protocol` | 15 |
858| `POST 1, GET, POST - → pack_corrupt` | 14 |
859| `POST 1, GET → http` | 12 |
860| `POST 1, GET → remote_error` | 12 |
862<!-- default-depth: end generated -->
864## SSH
866SSH transport removed 2026-10-31; history on branch archive/ssh.
Diagnostics4 git calls · 229 ms
CallStatusSizeTime0229 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
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 · 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 · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=218
git.response.bytes=38434
git.response.cache=HIT
git.response.duration_ms=3
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
fetch20024 KiB223 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=24593
git.response.cache=MISS
git.response.duration_ms=223
git.fetch.wants=e9bc26e322217640a8fb517955d0c981f738876c
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=24593
git.pkt.payload.max=24572
git.sideband.band1.bytes=24571
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
a5e2ca947cb14b67
Request
1495714d…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format