alkgit/docs/research/push-captures.md

# Research: receive-pack (push) walkthrough captures

**Status**: complete
**Date**: 2026-09-25
**Client**: git 2.43.0
**Method**: real `git push` (file://, git:// daemon, and smart-http against
a ground-truth mock receive-pack server validated against real git
behavior), plus raw stdio requests driven into real `git receive-pack` for
policy-error ground truth. This is the normative push-path wire record
that ADR-013 is built on. Scratch logs were in /tmp/opencode/oq04/ (not
kept); every fact below is restated in full here.

## Advertisement (GET info/refs + duplex)

- Smart-http GET: `# service=git-receive-pack` + flush, then a **V0-shaped
  ref advertisement**: `<oid> <ref>\0<caps>` on the FIRST ref line only,
  remaining ref lines bare, flush. The `capabilities^{}` zero-id sentinel
  line replaces the ref lines ONLY when the repo has no refs.
  Content-Type: `application/x-git-receive-pack-advertisement`.
- Duplex (git daemon): same ref advertisement WITHOUT the service prefix;
  server speaks first; no version negotiation at all — receive-pack is
  V0/V1-framed even for modern git (protocol.version=2 does not apply).
- Real receive-pack caps: `report-status report-status-v2 delete-refs
  side-band-64k quiet atomic ofs-delta object-format=sha1 agent=git/2.43.0`
  (+ `push-options` when receive.advertisePushOptions=true). The client
  selects a subset NUL-attached on its FIRST command line (observed:
  `report-status-v2 side-band-64k quiet object-format=sha1 agent=...`;
  note the leading space after the NUL).
- git 2.43 rejects a bare capability dump (no refs, no sentinel) and
  rejects a trailing `capabilities^{}` line when refs exist
  (`fatal: unexpected capabilities^{}`).

## Request (POST git-receive-pack)

- Body: command pkt-lines `<old> <new> <ref>` (caps NUL-attached on the
  first line only) + flush + [push-options section: bare pkt-lines +
  flush, only when push-options was negotiated] + PACK stream (raw, to
  end of body).
- Deletes: old=<current sha> new=zero-id. Creates: old=zero-id.
- Shallow clients push `shallow <sha>` lines BEFORE the command lines
  (captured from a --depth 1 clone push). Real receive-pack ACCEPTS them
  (unpack ok, refs applied) when the pack completes history; rejects with
  `ng <ref> shallow update not allowed` when the server would have to
  graft (receive.shallowUpdateDeepen unset).
- HTTP framing: POST Content-Type
  `application/x-git-receive-pack-request`; small bodies Content-Length;
  large (above http.postBuffer, git 2.43 default 1 MB) → chunked, and a
  4-byte `0000` probe POST answered 200-empty (same shape as upload-pack,
  POC-3).
- git:// framing: first pkt `git-receive-pack /<repo>\0host=<host>\0`, then
  the advertisement (server speaks first, no service prefix), then the
  request on the stream.

## Thin pack

- `git push` sends THIN packs by default (push.thin=true): the pack
  excludes objects the client believes the server already has (observed:
  the unchanged parent tree and its blob excluded; the new commit, tree,
  blob sent). NO `thin-pack` capability is involved on push (that string
  is a fetch arg). Ingestion MUST resolve delta bases from the server's
  own odb — the `Option<Never>` no-lookup composition is only valid when
  the pack is known-not-thin.
- Verified: `git index-pack --strict --stdin` FAILS on the captured pack
  ("did not receive expected object"); `--fix-thin` succeeds.

## Status report

- When side-band-64k was selected: the report is band-1 pkt-line chunks;
  the band payload is ITSELF pkt-line-framed: `unpack ok|ng <reason>`,
  then per-ref `ok <ref>` / `ng <ref> <reason>`, terminated by an INNER
  flush pkt inside the band; the response then ends with an OUTER flush.
  Without sideband (file:// local path): report lines are bare pkt-lines
  to a single flush.
- Observed per-ref ng reasons (real receive-pack): `shallow update not
  allowed`, `deletion prohibited`, `non-fast-forward`, `atomic push
  failure` (rollback of other refs). `unpack ok` even when some refs fail;
  pack-level failure → `unpack ng <reason>` (git source: the index-pack
  error text; not live-captured).
- Atomic: captured `ng refs/heads/dev deletion prohibited` + `ng
  refs/heads/main atomic push failure` in one report (dev was the real
  failure; main was rolled back).
- Human-readable diagnostics ride band-2 (`remote: error: denying
  non-fast-forward refs/heads/main (you should pull first)`).
- Client aborts on framing errors: a report sent WITHOUT sideband when the
  client selected side-band-64k → `fatal: protocol error: bad line length
  character` (observed live) — the report MUST be sideband-wrapped when
  side-band-64k was selected.

## CAS / race semantics

- The advertisement IS the client's CAS check: a stale old-id that does
  not appear in the advertisement → client refuses to send (non-FF or
  fetch-first message, NO commands transmitted).
- Server-side CAS is still required: races between advertisement and
  apply, and clients that send wrong old-ids deliberately. old must match
  current (or zero-id create) per ref; else `ng <ref> <reason>`.
- Empty command list (immediate `0000`) = client-side nothing-to-do.

## Version/framing surface

- No version line anywhere in receive-pack: no `version=2` exchange on
  push; the push path is V0/V1-framed regardless of protocol.version.
- report-status-v2 selected by the client when offered; response shape is
  identical to v1 for plain pushes (v2 adds option lines only when
  options exist).
## Raw stdio captures into real `git receive-pack` (hand-built requests)

- Corrupt pack: `unpack protocol error (pack signature mismatch detected)` +
  `ng <ref> unpacker error` — unpack runs BEFORE ref checks; a failed pack
  reports per-ref 'unpacker error' (not the detailed reason).
- Truncated request: `unpack eof before pack header was fully read`.
- Invalid ref name with a VALID pack: `unpack ok` + `ng refs/heads/../evil
  funny refname` — name validation is per-ref, after unpack, with reason
  'funny refname'. (Client-side git refuses such refnames itself; this is
  the malicious-client path.)
- Advertisement confirmed on the raw path: first ref line carries the caps
  NUL-attached; `unpack ng <reason>` at pack level, per-ref lines after.

## Pack-read ordering (definitive)

Real receive-pack ALWAYS expects a pack after the command flush (missing
pack → `unpack eof before pack header was fully read` + all refs
`unpacker error`). Per-ref checks (CAS, name validation, policy) run AFTER
the pack is indexed — observed: stale-old ng, 'funny refname' ng, 'deletion
prohibited' ng all arrive only after `unpack ok`. Fail-fast CAS before
reading the pack is an optimization, not the protocol order.

## quiet semantics

The client selects `quiet` on its first command line in every capture; band-2
error lines still arrived (`remote: error: denying non-fast-forward ...`).
quiet suppresses progress chatter, not error/diagnostic bands.