main
1// Format facts for the git wire codecs. Every numeric literal that encodes a format rule lives here, next to the
2// spec it comes from, so a parser cannot drift by "fixing" an off-by-one in a local guard. Other modules import
3// these names. This file is the only place those literals may appear.
4/* oxlint-disable no-magic-numbers -- definitions of the format facts; mutating one is a behavior change */
6/** SHA-1 object id width. gitformat-pack(5): object names in packs are 20 bytes. */
7export const OID_BYTES = 20;
8/** Hex digits in a SHA-1 object name. Two hex chars per byte. */
9export const OID_HEX_CHARS: number = OID_BYTES * 2;
10/** ASCII `'0'` and `'9'`: a decimal hex digit. */
11export const HEX_DIGIT_MIN = 0x30;
12export const HEX_DIGIT_MAX = 0x39;
13/** ASCII `'a'` and `'f'`: a lowercase hex letter. Uppercase is not an object id here. */
14export const HEX_LOWER_MIN = 0x61;
15export const HEX_LOWER_MAX = 0x66;
16/** Forty `'0'` characters: the object id that means "ref does not exist" in a compare-and-swap. */
17export const ZERO_OID: string = '0'.repeat(OID_HEX_CHARS);
18/** SHA-256 object names, rejected: gitprotocol-v2 object-format. */
19export const SHA256_HEX_CHARS = 64;
21/** One byte, and the mask that keeps one. */
22export const BYTE_VALUES = 256;
23export const BYTE_MASK = 255;
25/** Big-endian uint32 shifts. gitformat-pack(5) network order for version and object count. */
26export const BE32_SHIFTS: readonly number[] = Object.freeze([24, 16, 8, 0]);
27export const UINT32_BYTES = 4;
29// ---- tree (gitobject layout; fsck.c fsck_tree) ----
30/** Space between mode and name. */
31export const TREE_MODE_SEP = 0x20;
32/** NUL between name and object id. */
33export const TREE_NUL = 0x00;
34/** Canonical modes git writes. `40000` is the tree mode with the leading zero stripped. */
35export const MODE_BLOB = '100644';
36export const MODE_EXEC = '100755';
37export const MODE_LINK = '120000';
38export const MODE_TREE = '40000';
39export const MODE_COMMIT = '160000';
40/** Blob, executable, and symlink. A tree (`40000`) and a gitlink (`160000`) are not blob modes. */
41export const BLOB_MODES: readonly [typeof MODE_BLOB, typeof MODE_EXEC, typeof MODE_LINK] = Object.freeze([MODE_BLOB, MODE_EXEC, MODE_LINK]);
42/**
43 * fsck.c verify_ordered sorts an entry as a directory when S_ISDIR holds for its mode: the file-type bits (S_IFMT) of
44 * the low 16 bits (fsck keeps the mode in an `unsigned short`) are S_IFDIR. `40755` sorts as a directory; `160000`
45 * (gitlink) as a file. A tree sorts a directory by its name followed by `/`.
46 */
47export const MODE_S_IFMT = 0o17_0000;
48export const MODE_S_IFDIR = 0o04_0000;
49export const MODE_S_IFREG = 0o10_0000;
50export const MODE_S_IFLNK = 0o12_0000;
51/** ce_permissions: a regular file is executable (100755) when the owner-execute bit is set. */
52export const MODE_OWNER_EXEC = 0o100;
53/** fsck.c max_tree_entry_len (fsck.largePathname): a longer name is largePathname (WARN, an error under --strict). */
54export const TREE_MAX_NAME_BYTES = 4096;
55export const MODE_BITS = 0xff_ff;
56/** Octal digits that cover MODE_BITS: the low 18 bits are exact from the last six digits, however long the mode. */
57export const MODE_LOW_DIGITS = 6;
58export const TREE_SORT_SLASH = 0x2f;
59/**
60 * Shortest well-framed entry: one octal mode digit, the separating space, one name byte, NUL, and the object id.
61 * git's tree-walk rejects anything shorter (`too-short tree object`).
62 */
63export const TREE_MODE_MIN_DIGITS = 1;
64export const TREE_NAME_MIN_BYTES = 1;
65export const TREE_ENTRY_OVERHEAD: number = TREE_MODE_MIN_DIGITS + 1 + TREE_NAME_MIN_BYTES + 1;
66export const TREE_ENTRY_MIN: number = TREE_ENTRY_OVERHEAD + OID_BYTES;
68// ---- pkt-line (gitprotocol-common(5)) ----
69/** Hex digits of the length prefix. The length counts those digits. */
70export const PKT_LEN_HEX = 4;
71export const PKT_HEX_BASE = 16;
72/** `0000` flush, `0001` delim, `0002` response-end. Length 3 is not a pkt-line. */
73export const PKT_FLUSH = 0;
74export const PKT_DELIM = 1;
75export const PKT_RESPONSE_END = 2;
76export const PKT_LEN_INVALID = 3;
77/** Smallest data pkt-line: the 4 hex digits and an empty payload. */
78export const PKT_DATA_MIN: number = PKT_LEN_HEX;
79/** gitprotocol-common(5): pkt-line length must be ≤ 65520. Payload budget is that minus the length prefix. */
80export const PKT_MAX_SIZE = 65_520;
81export const PKT_MAX_PAYLOAD: number = PKT_MAX_SIZE - PKT_LEN_HEX;
82/** What git's reader accepts: pkt-line.c packet_read_with_status dies "protocol error: bad line length" once the payload
83 * (length minus the prefix) is ≥ its buffer, packet_buffer[LARGE_PACKET_MAX]. So it reads payloads up to 65519 bytes. */
84export const PKT_READ_MAX_PAYLOAD: number = PKT_MAX_SIZE - 1;
85/** Nibble width when decoding the hex length. Shifts of the four hex digits, high digit first. */
86export const NIBBLE_BITS = 4;
87export const PKT_LEN_SHIFTS: readonly number[] = Object.freeze([NIBBLE_BITS * 3, NIBBLE_BITS * 2, NIBBLE_BITS, 0]);
89// ---- pack (gitformat-pack(5)) ----
90/** ASCII `PACK`. */
91export const PACK_SIGNATURE: readonly number[] = Object.freeze([0x50, 0x41, 0x43, 0x4b]);
92export const PACK_VERSION = 2;
93/** 4 signature + 4 version + 4 object count. */
94export const PACK_HEADER_BYTES = 12;
95/** Trailer is the SHA-1 of every preceding byte. */
96export const PACK_TRAILER_BYTES: number = OID_BYTES;
97/** Object type codes. 0 and 5 are reserved. */
98export const OBJ_COMMIT = 1;
99export const OBJ_TREE = 2;
100export const OBJ_BLOB = 3;
101export const OBJ_TAG = 4;
102export const OBJ_OFS_DELTA = 6;
103export const OBJ_REF_DELTA = 7;
104/** The four object types git stores. Deltas exist only inside a pack. */
105export type ObjectTypeName = 'commit' | 'tree' | 'blob' | 'tag';
106/** Pack type name: a stored object, or one of the two delta kinds. */
107export type PackKind = ObjectTypeName | 'ofs_delta' | 'ref_delta';
108/** Numeric type id (pack.h OBJ_*). 0 and 5 are not members. */
109export type ObjType = typeof OBJ_COMMIT | typeof OBJ_TREE | typeof OBJ_BLOB | typeof OBJ_TAG | typeof OBJ_OFS_DELTA | typeof OBJ_REF_DELTA;
110export const OBJ_TYPE_SHIFT = 4;
111export const OBJ_TYPE_MASK = 7;
112/** Low nibble of the first header byte is the size; later bytes carry 7 bits. MSB continues. */
113export const OBJ_SIZE_FIRST_MASK = 0x0f;
114export const OBJ_SIZE_NEXT_MASK = 0x7f;
115export const OBJ_CONTINUE = 0x80;
116export const OBJ_SIZE_FIRST_BASE = 16;
117export const OBJ_SIZE_NEXT_BASE = 128;
118export const VARINT_BITS = 7;
119/** A size varint's 7-bit group may start at bit 63 at most: git refuses `bitsizeof(size_t) <= shift` ("bad object header",
120 * packfile.c) and dies on a delta size that overflows size_t (st_left_shift). An object header is then ≤ 10 bytes
121 * (4 + 9 × 7 bits), a delta size ≤ 10 bytes (10 × 7), and every decoded size is finite. */
122export const VARINT_MAX_SHIFT = 63;
124// ---- delta (gitformat-pack(5) "Deltified representation"; patch-delta.c DELTA_SIZE_MIN) ----
125/** git rejects a delta shorter than 4 bytes. */
126export const DELTA_SIZE_MIN = 4;
127/** Copy instruction: high bit set. Insert length is 1..127. Opcode 0 is reserved. */
128export const DELTA_COPY = 0x80;
129export const DELTA_INSERT_MAX = 127;
130/** Copy size of 0 means 0x10000. */
131export const DELTA_COPY_MAX = 0x1_00_00;
132export const DELTA_COPY_OFF1 = 0x01;
133export const DELTA_COPY_OFF2 = 0x02;
134export const DELTA_COPY_OFF3 = 0x04;
135export const DELTA_COPY_OFF4 = 0x08;
136export const DELTA_COPY_LEN1 = 0x10;
137export const DELTA_COPY_LEN2 = 0x20;
138export const DELTA_COPY_LEN3 = 0x40;
139/** Width of one byte. The next little-endian or offset byte sits this many bits higher. */
140export const BYTE_SHIFT = 8;
141export const DELTA_OFF_SHIFT: number = BYTE_SHIFT;
142/** Second and third offset/length bytes sit 16 bits up (two groups of DELTA_OFF_SHIFT). */
143export const DELTA_BYTE2_SHIFT: number = DELTA_OFF_SHIFT * 2;
144export const DELTA_OFF4_FACTOR = 0x1_00_00_00;
146// ---- sideband (gitprotocol-pack(5) side-band-64k; gitprotocol-v2(5) packfile section) ----
147export const SIDEBAND_PACK = 1;
148export const SIDEBAND_PROGRESS = 2;
149export const SIDEBAND_ERROR = 3;
150export const SIDEBAND_CHANNEL_BYTES = 1;
152/** gitprotocol-v2(5): the client's `Git-Protocol: version=2` and the `version 2` advertisement line. */
153export const PROTOCOL_V2 = 2;
155// ---- ident timezone (fsck.c fsck_ident, FSCK_MSG_BAD_TIMEZONE) ----
156/**
157 * Digits after the `+` or `-` of a commit or tag ident timezone (`+0530`). The zone is that sign,
158 * these digits, and then the newline. git does not range-check the hour or the minute: `+9999` and
159 * `+1560` are well-formed. A non-digit, a shorter or longer run, a missing sign, or any trailing byte
160 * is "bad time zone".
161 */
162export const IDENT_TZ_DIGITS = 4;
163/**
164 * Caller-supplied offsets only. fsck_ident does not range-check (`+9999` is a well-formed zone on the wire;
165 * checkIdent stays that loose). A caller is held to the offsets civil time uses: −12:00 (Etc/GMT+12) through
166 * +14:00 (Pacific/Kiritimati), minutes 00..59, and the extreme hours only on the hour.
167 */
168export const IDENT_TZ_HOUR_MIN = -12;
169export const IDENT_TZ_HOUR_MAX = 14;
170export const IDENT_TZ_MINUTE_MAX = 59;
172/**
173 * The largest author/committer/tagger timestamp fsck_ident accepts (fsck.c FSCK_MSG_BAD_DATE_OVERFLOW): git parses
174 * the digits with strtoumax and date_overflows() refuses anything that does not fit a signed 64-bit time_t, so
175 * 9223372036854775807 is a date and 9223372036854775808 is "date causes integer overflow". Measured on git 2.50
176 * (test/fsck-space.test.js `ok-max-date`, `date-overflow`).
177 */
178export const IDENT_TIMESTAMP_MAX = 0x7f_ff_ff_ff_ff_ff_ff_ffn;
180// ---- commit headers (Documentation/gitformat-commit; fsck.c fsck_commit) ----
181// fsck_commit reads exactly one tree, then any parent lines, then author lines (exactly one allowed), then one
182// committer, and stops: whatever follows (encoding, gpgsig, mergetag, unknown headers, a second tree or committer) is
183// not checked by fsck. ply keeps those lines in `extra`, except a second tree, parent, author, committer or encoding:
184// git's views of such an object disagree (pretty.c is last-wins for %an/%cn, %T and the date are first-wins), so ply
185// refuses it (PR #7, an allowed typed refusal in test/fsck-space.test.js).
186export const COMMIT_HEADER_TREE = 'tree';
187export const COMMIT_HEADER_PARENT = 'parent';
188export const COMMIT_HEADER_AUTHOR = 'author';
189export const COMMIT_HEADER_COMMITTER = 'committer';
190export const COMMIT_HEADER_ENCODING = 'encoding';
192// ---- tag headers (fsck.c fsck_tag_standalone) ----
193// An annotated tag is object, type, tag, then tagger (optional: tags before git 0.99.1 have none), then anything but a
194// second object, type, tag or tagger (refused like a second commit author, PR #7).
195export const TAG_HEADER_OBJECT = 'object';
196export const TAG_HEADER_TYPE = 'type';
197export const TAG_HEADER_TAG = 'tag';
198export const TAG_HEADER_TAGGER = 'tagger';
200// ---- zlib / deflate (RFC 1950, RFC 1951) ----
201export const ZLIB_HEADER_BYTES = 2;
202export const ZLIB_CM_DEFLATE = 8;
203export const ZLIB_CM_MASK = 0x0f;
204export const ZLIB_FDICT = 0x20;
205export const ZLIB_HEADER_MOD = 31;
206/** RFC 1950 CMF: CINFO is the high nibble, the window is 2^(CINFO + 8) bytes; 7 (32 KiB) is the largest zlib allows. */
207export const ZLIB_CINFO_SHIFT = 4;
208export const ZLIB_CINFO_MAX = 7;
209export const ZLIB_WINDOW_EXPONENT = 8;
210export const ADLER_BYTES = 4;
211export const ADLER_MOD = 65_521;
212/** Adler-32 stores the sum `b` in the high 16 bits. RFC 1950 §2.2. */
213export const ADLER_SHIFT = 16;
214/** Bytes summed between two reductions of the Adler sums (zlib's NMAX; any block size gives the same sums in doubles). */
215export const ADLER_NMAX = 5552;
216export const DEFLATE_BFINAL_BITS = 1;
217export const DEFLATE_BTYPE_BITS = 2;
218export const DEFLATE_STORED = 0;
219export const DEFLATE_FIXED = 1;
220export const DEFLATE_DYNAMIC = 2;
221export const DEFLATE_STORED_HEADER_BYTES = 4;
222/** One's complement of the stored-block length is 16 bits. RFC 1951 §3.2.4. */
223export const DEFLATE_STORED_LEN_MASK = 0xff_ff;
224export const DEFLATE_MAX_BITS = 15;
225/** Deflate's largest window (CINFO 7, 2^15 bytes, RFC 1951 §2). A streaming inflater keeps this much output and no more. */
226export const INFLATE_WINDOW: number = 1 << DEFLATE_MAX_BITS;
227/** Bytes one streaming inflate pull yields at most: half a window, so a pull holds one chunk beside the window. */
228export const INFLATE_CHUNK: number = INFLATE_WINDOW / 2;
229/** Bytes of an object push hands CompressionStream at a time (packwrite.ts): two windows. The deflate output of one slice
230 * is what the push writer holds beside the caller's objects (at most this plus one 16 KiB block: 81,940 B measured, was
231 * 32,776 B with INFLATE_CHUNK slices), for 3-5% less push CPU under workerd and 8% under node (CONTEXT.md). */
232export const DEFLATE_SLICE: number = 2 * INFLATE_WINDOW;
233export const DEFLATE_BIT_TABLE = 16;
234/** Bits the inflate decoder looks a code up by in one step; a longer code is decoded a bit at a time. */
235export const INFLATE_FAST_BITS = 9;
236/** A fast-table entry is the code's length above the symbol's 9 bits (a symbol is below 288, a length at most 9). */
237export const INFLATE_FAST_SYMBOL_BITS = 9;
238/** The inflate decoder tops its bit buffer up while it holds fewer bits than this: one byte more still fits in 32 bits. */
239export const INFLATE_LOOKAHEAD_BITS = 24;
240export const DEFLATE_LITERALS = 256;
241export const DEFLATE_EOB = 256;
242export const DEFLATE_LENGTH_BASE = 257;
243export const DEFLATE_LENGTH_CODES = 29;
244export const DEFLATE_HLIT_BASE = 257;
245export const DEFLATE_HLIT_BITS = 5;
246export const DEFLATE_HDIST_BASE = 1;
247export const DEFLATE_HDIST_BITS = 5;
248export const DEFLATE_HCLEN_BASE = 4;
249export const DEFLATE_HCLEN_BITS = 4;
250export const DEFLATE_HLIT_MAX = 286;
251export const DEFLATE_HDIST_MAX = 30;
252export const DEFLATE_CODELEN_CODES = 19;
253export const DEFLATE_CODELEN_BITS = 3;
254export const DEFLATE_REPEAT_PREV = 16;
255export const DEFLATE_REPEAT_ZERO3 = 17;
256export const DEFLATE_REPEAT_ZERO11 = 18;
257export const DEFLATE_REPEAT16_BASE = 3;
258export const DEFLATE_REPEAT16_BITS = 2;
259export const DEFLATE_REPEAT17_BASE = 3;
260export const DEFLATE_REPEAT17_BITS = 3;
261export const DEFLATE_REPEAT18_BASE = 11;
262export const DEFLATE_REPEAT18_BITS = 7;
264// ---- zlib stream length (zlib deflate.c deflateBound, compress.c compressBound) ----
265// RFC 1951 puts no ceiling on a deflate stream's length: a non-final empty stored block costs 5 bytes and produces nothing,
266// and may repeat forever (a fixed block holding only end-of-block, 10 bits, likewise). So "how long may the zlib stream
267// of an object declared S bytes be" is a policy, and the policy is zlib's own promise about its output: deflateBound(S)
268// is the most any level, strategy, windowBits or memLevel emits for S bytes under Z_FINISH/Z_NO_FLUSH (zlib.h). Its
269// conservative form (deflate.c, non-default parameters) is sourceLen + ((sourceLen + 7) >> 3) + ((sourceLen + 63) >> 6)
270// + 5 + a 6-byte wrapper: 9-bit literals in fixed blocks (RFC 1951 §3.2.6: literals 144–255) plus per-block overhead at
271// zlib's smallest blocks. The constant is compressBound's 13 (compress.c: the 2-byte header, the 4-byte Adler-32, and 7),
272// which also covers zlib 1.3's storelen (stored blocks of 127 bytes at memLevel 1, + 7) and fixedlen (+ 4) forms and the
273// 65535-byte stored blocks a level-0 encoder writes. zlibBound(S) = S + ⌈S/8⌉ + ⌈S/64⌉ + 13 is ≥ every one of those at
274// every S (test/format-facts.test.js checks the inequalities, mutant-kill.test.js node:zlib's actual output); an encoder
275// that flushes between tiny chunks could exceed it, and no git server does. Input past it is `pack_corrupt`.
276export const ZLIB_BOUND_LITERAL_DIV = 8;
277export const ZLIB_BOUND_BLOCK_DIV = 64;
278export const ZLIB_BOUND_SLACK = 13;
279/** The longest zlib stream accepted for an object whose inflated size is `size`. Finite for every finite size. */
280export const zlibBound = (size: number): number => size + Math.ceil(size / ZLIB_BOUND_LITERAL_DIV) + Math.ceil(size / ZLIB_BOUND_BLOCK_DIV) + ZLIB_BOUND_SLACK;
282/** `2 ** shift` for a size-varint group. Defined once so the base is not recopied at each call site. */
283export const varintScale = (shift: number): number => 2 ** shift;
Diagnostics4 git calls · 29 ms
CallStatusSizeTime029 ms
discover200152 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 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 · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=2 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 · hit8 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=19 git.response.bytes=38434 git.response.cache=HIT git.response.duration_ms=8 git.fetch.filter=blob:none git.fetch.filter.requested=tree:0 git.fetch.filter.fallback=blob:none git.fetch.filter.learned=false git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=6 git.pkt.data=4 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=38434 git.pkt.payload.max=38339 git.sideband.band1.bytes=38338 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=63 git.pack.bytes=38338 git.pack.ofs_delta=0 git.pack.ref_delta=8 git.pack.chain.max=8 git.pack.trailer=0bc36ab7adf82d3109177f11f1ea93f1ce071f77 git.pack.full=55Open pack map
fetch2006.2 KiB · hit19 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=6328 git.response.cache=HIT git.response.duration_ms=19 git.fetch.wants=8e89ce88c747b04d0af3afc0682aab680a96043c 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=6328 git.pkt.payload.max=6307 git.sideband.band1.bytes=6306 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
- a5e21eaa9c6ea87d
- Request
- ded24818…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format