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:
| outcome | meaning | code (retry) |
|---|---|---|
landed | every commanded ref was updated | — (resolves) |
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) |
partial | a non-atomic multi-ref push: the refs in landed were updated, those in rejected were not | push_partial (no) |
ambiguous | the refs may or may not have moved: read them back first | ambiguous (read) |
preSend | ply refused before sending a byte; definite: nothing changed | bad_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.creport()writesunpack <status>(okwhenunpack_statusis NULL), then for each command in request orderok <ref>orng <ref> <error_string>, then a flush;report_v2()writes the same and addsoption refname|old-oid|new-oid|forced-updatelines after anokonly for a command a proc-receive hook reported (cmd->report), repeatingok <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 commandunpacker errorand returns; nothing else sets that string.cmd_receive_pack()skips unpack entirely whendelete_only(), so a delete-only push always reportsunpack ok.execute_commands_atomic(): a failure inside the transaction marks every other commandatomic push failure(oratomic 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 packets0005\1as keepalives while hooks run (copy_to_sideband;use_keepaliveis KEEPALIVE_ALWAYS fromexecute_commandson, 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 orERR. send-pack.creceive_unpack_status()/receive_status()andsideband.cdemultiplex_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 anERRpacket (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):
- Atomic split. An atomic push answered with some
okand somengisambiguous, 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. - Option lines. An
okfollowed byoptionlines (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 isambiguous. Under v1 they are not git's at all. - Unknown unpack failure text. A non-
okunpack status that is not one of git's eight strings isambiguous, even with every refng 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>, thenng <ref> <s>for each ref) ispush_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 beok(the boundary enumeration, unchanged). No ref lines, a ref that does not echo the status, anokbeside it, or a delete-only push stayambiguous. Before this, such a report wasambiguousand a single-ref update was read back: an invalid pack whose ref had not moved came backcas_conflict, and a caller retried a pack that cannot land. - Anything after the final flush (a second report, a transport error) is
ambiguous, although the report before it was complete. - A connection failure before any response byte is
ambiguouseven 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. - 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.
| cells | table → main | cause |
|---|---|---|
| 276,312 | ambiguous → limit_exceeded (retry: no) | every flood cell: a report-line limit hit after the send kept its pre-send code |
| 19,456 + 1,152 + 192 | ambiguous → rejected / cas_conflict / landed | plain stream with no final flush: main never required the report's flush |
| 14,592 + 864 + 144 | ambiguous → rejected / cas_conflict / landed | side-band report without its own flush inside band 1 |
| 19,456 + 1,152 + 192 | ambiguous → rejected / cas_conflict / landed | a second flush after the final flush |
| 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 |
| 14,592 + 864 + 144 | ambiguous → rejected / cas_conflict / landed | an ERR packet before the report (main skipped the line), with any delivery |
| 12,880 | ambiguous → push_rejected | unpack near-miss (ok*): issue #33, the ref had moved |
| 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 |
| 2,688 + 280 + 168 | ambiguous → rejected / cas_conflict / landed | option lines after ok (v1, or v2 proc-receive) |
| 2,128 | ambiguous → push_rejected | ng <ref> unpacker error beside unpack ok, or beside other statuses |
| 560 + 280 | partial → push_rejected / cas_conflict | non-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 elseprogress— 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 3band3After— band 3 after the report, before the outer flusherrPkt— 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 updateddropAfterPack— the connection fails after the pack, before any response byte: the server may have updated the refsrefused(what="ref") — ply refuses before sending: validateRef refuses the ref namerefused(what="oid") — ply refuses before sending: an old/new oid that is not 40-hexrefused(what="maxRefs") — ply refuses before sending: more commands than limits.maxRefsrefused(what="packBytes") — ply refuses before sending: the built pack exceeds limits.maxPackBytesrefused(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 wiresideband— 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 streamband1Split— one band-1 packet per inner pkt: send_sideband() chunks at LARGE_PACKET_MAX; the client reassembles band 1 as a streamnoFinalFlush— 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 presentcutAfterUnpack— the stream ends cleanly after the unpack line (a cut at a pkt boundary)cutMidPkt— the stream ends inside the last data pkttrailingPkt— a second copy of the report after the final flushthrowAfter— every byte, then the transport fails (connection reset after the flush)flood— 16 extra report lines: exceeds the client's report-line captrailingFlush— a second flush after the final flushband1Trailing(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 flushwrongBand(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 differthree— 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 refon— 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, flushv2— report_v2() without proc-receive: byte-identical to report()v2Options— report_v2(): "option forced-update" after each ok, written only for proc-receive reportsv1Options— 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 NULLgitError(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 itabsent— no unpack line: send-pack.c receive_unpack_status failsunreadable— status bytes 0xff 0xfe: not textnearMiss(status="ok*") — one flip from "ok" (issue #33): neither "ok" nor a git failure stringduplicated— 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 NULLngCas(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 failedngEcho(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 refusalmissing— no status line for a commanded ref: report() writes one per command, so never gitduplicate— 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 hasstatusmixed— at ∈ {0, 1, 2} × odd ∈ the 11statustags: 33 variants (the odd ref's status overridesstatusfor refat)
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).
| removed | why | raw cells |
|---|---|---|
| impossible | plain framing has no band 1, 2 or 3 (use_sideband=0: hook output goes to stderr) | 7,791,168 |
| impossible | a delete-only push sends no pack, so it cannot be cut inside or after one, nor refused for its size | 188,496 |
| impossible | one ref cannot be mixed | 3,821,664 |
| impossible | the odd ref index is beyond the commanded refs | 1,273,888 |
| impossible | a mixed report whose odd status equals the common status is the uniform cell | 579,040 |
| 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 |
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 offclean/plain/complete/one/withPack/on/v1/ok/ok/uniform— all ok one/plain/v1/atomic onclean/plain/complete/one/withPack/off/v2/ok/ok/uniform— all ok one/plain/v2/atomic offclean/plain/complete/one/withPack/on/v2/ok/ok/uniform— all ok one/plain/v2/atomic onclean/sideband/complete/one/withPack/off/v1/ok/ok/uniform— all ok one/sideband/v1/atomic offclean/sideband/complete/one/withPack/on/v1/ok/ok/uniform— all ok one/sideband/v1/atomic onclean/sideband/complete/one/withPack/off/v2/ok/ok/uniform— all ok one/sideband/v2/atomic offclean/sideband/complete/one/withPack/on/v2/ok/ok/uniform— all ok one/sideband/v2/atomic onclean/plain/complete/two/withPack/off/v1/ok/ok/uniform— all ok two/plain/v1/atomic offclean/plain/complete/two/withPack/on/v1/ok/ok/uniform— all ok two/plain/v1/atomic onclean/plain/complete/two/withPack/off/v2/ok/ok/uniform— all ok two/plain/v2/atomic offclean/plain/complete/two/withPack/on/v2/ok/ok/uniform— all ok two/plain/v2/atomic onclean/sideband/complete/two/withPack/off/v1/ok/ok/uniform— all ok two/sideband/v1/atomic offclean/sideband/complete/two/withPack/on/v1/ok/ok/uniform— all ok two/sideband/v1/atomic onclean/sideband/complete/two/withPack/off/v2/ok/ok/uniform— all ok two/sideband/v2/atomic offclean/sideband/complete/two/withPack/on/v2/ok/ok/uniform— all ok two/sideband/v2/atomic onclean/plain/complete/three/withPack/off/v1/ok/ok/uniform— all ok three/plain/v1/atomic offclean/plain/complete/three/withPack/on/v1/ok/ok/uniform— all ok three/plain/v1/atomic onclean/plain/complete/three/withPack/off/v2/ok/ok/uniform— all ok three/plain/v2/atomic offclean/plain/complete/three/withPack/on/v2/ok/ok/uniform— all ok three/plain/v2/atomic onclean/sideband/complete/three/withPack/off/v1/ok/ok/uniform— all ok three/sideband/v1/atomic offclean/sideband/complete/three/withPack/on/v1/ok/ok/uniform— all ok three/sideband/v1/atomic onclean/sideband/complete/three/withPack/off/v2/ok/ok/uniform— all ok three/sideband/v2/atomic offclean/sideband/complete/three/withPack/on/v2/ok/ok/uniform— all ok three/sideband/v2/atomic onclean/plain/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 two/plain/v1; hidden ref, non-atomic plainclean/plain/complete/two/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic two/plain/v1clean/plain/complete/two/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 two/plain/v2clean/plain/complete/two/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic two/plain/v2progress/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 two/sideband/v1progress/sideband/complete/two/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic two/sideband/v1progress/sideband/complete/two/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 two/sideband/v2progress/sideband/complete/two/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic two/sideband/v2clean/plain/complete/three/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 three/plain/v1clean/plain/complete/three/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic three/plain/v1clean/plain/complete/three/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 three/plain/v2clean/plain/complete/three/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic three/plain/v2progress/sideband/complete/three/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 three/sideband/v1progress/sideband/complete/three/withPack/on/v1/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic three/sideband/v1progress/sideband/complete/three/withPack/off/v2/ok/ok/mixed(at=1,odd=ngHook)— update hook refuses r1 three/sideband/v2progress/sideband/complete/three/withPack/on/v2/ok/ngAtomic(reason=atomic push failure)/mixed(at=1,odd=ngHook)— update hook refuses r1, atomic three/sideband/v2clean/plain/complete/two/withPack/off/v1/ok/ngHook(reason=hook declined)/uniform— pre-receive refuses plainclean/plain/complete/one/withPack/off/v1/ok/ngCas(reason=failed to update ref)/uniform— stale old oid plainclean/plain/complete/two/withPack/off/v1/ok/ok/mixed(at=0,odd=ngCas)— stale old oid, two refs plainclean/plain/complete/one/withPack/off/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform— corrupted pack plainclean/plain/complete/two/withPack/on/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform— corrupted pack, two refs, atomic plainclean/plain/complete/one/deleteOnly/off/v1/ok/ok/uniform— delete plain; delete with an unknown old oid plainclean/plain/complete/two/deleteOnly/off/v1/ok/ok/mixed(at=1,odd=ngCas)— delete two, one stale plainclean/plain/complete/two/withPack/on/v1/ok/ok/mixed(at=1,odd=ngHook)— hidden ref, atomic plainprogress/sideband/complete/two/withPack/off/v1/ok/ngHook(reason=hook declined)/uniform— pre-receive refuses sidebandprogress/sideband/complete/one/withPack/off/v1/ok/ngCas(reason=failed to update ref)/uniform— stale old oid sidebandprogress/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=0,odd=ngCas)— stale old oid, two refs sidebandprogress/sideband/complete/one/withPack/off/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform— corrupted pack sidebandprogress/sideband/complete/two/withPack/on/v1/gitError(status=unpack-objects abnormal exit)/ngUnpacker(reason=unpacker error)/uniform— corrupted pack, two refs, atomic sidebandclean/sideband/complete/one/deleteOnly/off/v1/ok/ok/uniform— delete sidebandprogress/sideband/complete/two/deleteOnly/off/v1/ok/ok/mixed(at=1,odd=ngCas)— delete two, one stale sidebandprogress/sideband/complete/one/deleteOnly/off/v1/ok/ok/uniform— delete with an unknown old oid sidebandclean/sideband/complete/two/withPack/off/v1/ok/ok/mixed(at=1,odd=ngHook)— hidden ref, non-atomic sidebandclean/sideband/complete/two/withPack/on/v1/ok/ok/mixed(at=1,odd=ngHook)— hidden ref, atomic sidebandprogress/sideband/complete/two/withPack/off/v1/ok/ok/uniform— noisy hooks, band 2 before and after the reportkeepalive/sideband/complete/one/withPack/off/v1/ok/ok/uniform— slow hooks: keepalives before and after the reportdropBeforePack/plain/complete/one/withPack/off/v1/ok/ok/uniform— connection fails: dropBeforePackdropMidPack/plain/complete/one/withPack/off/v1/ok/ok/uniform— connection fails: dropMidPackdropAfterPack/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 intand stores auint16_t, so only the low 16 bits exist:7100644and300644are 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 leading0is 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.
.gitis 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 namegit~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.
.gitmodulesin any HFS/NTFS spelling (gitmod~1, the fallbackgi7eba~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..gitattributeslikewise (gitattributesBlob, gitattributesMissing; but as a symlink only gitattributesSymlink, INFO)..gitignoreand.mailmapas 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-treeunder 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.
- 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 cloneand checkoutDir of 100600, 100664, 100700, 7100644, 40755, 1 and 140000 arediff -ridentical). - 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).
- 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.
- .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 againstgit check-attr --sourceat 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). - 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/1 | table → ply | cause |
|---|---|---|
| 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 |
| 72 / 72 | accept → refuse | git~2 refused as .git (only git~1 is .git's short name) |
| 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 |
| 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) |
| 50 / 0 | names | main: 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 treeplain100644 m— an ordinary siblingnullSha1100644 n— is_null_oidfullPathname100644 m/n— strchr(name, '/')emptyName100644— an empty name: badTree (decode_tree_entry)malformedMode10x644 m— parse_mode: a non-octal digit, "malformed mode in tree entry": badTreehasDot100644 .— "."hasDotdot100644 ..— ".."hasDotgit100644 .git— is_hfs_dotgit || is_ntfs_dotgitzeroPaddedFilemode0100644 m— the mode's first byte is '0'badFilemode100664 m— S_IFREG|0664 under --strictgitmodulesSymlink120000 .gitmodules— S_ISLNK on a .gitmodulesgitmodulesBlob40000 .gitmodules— a .gitmodules that is a tree: fsck_finish "non-blob found at .gitmodules"gitattributesSymlink120000 .gitattributes— S_ISLNK on a .gitattributes (INFO)gitattributesMissing160000 .gitattributes— a .gitattributes gitlink: fsck_finish cannot read the blobgitignoreSymlink120000 .gitignore— S_ISLNK on a .gitignore (INFO)mailmapSymlink120000 .mailmap— S_ISLNK on a .mailmap (INFO)largePathname100644 m×4097— tree_entry_len > 4096duplicateEntries— 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)
blob100644— S_IFREG|0644: standardexec100755— S_IFREG|0755: standardsymlink120000— S_IFLNK: standardtree40000— S_IFDIR: standardgitlink160000— S_IFGITLINK: standardgroup100664— S_IFREG|0664: "we had a few of these early on"; badFilemode only under --strictprivate100600— S_IFREG|0600: badFilemode (INFO); canon_mode 100644dir75540755— S_IFDIR|0755: badFilemode; S_ISDIR, so it sorts and reads as a treegitlinkPerm160644— S_IFGITLINK|0644: badFilemode; canon_mode 160000zeroPadded0100644— a leading 0: zeroPaddedFilemode (WARN), and the value is still 100644zeroPaddedTree040000— the zero-padded tree mode old tools wrote: zeroPaddedFilemodetruncated7100644— parse_mode keeps 16 bits: 07100644 & 0xffff is 0100644, a standard mode (no report at all)unknownType1— type bits 0: badFilemode; canon_mode makes it a gitlinkallBits777777— 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 namedot"." — hasDotdotdot".." — hasDotdotempty"" — decode_tree_entry: "empty filename in tree entry", so badTree (emptyName is unreachable)slash"a/b" — fullPathnamedotgit".git" — hasDotgitDOTGIT".GIT" — is_ntfs_dotgit and is_hfs_dotgit fold ASCII caseDotGit".Git" — mixed caseshort1"git~1" — is_ntfs_dotgit: the 8.3 short name of .gitSHORT1"GIT~1" — the short name, upper caseshort2"git~2" — not .git: git guarantees .git takes ~1 (path.c), so ~2 is an ordinary nameshort10"git~10" — git~1 followed by a digit: an ordinary nametrailDot".git." — NTFS trims trailing dotstrailSpace".git " — NTFS trims trailing spacestrailMixed".git. ." — dots and spaces, any mixstream".git:x" — an NTFS alternate data stream of .gitshortStream"git~1:x" — a stream of the short namedotgitx".gitx" — a longer name: ordinaryhfsZwnj".g\xe2\x80\x8cit" — HFS+ ignores U+200ChfsBom"\xef\xbb\xbf.git" — HFS+ ignores U+FEFF, also in fronthfsLrm".git\xe2\x80\x8e" — HFS+ ignores U+200E, also at the endhfsBadTail".git\xff" — next_hfs_char reads an invalid sequence as the end of the name: .githfsSurrogate".git\xed\xa0\x80" — a UTF-8-encoded surrogate is invalid to pick_one_utf8_char: the end, so .gitbadLead"\xff.git" — invalid UTF-8 before the dot: not .git to HFS, not to NTFSoverlongDot"\xc0\xaegit" — an overlong "." is invalid, never a dotbackslash"a.git" — fsck_tree reads a backslash as a separator (is_ntfs_dotgit after it) on every platformbackslashShort"a\git~1" — the short name after a backslashbackslashDotdot"..\x" — fsck checks only .git after a backslash: accepted, and..on Windowsgitmodules".gitmodules" — gitmodulesSymlink as a symlink; collected for fsck_finish otherwiseGITMODULES".GITMODULES" — casegitmodulesTrail".gitmodules ." — is_ntfs_dot_generic: trailing spaces and dotsgitmodulesStream".gitmodules:x" — a streamgitmodulesShort"gitmod~1" — the 6-character short name, ~1 to ~4gitmodulesShort5"gitmod~5" — ~5 is past the regular short names, and gitmod is not the fallback prefix: ordinarygitmodulesFallback"GI7EBA~1" — the fallback short name (hash prefix gi7eba)gitmodulesFallback9"gi7eba~9" — the fallback allows ~1 to ~9tildeDigits"~1234567" — is_ntfs_dot_generic's fallback loop takes a leading ~ and digits as every dotfile's short namegitmodulesHfs".gitmodu\xe2\x80\x8dles" — HFS+ ignorable insidegitmodulesBackslash"a.gitmodules" — is_ntfs_dotgitmodules after a backslashgitattributes".gitattributes" — gitattributesSymlink (INFO) as a symlinkgitattributesShort"gi7d29~1" — its fallback short namegitattributesBackslash"a.gitattributes" — fsck_tree checks only .gitmodules after a backslashgitignore".gitignore" — gitignoreSymlink (INFO)gitignoreShort"gi250a~1" — its fallback short namemailmap".mailmap" — mailmapSymlink (INFO)mailmapShort"maba30~1" — its fallback short namelong4096"l×4096" — max_tree_entry_len: 4096 bytes is allowedlong4097"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 entrytriggerFirst— 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):
| msgId | cells |
|---|---|
badFilemode (warning) | 10,058 |
treeNotSorted | 9,744 |
hasDotgit | 9,184 |
zeroPaddedFilemode | 4,432 |
badTree | 3,150 |
gitmodulesBlob | 2,320 |
fullPathname | 1,792 |
hasDot | 1,792 |
hasDotdot | 1,792 |
largePathname | 1,792 |
gitattributesMissing | 1,726 |
gitmodulesSymlink | 1,660 |
duplicateEntries | 1,568 |
gitattributesSymlink (warning) | 1,429 |
gitignoreSymlink (warning) | 1,429 |
mailmapSymlink (warning) | 1,429 |
gitmodulesMissing | 1,400 |
nullSha1 | 1,330 |
gitattributesBlob | 315 |
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, asgit ls-treeprints itgitattributesSymlink→ 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 doesgitignoreSymlink→ accept: ply never reads .gitignoremailmapSymlink→ accept: ply never reads .mailmap
Advertisement
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):
| decision | ply entry point | outcome |
|---|---|---|
caps | discover() | ok with the parsed capabilities, or unsupported / protocol / remote_error / not_git / network |
refs | lsRefs() | ok with the refs and HEAD's target, or protocol / unsupported / remote_error |
push | GitHttp.push (pushWithOptions) | landed, or unsupported before a byte of the push is sent, or ambiguous (push-outcome's rule) |
request | fetchPack() | 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.cprocess_capabilities_v2reads 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:keyorkey=…),server_feature_v2(value: the firstkey=…; a bareobject-formatis no value, so sha1) andserver_supports_feature(the firstkey/key=…line, its value split on whitespace byparse_feature_value) all take the first matching line.send_capabilitiesdies "unknown object format" on a namehash_algo_by_namedoes not know;get_remote_refsdies "server doesn't support 'ls-refs'".process_ref_v2splits a record on every space (a doubled space is an empty field, an empty second field a ref named ""), skips anunborn <name> …record (it records HEAD's unborn target only for a clone that asked), reads the oid withparse_oid_hex_algop(either case), keepssymref-target:andpeeled: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 andfind_ref_by_nametakes the first (observed:git fetchof it fetches the first oid).pkt-line.cpacket_read_with_statusdies "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.csend_packchecks, before sending anything, the repository hash againstobject-format(absent is sha1), then--atomicagainstatomic, then push options againstpush-options.builtin/receive-pack.chonours a client'satomic/push-optionsonly when it advertised them, and dies on commands in another hash.upload-pack.cprocess_argsacceptsno-progress,include-taganddeepen-relativeunconditionally andfilteronly withuploadpack.allowFilter;fetch-pack.cwarns "filtering not recognized by server, ignoring" and fetches everything.
Judgment calls.
- 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 asunsupported. - A filter the server cannot honour is refused (
protocol: upload-pack dies on the unexpectedfilterline and the stream ends without its flush), where git warns and fetches everything:fetchObject's bounded memory rests on the filter it asked for. - v0 / v1 servers, a server without
fetch, and sha256 areunsupportedthoughgit ls-remoteproceeds: ply is v2-only, every ply read is ls-refs then fetch, and ply is sha1-only. - 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):
| # | where | train/1 | git | now |
|---|---|---|---|---|
| 1 | discover: a capability listed twice | the last line wins (sha1 after sha256 proceeds; sha256 after sha1 refuses) | the first wins | the first wins |
| 2 | discover: object-format with no = | unsupported | sha1, proceeds | sha1 |
| 3 | discover: no flush, or a delim, after the capabilities | proceeds | "expected flush after capabilities" | protocol |
| 4 | discover: a pkt after the capabilities' flush | read as a capability, proceeds | refuses | protocol |
| 5 | discover: no ls-refs (or no fetch) | proceeds | "server doesn't support 'ls-refs'" | unsupported |
| 6 | discover: ERR as the first line | unsupported | "remote error" | remote_error |
| 7 | every pkt-line reader: a payload of 65520–65531 bytes | accepted | "bad line length" | protocol |
| 8 | ls-refs: an unborn … record | protocol | skipped | skipped |
| 9 | ls-refs: an upper-case oid or peeled oid | protocol | accepted | accepted, kept lower-case |
| 10 | ls-refs: an empty name (<oid> , <oid> <name>) | protocol | a ref named "" | a ref named "" |
| 11 | ls-refs: a name listed twice | the last listing | the first | the first |
| 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 |
| 13 | push: atomic or push options to a sha256 repository | advertisement read, hash ignored, pushed: ambiguous | refuses before sending | unsupported 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,emptyobjectFormat(6) — object-format, read by send_capabilities with server_feature_v2 (needs=):sha1,absent,sha256,unknown,bare,emptyfetch(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,absentserverOption(2) — server-option:present,absentsessionId(2) — session-id:absent,presentmalformed(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,erreol(2) — line ends:lf,noneframing(6) — the end of the listing:flush,noFlush,delim,trailing,longMax,longOver
push
request(4) — what the push asks for:none,atomic,options,bothatomic(2) — receive.advertiseAtomic:on,offoptions(2) — receive.advertisePushOptions:off,onformat(2) — the server repository's hash:sha1,sha256
request
flag(5) — one fetch argument ply can send (fetch.js fetchBody):noProgress,progress,includeTag,deepenRelative,filterserver(2) — uploadpack.allowFilter:filterOn,filterOff
Cells
| decision | cells | observed from git | derived |
|---|---|---|---|
| caps | 64,159 | 59 | 64,100 |
| refs | 216 | 216 | 0 |
| push | 32 | 32 | 0 |
| request | 10 | 10 | 0 |
| all | 64,417 | 317 | 64,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) | class | ply outcomes over its cells | cells (observed) | what a caller can safely do next |
|---|---|---|---|---|
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 |
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 |
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 |
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. |
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 |
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 |
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. |
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 |
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) | 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 |
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 |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
deletion prohibited (1522) | rejected | partial, rejected(push_rejected) | 6 (6) | receive.denyDeletes: branch deletion is off on this server |
deletion of the current branch prohibited (1539) | rejected | partial, rejected(push_rejected) | 4 (4) | receive.denyDeleteCurrent refuses deleting HEAD's branch, whatever its value |
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. |
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) |
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) |
hook declined (1579) | rejected | partial, rejected(push_rejected) | 42 (42) | the update hook refused the ref: server policy, not a race |
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. |
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). |
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. |
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 |
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 |
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 |
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 |
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 |
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. |
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 |
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) |
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) | 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). |
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). |
pre-receive hook declined (1987) | rejected | rejected(push_rejected) | 42 (42) | the pre-receive hook refused the push: server policy, not a race |
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 |
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. |
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 |
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 |
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 |
git >= 2.51 batched texts (era v2.51+, the non-atomic commit failure):
| text | class | what a caller can safely do next |
|---|---|---|
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 |
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 |
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) |
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 |
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 |
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 |
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 |
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 |
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):
| question | git's oracle | ply |
|---|---|---|
| format | git check-ref-format <name> (refs.c check_refname_format(name, 0)) | validateRef |
| 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 |
| delete | the 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 (
expectTypeleft out, COMMIT or TAG) is sent withdeepen 1when the server takes shallow requests. A want named a tree or a blob gets none. - R2 A caller's explicit
deepenis sent as given and always wins (0: nodeepenline). - 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,
shallownot yet known for the quirks record) refused with an empty response, anERRline or HTTP 400 reads the advertisement once per quirks record; iffetch=lists noshallowthe want is asked again withoutdeepen, once; if it is listed the first error stands. Never when the caller gavedeepen. - 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.
- A stale
listed. A record taught that the server listsshallow, on a server that no longer does, refused with anERRline 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 needsshallownot 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 aboutshallowis believed: the want is asked again withoutdeepen(3 cells). - A stale
unlisted. A record taught that the server lists noshallow, on a server that now does: nodeepenis 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. deepenignored. 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.- 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: nodeepenline, 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 commitTAG— may peel to a commit (the want is an annotated tag of the tip)TREE— no history is reachable from a tree: no default depthBLOB— 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 recordlisted— an advertisement that listedshallowunlisted— 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, Artifactsno— a server without shallow fetches
refusal — what the server does with a request that carries deepen (5)
none— takes it: gitempty— HTTP 200 with an empty body: git upload-pack dying on an argument it does not takeerr— an ERR pkt-line (remote_error)400— HTTP 400: how Artifacts refuses an argument it does not takeignored— 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 nofilter)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 → outcome | cells |
|---|---|
POST - → ok | 740 |
POST - → pack_corrupt | 220 |
POST 2 → ok | 180 |
POST 2 → http | 120 |
POST 2 → remote_error | 120 |
POST 2 → protocol | 90 |
POST 1 → ok | 68 |
POST 2 → pack_corrupt | 60 |
POST 2, GET → protocol | 30 |
POST 1 → pack_corrupt | 28 |
POST 1, GET, POST - → ok | 25 |
POST 1 → http | 24 |
POST 1 → remote_error | 24 |
POST 1 → protocol | 18 |
POST 1, GET → protocol | 15 |
POST 1, GET, POST - → pack_corrupt | 14 |
POST 1, GET → http | 12 |
POST 1, GET → remote_error | 12 |
SSH
SSH transport removed 2026-10-31; history on branch archive/ssh.