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