technical/protocol-common.txt

Documentation Common to Pack and Http Protocols
===============================================

ABNF Notation
-------------

ABNF notation as described by RFC 5234 is used within the protocol documents,
except the following replacement core rules are used:
----
 HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
----

We also define the following common rules:
----
 NUL = %x00
 zero-id = 40*"0"
 obj-id = 40*(HEXDIGIT)

 refname = "HEAD"
 refname /= "refs/" <see discussion below>
----

A refname is a hierarchical octet string beginning with "refs/" and
not violating the 'git-check-ref-format' command's validation rules.
More specifically, they:

. They can include slash `/` for hierarchical (directory)
 grouping, but no slash-separated component can begin with a
 dot `.`.

. They must contain at least one `/`. This enforces the presence of a
 category like `heads/`, `tags/` etc. but the actual names are not
 restricted.

. They cannot have two consecutive dots `..` anywhere.

. They cannot have ASCII control characters (i.e. bytes whose
 values are lower than \040, or \177 `DEL`), space, tilde `~`,
 caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`,
 or open bracket `[` anywhere.

. They cannot end with a slash `/` nor a dot `.`.

. They cannot end with the sequence `.lock`.

. They cannot contain a sequence `@{`.

. They cannot contain a `\\`.


pkt-line Format
---------------

Much (but not all) of the payload is described around pkt-lines.

A pkt-line is a variable length binary string. The first four bytes
of the line, the pkt-len, indicates the total length of the line,
in hexadecimal. The pkt-len includes the 4 bytes used to contain
the length's hexadecimal representation.

A pkt-line MAY contain binary data, so implementors MUST ensure
pkt-line parsing/formatting routines are 8-bit clean.

A non-binary line SHOULD BE terminated by an LF, which if present
MUST be included in the total length.

The maximum length of a pkt-line's data component is 65520 bytes.
Implementations MUST NOT send pkt-line whose length exceeds 65524
(65520 bytes of payload + 4 bytes of length data).

Implementations SHOULD NOT send an empty pkt-line ("0004").

A pkt-line with a length field of 0 ("0000"), called a flush-pkt,
is a special case and MUST be handled differently than an empty
pkt-line ("0004").

----
 pkt-line = data-pkt / flush-pkt

 data-pkt = pkt-len pkt-payload
 pkt-len = 4*(HEXDIG)
 pkt-payload = (pkt-len - 4)*(OCTET)

 flush-pkt = "0000"
----

Examples (as C-style strings):

----
 pkt-line actual value
 ---------------------------------
 "0006a\n" "a\n"
 "0005a" "a"
 "000bfoobar\n" "foobar\n"
 "0004" ""
----