man5/gitformat-bundle.5

   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: 2024-09-18
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.1.565.g6531f31ef3
   8 .\"  Language: English
   9 .\"
  10 .TH "GITFORMAT\-BUNDLE" "5" "2024-09-18" "Git 2\&.46\&.1\&.565\&.g6531f3" "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
  55
  56 prerequisite = "\-" obj\-id SP comment LF
  57 comment      = *CHAR
  58 reference    = obj\-id SP refname LF
  59
  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
  74
  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)
  81
  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
 170 \fB\&.promisor\fR
 171 pack\-file after it is unbundled\&.
 172 .RE
 173 .SH "GIT"
 174 .sp
 175 Part of the \fBgit\fR(1) suite