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

gitformat-bundle.5 (5069B)

    

  1. '\" t
  2. .\"     Title: gitformat-bundle
  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 "GITFORMAT\-BUNDLE" "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. gitformat-bundle \- The bundle file format
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. *\&.bundle
  36. *\&.bdl
  37. .fi
  38. .SH "DESCRIPTION"
  39. .sp
  40. The Git bundle format is a format that represents both refs and Git objects\&. A bundle is a header in a format similar to \fBgit-show-ref\fR(1) followed by a pack in *\&.pack format\&.
  41. .sp
  42. The format is created and read by the \fBgit-bundle\fR(1) command, and supported by e\&.g\&. \fBgit-fetch\fR(1) and \fBgit-clone\fR(1)\&.
  43. .SH "FORMAT"
  44. .sp
  45. We will use ABNF notation to define the Git bundle format\&. See \fBgitprotocol-common\fR(5) for the details\&.
  46. .sp
  47. A v2 bundle looks like this:
  48. .sp
  49. .if n \{\
  50. .RS 4
  51. .\}
  52. .nf
  53. bundle    = signature *prerequisite *reference LF pack
  54. signature = "# v2 git bundle" LF
  56. prerequisite = "\-" obj\-id SP comment LF
  57. comment      = *CHAR
  58. reference    = obj\-id SP refname LF
  60. pack         = \&.\&.\&. ; packfile
  61. .fi
  62. .if n \{\
  63. .RE
  64. .\}
  65. .sp
  66. A v3 bundle looks like this:
  67. .sp
  68. .if n \{\
  69. .RS 4
  70. .\}
  71. .nf
  72. bundle    = signature *capability *prerequisite *reference LF pack
  73. signature = "# v3 git bundle" LF
  75. capability   = "@" key ["=" value] LF
  76. prerequisite = "\-" obj\-id SP comment LF
  77. comment      = *CHAR
  78. reference    = obj\-id SP refname LF
  79. key          = 1*(ALPHA / DIGIT / "\-")
  80. value        = *(%01\-09 / %0b\-FF)
  82. pack         = \&.\&.\&. ; packfile
  83. .fi
  84. .if n \{\
  85. .RE
  86. .\}
  87. .SH "SEMANTICS"
  88. .sp
  89. A Git bundle consists of several parts\&.
  90. .sp
  91. .RS 4
  92. .ie n \{\
  93. \h'-04'\(bu\h'+03'\c
  94. .\}
  95. .el \{\
  96. .sp -1
  97. .IP \(bu 2.3
  98. .\}
  99. "Capabilities", which are only in the v3 format, indicate functionality that the bundle requires to be read properly\&.
  100. .RE
  101. .sp
  102. .RS 4
  103. .ie n \{\
  104. \h'-04'\(bu\h'+03'\c
  105. .\}
  106. .el \{\
  107. .sp -1
  108. .IP \(bu 2.3
  109. .\}
  110. "Prerequisites" list the objects that are NOT included in the bundle and the reader of the bundle MUST already have, in order to use the data in the bundle\&. The objects stored in the bundle may refer to prerequisite objects and anything reachable from them (e\&.g\&. a tree object in the bundle can reference a blob that is reachable from a prerequisite) and/or expressed as a delta against prerequisite objects\&.
  111. .RE
  112. .sp
  113. .RS 4
  114. .ie n \{\
  115. \h'-04'\(bu\h'+03'\c
  116. .\}
  117. .el \{\
  118. .sp -1
  119. .IP \(bu 2.3
  120. .\}
  121. "References" record the tips of the history graph, iow, what the reader of the bundle CAN "git fetch" from it\&.
  122. .RE
  123. .sp
  124. .RS 4
  125. .ie n \{\
  126. \h'-04'\(bu\h'+03'\c
  127. .\}
  128. .el \{\
  129. .sp -1
  130. .IP \(bu 2.3
  131. .\}
  132. "Pack" is the pack data stream "git fetch" would send, if you fetch from a repository that has the references recorded in the "References" above into a repository that has references pointing at the objects listed in "Prerequisites" above\&.
  133. .RE
  134. .sp
  135. In the bundle format, there can be a comment following a prerequisite obj\-id\&. This is a comment and it has no specific meaning\&. The writer of the bundle MAY put any string here\&. The reader of the bundle MUST ignore the comment\&.
  136. .SS "Note on shallow clones and Git bundles"
  137. .sp
  138. Note that the prerequisites do not represent a shallow\-clone boundary\&. The semantics of the prerequisites and the shallow\-clone boundaries are different, and the Git bundle v2 format cannot represent a shallow clone repository\&.
  139. .SH "CAPABILITIES"
  140. .sp
  141. Because there is no opportunity for negotiation, unknown capabilities cause \fIgit bundle\fR to abort\&.
  142. .sp
  143. .RS 4
  144. .ie n \{\
  145. \h'-04'\(bu\h'+03'\c
  146. .\}
  147. .el \{\
  148. .sp -1
  149. .IP \(bu 2.3
  150. .\}
  151. \fBobject\-format\fR
  152. specifies the hash algorithm in use, and can take the same values as the
  153. \fBextensions\&.objectFormat\fR
  154. configuration value\&.
  155. .RE
  156. .sp
  157. .RS 4
  158. .ie n \{\
  159. \h'-04'\(bu\h'+03'\c
  160. .\}
  161. .el \{\
  162. .sp -1
  163. .IP \(bu 2.3
  164. .\}
  165. \fBfilter\fR
  166. specifies an object filter as in the
  167. \fB\-\-filter\fR
  168. option in
  169. \fBgit-rev-list\fR(1)\&. The resulting pack\-file must be marked as a \&.\fBpromisor\fR
  170. pack\-file after it is unbundled\&.
  171. .RE
  172. .SH "GIT"
  173. .sp
  174. Part of the \fBgit\fR(1) suite