| '\" t |
| .\" Title: gitformat-bundle |
| .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/> |
| .\" Date: 2025-08-13 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.51.0.rc2 |
| .\" Language: English |
| .\" |
| .TH "GITFORMAT\-BUNDLE" "5" "2025-08-13" "Git 2\&.51\&.0\&.rc2" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| gitformat-bundle \- The bundle file format |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| *\&.bundle |
| *\&.bdl |
| .fi |
| .SH "DESCRIPTION" |
| .sp |
| 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\&. |
| .sp |
| 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)\&. |
| .SH "FORMAT" |
| .sp |
| We will use ABNF notation to define the Git bundle format\&. See \fBgitprotocol-common\fR(5) for the details\&. |
| .sp |
| A v2 bundle looks like this: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| bundle = signature *prerequisite *reference LF pack |
| signature = "# v2 git bundle" LF |
| |
| prerequisite = "\-" obj\-id SP comment LF |
| comment = *CHAR |
| reference = obj\-id SP refname LF |
| |
| pack = \&.\&.\&. ; packfile |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| A v3 bundle looks like this: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| bundle = signature *capability *prerequisite *reference LF pack |
| signature = "# v3 git bundle" LF |
| |
| capability = "@" key ["=" value] LF |
| prerequisite = "\-" obj\-id SP comment LF |
| comment = *CHAR |
| reference = obj\-id SP refname LF |
| key = 1*(ALPHA / DIGIT / "\-") |
| value = *(%01\-09 / %0b\-FF) |
| |
| pack = \&.\&.\&. ; packfile |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .SH "SEMANTICS" |
| .sp |
| A Git bundle consists of several parts\&. |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| "Capabilities", which are only in the v3 format, indicate functionality that the bundle requires to be read properly\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| "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\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| "References" record the tips of the history graph, iow, what the reader of the bundle CAN "git fetch" from it\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| "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\&. |
| .RE |
| .sp |
| 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\&. |
| .SS "Note on shallow clones and Git bundles" |
| .sp |
| 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\&. |
| .SH "CAPABILITIES" |
| .sp |
| Because there is no opportunity for negotiation, unknown capabilities cause \fIgit bundle\fR to abort\&. |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| \fBobject\-format\fR |
| specifies the hash algorithm in use, and can take the same values as the |
| \fBextensions\&.objectFormat\fR |
| configuration value\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| \fBfilter\fR |
| specifies an object filter as in the |
| \fB\-\-filter\fR |
| option in |
| \fBgit-rev-list\fR(1)\&. The resulting pack\-file must be marked as a \&.\fBpromisor\fR |
| pack\-file after it is unbundled\&. |
| .RE |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |
