diff options
Diffstat (limited to 'man5/gitprotocol-common.5')
| -rw-r--r-- | man5/gitprotocol-common.5 | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/man5/gitprotocol-common.5 b/man5/gitprotocol-common.5 new file mode 100644 index 000000000..2a4f38d87 --- /dev/null +++ b/man5/gitprotocol-common.5 @@ -0,0 +1,238 @@ +'\" t +.\" Title: gitprotocol-common +.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 08/18/2022 +.\" Manual: Git Manual +.\" Source: Git 2.37.2.382.g795ea8776b +.\" Language: English +.\" +.TH "GITPROTOCOL\-COMMON" "5" "08/18/2022" "Git 2\&.37\&.2\&.382\&.g795ea8" "Git Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +gitprotocol-common \- Things common to various protocols +.SH "SYNOPSIS" +.sp +.nf +<over\-the\-wire\-protocol> +.fi +.sp +.SH "DESCRIPTION" +.sp +This document sets defines things common to various over\-the\-wire protocols and file formats used in Git\&. +.SH "ABNF NOTATION" +.sp +ABNF notation as described by RFC 5234 is used within the protocol documents, except the following replacement core rules are used: +.sp +.if n \{\ +.RS 4 +.\} +.nf + HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" +.fi +.if n \{\ +.RE +.\} +.sp +.sp +We also define the following common rules: +.sp +.if n \{\ +.RS 4 +.\} +.nf + NUL = %x00 + zero\-id = 40*"0" + obj\-id = 40*(HEXDIGIT) + + refname = "HEAD" + refname /= "refs/" <see discussion below> +.fi +.if n \{\ +.RE +.\} +.sp +.sp +A refname is a hierarchical octet string beginning with "refs/" and not violating the \fIgit\-check\-ref\-format\fR command\(cqs validation rules\&. More specifically, they: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +They can include slash +\fB/\fR +for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot +\fB\&.\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +They must contain at least one +\fB/\fR\&. This enforces the presence of a category like +\fBheads/\fR, +\fBtags/\fR +etc\&. but the actual names are not restricted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +They cannot have two consecutive dots +\fB\&.\&.\fR +anywhere\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +They cannot have ASCII control characters (i\&.e\&. bytes whose values are lower than \e040, or \e177 +\fBDEL\fR), space, tilde +\fB~\fR, caret +\fB^\fR, colon +\fB:\fR, question\-mark +\fB?\fR, asterisk +\fB*\fR, or open bracket +\fB[\fR +anywhere\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +They cannot end with a slash +\fB/\fR +or a dot +\fB\&.\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +They cannot end with the sequence +\fB\&.lock\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 7." 4.2 +.\} +They cannot contain a sequence +\fB@{\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 8." 4.2 +.\} +They cannot contain a +\fB\e\e\fR\&. +.RE +.SH "PKT\-LINE FORMAT" +.sp +Much (but not all) of the payload is described around pkt\-lines\&. +.sp +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\(cqs hexadecimal representation\&. +.sp +A pkt\-line MAY contain binary data, so implementors MUST ensure pkt\-line parsing/formatting routines are 8\-bit clean\&. +.sp +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)\&. +.sp +The maximum length of a pkt\-line\(cqs data component is 65516 bytes\&. Implementations MUST NOT send pkt\-line whose length exceeds 65520 (65516 bytes of payload + 4 bytes of length data)\&. +.sp +Implementations SHOULD NOT send an empty pkt\-line ("0004")\&. +.sp +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")\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + 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" +.fi +.if n \{\ +.RE +.\} +.sp +.sp +Examples (as C\-style strings): +.sp +.if n \{\ +.RS 4 +.\} +.nf + pkt\-line actual value + \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + "0006a\en" "a\en" + "0005a" "a" + "000bfoobar\en" "foobar\en" + "0004" "" +.fi +.if n \{\ +.RE +.\} +.sp +.SH "GIT" +.sp +Part of the \fBgit\fR(1) suite |