diff options
Diffstat (limited to 'man5/gitformat-bundle.5')
| -rw-r--r-- | man5/gitformat-bundle.5 | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/man5/gitformat-bundle.5 b/man5/gitformat-bundle.5 new file mode 100644 index 000000000..7960ee99e --- /dev/null +++ b/man5/gitformat-bundle.5 @@ -0,0 +1,178 @@ +'\" 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: 08/18/2022 +.\" Manual: Git Manual +.\" Source: Git 2.37.2.382.g795ea8776b +.\" Language: English +.\" +.TH "GITFORMAT\-BUNDLE" "5" "08/18/2022" "Git 2\&.37\&.2\&.382\&.g795ea8" "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" lists 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 the shallow clone and a Git bundle" +.sp +Note that the prerequisites does 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 |