man5/gitprotocol-common.5

'\" 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-10-08
.\"    Manual: Git Manual
.\"    Source: Git 2.51.0.480.g60f3f52f17
.\"  Language: English
.\"
.TH "GITPROTOCOL\-COMMON" "5" "2025-10-08" "Git 2\&.51\&.0\&.480\&.g60f3f5" "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
\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 ?, asterisk
\fB*\fR, 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
\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
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