'\" t
.\"     Title: gitformat-bundle
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/05/2024
.\"    Manual: Git Manual
.\"    Source: Git 2.43.0.381.gb435a96ce8
.\"  Language: English
.\"
.TH "GITFORMAT\-BUNDLE" "5" "01/05/2024" "Git 2\&.43\&.0\&.381\&.gb435a9" "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
.sp
.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
.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
.\}
.sp
.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
\fB\&.promisor\fR
pack\-file after it is unbundled\&.
.RE
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite