| Current File : /home/inlingua/miniconda3/man/man5/gitprotocol-common.5 |
'\" 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: 2024-05-30
.\" Manual: Git Manual
.\" Source: Git 2.45.2
.\" Language: English
.\"
.TH "GITPROTOCOL\-COMMON" "5" "2024\-05\-30" "Git 2\&.45\&.2" "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 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