man5/gitprotocol-common.5

   1 '\" t
   2 .\"     Title: gitprotocol-common
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-08-09
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.42.0.rc1
   8 .\"  Language: English
   9 .\"
  10 .TH "GITPROTOCOL\-COMMON" "5" "2023\-08\-09" "Git 2\&.42\&.0\&.rc1" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 gitprotocol-common \- Things common to various protocols
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 <over\-the\-wire\-protocol>
  36 .fi
  37 .sp
  38 .SH "DESCRIPTION"
  39 .sp
  40 This document sets defines things common to various over\-the\-wire protocols and file formats used in Git\&.
  41 .SH "ABNF NOTATION"
  42 .sp
  43 ABNF notation as described by RFC 5234 is used within the protocol documents, except the following replacement core rules are used:
  44 .sp
  45 .if n \{\
  46 .RS 4
  47 .\}
  48 .nf
  49   HEXDIG    =  DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
  50 .fi
  51 .if n \{\
  52 .RE
  53 .\}
  54 .sp
  55 .sp
  56 We also define the following common rules:
  57 .sp
  58 .if n \{\
  59 .RS 4
  60 .\}
  61 .nf
  62   NUL       =  %x00
  63   zero\-id   =  40*"0"
  64   obj\-id    =  40*(HEXDIGIT)
  65
  66   refname  =  "HEAD"
  67   refname /=  "refs/" <see discussion below>
  68 .fi
  69 .if n \{\
  70 .RE
  71 .\}
  72 .sp
  73 .sp
  74 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:
  75 .sp
  76 .RS 4
  77 .ie n \{\
  78 \h'-04' 1.\h'+01'\c
  79 .\}
  80 .el \{\
  81 .sp -1
  82 .IP "  1." 4.2
  83 .\}
  84 They can include slash
  85 \fB/\fR
  86 for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot
  87 \fB\&.\fR\&.
  88 .RE
  89 .sp
  90 .RS 4
  91 .ie n \{\
  92 \h'-04' 2.\h'+01'\c
  93 .\}
  94 .el \{\
  95 .sp -1
  96 .IP "  2." 4.2
  97 .\}
  98 They must contain at least one
  99 \fB/\fR\&. This enforces the presence of a category like
 100 \fBheads/\fR,
 101 \fBtags/\fR
 102 etc\&. but the actual names are not restricted\&.
 103 .RE
 104 .sp
 105 .RS 4
 106 .ie n \{\
 107 \h'-04' 3.\h'+01'\c
 108 .\}
 109 .el \{\
 110 .sp -1
 111 .IP "  3." 4.2
 112 .\}
 113 They cannot have two consecutive dots
 114 \fB\&.\&.\fR
 115 anywhere\&.
 116 .RE
 117 .sp
 118 .RS 4
 119 .ie n \{\
 120 \h'-04' 4.\h'+01'\c
 121 .\}
 122 .el \{\
 123 .sp -1
 124 .IP "  4." 4.2
 125 .\}
 126 They cannot have ASCII control characters (i\&.e\&. bytes whose values are lower than \e040, or \e177
 127 \fBDEL\fR), space, tilde
 128 \fB~\fR, caret
 129 \fB^\fR, colon
 130 \fB:\fR, question\-mark
 131 \fB?\fR, asterisk
 132 \fB*\fR, or open bracket
 133 \fB[\fR
 134 anywhere\&.
 135 .RE
 136 .sp
 137 .RS 4
 138 .ie n \{\
 139 \h'-04' 5.\h'+01'\c
 140 .\}
 141 .el \{\
 142 .sp -1
 143 .IP "  5." 4.2
 144 .\}
 145 They cannot end with a slash
 146 \fB/\fR
 147 or a dot
 148 \fB\&.\fR\&.
 149 .RE
 150 .sp
 151 .RS 4
 152 .ie n \{\
 153 \h'-04' 6.\h'+01'\c
 154 .\}
 155 .el \{\
 156 .sp -1
 157 .IP "  6." 4.2
 158 .\}
 159 They cannot end with the sequence
 160 \fB\&.lock\fR\&.
 161 .RE
 162 .sp
 163 .RS 4
 164 .ie n \{\
 165 \h'-04' 7.\h'+01'\c
 166 .\}
 167 .el \{\
 168 .sp -1
 169 .IP "  7." 4.2
 170 .\}
 171 They cannot contain a sequence
 172 \fB@{\fR\&.
 173 .RE
 174 .sp
 175 .RS 4
 176 .ie n \{\
 177 \h'-04' 8.\h'+01'\c
 178 .\}
 179 .el \{\
 180 .sp -1
 181 .IP "  8." 4.2
 182 .\}
 183 They cannot contain a
 184 \fB\e\e\fR\&.
 185 .RE
 186 .SH "PKT\-LINE FORMAT"
 187 .sp
 188 Much (but not all) of the payload is described around pkt\-lines\&.
 189 .sp
 190 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\&.
 191 .sp
 192 A pkt\-line MAY contain binary data, so implementors MUST ensure pkt\-line parsing/formatting routines are 8\-bit clean\&.
 193 .sp
 194 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)\&.
 195 .sp
 196 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)\&.
 197 .sp
 198 Implementations SHOULD NOT send an empty pkt\-line ("0004")\&.
 199 .sp
 200 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")\&.
 201 .sp
 202 .if n \{\
 203 .RS 4
 204 .\}
 205 .nf
 206   pkt\-line     =  data\-pkt / flush\-pkt
 207
 208   data\-pkt     =  pkt\-len pkt\-payload
 209   pkt\-len      =  4*(HEXDIG)
 210   pkt\-payload  =  (pkt\-len \- 4)*(OCTET)
 211
 212   flush\-pkt    = "0000"
 213 .fi
 214 .if n \{\
 215 .RE
 216 .\}
 217 .sp
 218 .sp
 219 Examples (as C\-style strings):
 220 .sp
 221 .if n \{\
 222 .RS 4
 223 .\}
 224 .nf
 225   pkt\-line          actual value
 226   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 227   "0006a\en"         "a\en"
 228   "0005a"           "a"
 229   "000bfoobar\en"    "foobar\en"
 230   "0004"            ""
 231 .fi
 232 .if n \{\
 233 .RE
 234 .\}
 235 .sp
 236 .SH "GIT"
 237 .sp
 238 Part of the \fBgit\fR(1) suite