gitprotocol-common.5 (5368B)
- '\" t
- .\" Title: gitprotocol-common
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GITPROTOCOL\-COMMON" "5" "2025-03-14" "Git 2\&.49\&.0" "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
- .SH "DESCRIPTION"
- .sp
- This document 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
- 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
- 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 \&.\&.
- .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 \&.\&. 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 ?, asterisk *, or open bracket [ 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 \&.\&.
- .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 \&.\fBlock\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 \e\e\&.
- .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
- 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
- .\}
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite