logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

gitprotocol-common.5 (5368B)


  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: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GITPROTOCOL\-COMMON" "5" "2025-03-14" "Git 2\&.49\&.0" "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. refname = "HEAD"
  64. refname /= "refs/" <see discussion below>
  65. .fi
  66. .if n \{\
  67. .RE
  68. .\}
  69. .sp
  70. 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:
  71. .sp
  72. .RS 4
  73. .ie n \{\
  74. \h'-04' 1.\h'+01'\c
  75. .\}
  76. .el \{\
  77. .sp -1
  78. .IP " 1." 4.2
  79. .\}
  80. They can include slash
  81. \fB/\fR
  82. for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot \&.\&.
  83. .RE
  84. .sp
  85. .RS 4
  86. .ie n \{\
  87. \h'-04' 2.\h'+01'\c
  88. .\}
  89. .el \{\
  90. .sp -1
  91. .IP " 2." 4.2
  92. .\}
  93. They must contain at least one
  94. \fB/\fR\&. This enforces the presence of a category like
  95. \fBheads/\fR,
  96. \fBtags/\fR
  97. etc\&. but the actual names are not restricted\&.
  98. .RE
  99. .sp
  100. .RS 4
  101. .ie n \{\
  102. \h'-04' 3.\h'+01'\c
  103. .\}
  104. .el \{\
  105. .sp -1
  106. .IP " 3." 4.2
  107. .\}
  108. They cannot have two consecutive dots \&.\&. anywhere\&.
  109. .RE
  110. .sp
  111. .RS 4
  112. .ie n \{\
  113. \h'-04' 4.\h'+01'\c
  114. .\}
  115. .el \{\
  116. .sp -1
  117. .IP " 4." 4.2
  118. .\}
  119. They cannot have ASCII control characters (i\&.e\&. bytes whose values are lower than \e040, or \e177
  120. \fBDEL\fR), space, tilde
  121. \fB~\fR, caret
  122. \fB^\fR, colon
  123. \fB:\fR, question\-mark ?, asterisk *, or open bracket [ anywhere\&.
  124. .RE
  125. .sp
  126. .RS 4
  127. .ie n \{\
  128. \h'-04' 5.\h'+01'\c
  129. .\}
  130. .el \{\
  131. .sp -1
  132. .IP " 5." 4.2
  133. .\}
  134. They cannot end with a slash
  135. \fB/\fR
  136. or a dot \&.\&.
  137. .RE
  138. .sp
  139. .RS 4
  140. .ie n \{\
  141. \h'-04' 6.\h'+01'\c
  142. .\}
  143. .el \{\
  144. .sp -1
  145. .IP " 6." 4.2
  146. .\}
  147. They cannot end with the sequence \&.\fBlock\fR\&.
  148. .RE
  149. .sp
  150. .RS 4
  151. .ie n \{\
  152. \h'-04' 7.\h'+01'\c
  153. .\}
  154. .el \{\
  155. .sp -1
  156. .IP " 7." 4.2
  157. .\}
  158. They cannot contain a sequence
  159. \fB@\fR{\&.
  160. .RE
  161. .sp
  162. .RS 4
  163. .ie n \{\
  164. \h'-04' 8.\h'+01'\c
  165. .\}
  166. .el \{\
  167. .sp -1
  168. .IP " 8." 4.2
  169. .\}
  170. They cannot contain a \e\e\&.
  171. .RE
  172. .SH "PKT\-LINE FORMAT"
  173. .sp
  174. Much (but not all) of the payload is described around pkt\-lines\&.
  175. .sp
  176. 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\&.
  177. .sp
  178. A pkt\-line MAY contain binary data, so implementors MUST ensure pkt\-line parsing/formatting routines are 8\-bit clean\&.
  179. .sp
  180. 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)\&.
  181. .sp
  182. 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)\&.
  183. .sp
  184. Implementations SHOULD NOT send an empty pkt\-line ("0004")\&.
  185. .sp
  186. 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")\&.
  187. .sp
  188. .if n \{\
  189. .RS 4
  190. .\}
  191. .nf
  192. pkt\-line = data\-pkt / flush\-pkt
  193. data\-pkt = pkt\-len pkt\-payload
  194. pkt\-len = 4*(HEXDIG)
  195. pkt\-payload = (pkt\-len \- 4)*(OCTET)
  196. flush\-pkt = "0000"
  197. .fi
  198. .if n \{\
  199. .RE
  200. .\}
  201. .sp
  202. Examples (as C\-style strings):
  203. .sp
  204. .if n \{\
  205. .RS 4
  206. .\}
  207. .nf
  208. pkt\-line actual value
  209. \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  210. "0006a\en" "a\en"
  211. "0005a" "a"
  212. "000bfoobar\en" "foobar\en"
  213. "0004" ""
  214. .fi
  215. .if n \{\
  216. .RE
  217. .\}
  218. .SH "GIT"
  219. .sp
  220. Part of the \fBgit\fR(1) suite