[thirdparty/git.git] / Documentation / gitprotocol-common.txt

gitprotocol-common(5)
=====================

NAME
----
gitprotocol-common - Things common to various protocols

SYNOPSIS
--------
[verse]
<over-the-wire-protocol>

DESCRIPTION
-----------

This document defines things common to various over-the-wire
protocols and file formats used in Git.

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 `^`, colon `:`, question-mark `?`, asterisk `*`,
  or open bracket `[` anywhere.

. They cannot end with a slash `/` or 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. Receivers MUST treat pkt-lines
with non-binary data the same whether or not they contain the trailing
LF (stripping the LF if present, and not complaining when it is
missing).

The maximum length of a pkt-line's data component is 65516 bytes.
Implementations MUST NOT send pkt-line whose length exceeds 65520
(65516 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"            ""
----

GIT
---
Part of the linkgit:git[1] suite
Commit	Line	Data
5db92105 ÆAB	1	gitprotocol-common(5)
	2	=====================
	3
	4	NAME
	5	----
	6	gitprotocol-common - Things common to various protocols
	7
	8	SYNOPSIS
	9	--------
	10	[verse]
	11	<over-the-wire-protocol>
	12
	13	DESCRIPTION
	14	-----------
	15
859a6d60	16	This document defines things common to various over-the-wire
5db92105	17	protocols and file formats used in Git.
b31222cf SC	18
	19	ABNF Notation
	20	-------------
	21
	22	ABNF notation as described by RFC 5234 is used within the protocol documents,
	23	except the following replacement core rules are used:
	24	----
	25	HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
	26	----
	27
	28	We also define the following common rules:
	29	----
	30	NUL = %x00
	31	zero-id = 40*"0"
	32	obj-id = 40*(HEXDIGIT)
	33
	34	refname = "HEAD"
	35	refname /= "refs/" <see discussion below>
	36	----
	37
	38	A refname is a hierarchical octet string beginning with "refs/" and
	39	not violating the 'git-check-ref-format' command's validation rules.
	40	More specifically, they:
	41
	42	. They can include slash `/` for hierarchical (directory)
	43	grouping, but no slash-separated component can begin with a
	44	dot `.`.
	45
	46	. They must contain at least one `/`. This enforces the presence of a
	47	category like `heads/`, `tags/` etc. but the actual names are not
	48	restricted.
	49
	50	. They cannot have two consecutive dots `..` anywhere.
	51
	52	. They cannot have ASCII control characters (i.e. bytes whose
	53	values are lower than \040, or \177 `DEL`), space, tilde `~`,
6cf378f0	54	caret `^`, colon `:`, question-mark `?`, asterisk `*`,
b31222cf SC	55	or open bracket `[` anywhere.
b31222cf SC	56
a58088ab	57	. They cannot end with a slash `/` or a dot `.`.
b31222cf SC	58
	59	. They cannot end with the sequence `.lock`.
	60
	61	. They cannot contain a sequence `@{`.
	62
	63	. They cannot contain a `\\`.
	64
	65
	66	pkt-line Format
	67	---------------
	68
	69	Much (but not all) of the payload is described around pkt-lines.
	70
	71	A pkt-line is a variable length binary string. The first four bytes
	72	of the line, the pkt-len, indicates the total length of the line,
	73	in hexadecimal. The pkt-len includes the 4 bytes used to contain
	74	the length's hexadecimal representation.
	75
	76	A pkt-line MAY contain binary data, so implementors MUST ensure
	77	pkt-line parsing/formatting routines are 8-bit clean.
	78
	79	A non-binary line SHOULD BE terminated by an LF, which if present
1c9b659d JK	80	MUST be included in the total length. Receivers MUST treat pkt-lines
	81	with non-binary data the same whether or not they contain the trailing
	82	LF (stripping the LF if present, and not complaining when it is
	83	missing).
b31222cf	84
7841c480 LS	85	The maximum length of a pkt-line's data component is 65516 bytes.
	86	Implementations MUST NOT send pkt-line whose length exceeds 65520
	87	(65516 bytes of payload + 4 bytes of length data).
b31222cf SC	88
	89	Implementations SHOULD NOT send an empty pkt-line ("0004").
	90
	91	A pkt-line with a length field of 0 ("0000"), called a flush-pkt,
	92	is a special case and MUST be handled differently than an empty
	93	pkt-line ("0004").
	94
	95	----
	96	pkt-line = data-pkt / flush-pkt
	97
	98	data-pkt = pkt-len pkt-payload
	99	pkt-len = 4*(HEXDIG)
	100	pkt-payload = (pkt-len - 4)*(OCTET)
	101
	102	flush-pkt = "0000"
	103	----
	104
	105	Examples (as C-style strings):
	106
	107	----
	108	pkt-line actual value
	109	---------------------------------
	110	"0006a\n" "a\n"
	111	"0005a" "a"
	112	"000bfoobar\n" "foobar\n"
	113	"0004" ""
	114	----
5db92105 ÆAB	115
	116	GIT
	117	---
	118	Part of the linkgit:git[1] suite