This Git documentation is based on Git 2.53. The up to date Git reference can be found on https://git-scm.com/docs/
The Git bundle format is a format that represents both refs and Git objects. A bundle is a header in a format similar to the section called “git-show-ref(1)” followed by a pack in *.pack format.
The format is created and read by the the section called “git-bundle(1)” command, and supported by e.g. the section called “git-fetch(1)” and the section called “git-clone(1)”.
We will use ABNF notation to define the Git bundle format. See the section called “gitprotocol-common(5)” for the details.
A v2 bundle looks like this:
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
A v3 bundle looks like this:
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
A Git bundle consists of several parts.
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.
Because there is no opportunity for negotiation, unknown capabilities cause git bundle to abort.
Part of the the section called “git(1)” suite
Used by the section called “gitformat-commit-graph(5)” and the "MIDX" format (see the pack format documentation in the section called “gitformat-pack(5)”).
Some file formats in Git use a common concept of "chunks" to describe sections of the file. This allows structured access to a large file by scanning a small "table of contents" for the remaining data. This common format is used by the commit-graph and multi-pack-index files. See the multi-pack-index format in the section called “gitformat-pack(5)” and the commit-graph format in the section called “gitformat-commit-graph(5)” for how they use the chunks to describe structured data.
A chunk-based file format begins with some header information custom to that format. That header should include enough information to identify the file type, format version, and number of chunks in the file. From this information, that file can determine the start of the chunk-based region.
The chunk-based region starts with a table of contents describing where each chunk starts and ends. This consists of (C+1) rows of 12 bytes each, where C is the number of chunks. Consider the following table:
| Chunk ID (4 bytes) | Chunk Offset (8 bytes) | |--------------------|------------------------| | ID[0] | OFFSET[0] | | ... | ... | | ID[C] | OFFSET[C] | | 0x0000 | OFFSET[C+1] |
Each row consists of a 4-byte chunk identifier (ID) and an 8-byte offset. Each integer is stored in network-byte order.
The chunk identifier ID[i] is a label for the data stored within this file from OFFSET[i] (inclusive) to OFFSET[i+1] (exclusive). Thus, the size of the i`th chunk is equal to the difference between `OFFSET[i+1] and OFFSET[i]. This requires that the chunk data appears contiguously in the same order as the table of contents.
The final entry in the table of contents must be four zero bytes. This confirms that the table of contents is ending and provides the offset for the end of the chunk-based data.
Note: The chunk-based format expects that the file contains at least a trailing hash after OFFSET[C+1].
Functions for working with chunk-based file formats are declared in chunk-format.h. Using these methods provide extra checks that assist developers when creating new file formats.
To write a chunk-based file format, create a struct chunkfile by calling init_chunkfile() and pass a struct hashfile pointer. The caller is responsible for opening the hashfile and writing header information so the file format is identifiable before the chunk-based format begins.
Then, call add_chunk() for each chunk that is intended for writing. This populates the chunkfile with information about the order and size of each chunk to write. Provide a chunk_write_fn function pointer to perform the write of the chunk data upon request.
Call write_chunkfile() to write the table of contents to the hashfile followed by each of the chunks. This will verify that each chunk wrote the expected amount of data so the table of contents is correct.
Finally, call free_chunkfile() to clear the struct chunkfile data. The caller is responsible for finalizing the hashfile by writing the trailing hash and closing the file.
To read a chunk-based file format, the file must be opened as a memory-mapped region. The chunk-format API expects that the entire file is mapped as a contiguous memory region.
Initialize a struct chunkfile pointer with init_chunkfile(NULL).
After reading the header information from the beginning of the file, including the chunk count, call read_table_of_contents() to populate the struct chunkfile with the list of chunks, their offsets, and their sizes.
Extract the data information for each chunk using pair_chunk() or read_chunk():
After calling these methods, call free_chunkfile() to clear the struct chunkfile data. This will not close the memory-mapped region. Callers are expected to own that data for the timeframe the pointers into the region are needed.
These file formats use the chunk-format API, and can be used as examples for future formats:
Part of the the section called “git(1)” suite
The Git commit-graph stores a list of commit OIDs and some associated metadata, including:
These positional references are stored as unsigned 32-bit integers corresponding to the array position within the list of commit OIDs. Due to some special constants we use to track parents, we can store at most (1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits.
In order to allow extensions that add extra data to the graph, we organize the body into "chunks" and provide a binary lookup table at the beginning of the body. The header includes certain values, such as number of chunks and hash type.
All multi-byte numbers are in network byte order.
4-byte signature:
The signature is: {'C', 'G', 'P', 'H'}1-byte version number:
Currently, the only valid version is 1.1-byte Hash Version
We infer the hash length (H) from this value:
1 => SHA-1
2 => SHA-256
If the hash type does not match the repository's hash algorithm, the
commit-graph file should be ignored with a warning presented to the
user.1-byte number (C) of "chunks"
1-byte number (B) of base commit-graphs
We infer the length (H*B) of the Base Graphs chunk
from this value.(C + 1) * 12 bytes listing the table of contents for the chunks:
First 4 bytes describe the chunk id. Value 0 is a terminating label.
Other 8 bytes provide the byte-offset in current file for chunk to
start. (Chunks are ordered contiguously in the file, so you can infer
the length using the next chunk position if necessary.) Each chunk
ID appears at most once.The CHUNK LOOKUP matches the table of contents from the chunk-based file format, see linkgit:gitformat-chunk[5]
The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless otherwise specified.
The ith entry, F[i], stores the number of OIDs with first byte at most i. Thus F[255] stores the total number of commits (N).
The OIDs for all commits in the graph, sorted in ascending order.
This list of 4-byte values store the second through nth parents for all octopus merges. The second parent value in the commit data stores an array position within this list along with the most-significant bit on. Starting at that array position, iterate through this list of commit positions for the parents until reaching a value with the most-significant bit on. The other bits correspond to the position of the last parent.
It starts with header consisting of three unsigned 32-bit integers:
This list of H-byte hashes describe a set of B commit-graph files that form a commit-graph chain. The graph position for the ith commit in this file's OID Lookup chunk is equal to i plus the number of commits in all base graphs. If B is non-zero, this chunk must exist.
The Generation Data (GDA2) and Generation Data Overflow (GDO2) chunks have the number 2 in their chunk IDs because a previous version of Git wrote possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By changing the IDs, newer versions of Git will silently ignore those older chunks and write the new information without trusting the incorrect data.
Part of the the section called “git(1)” suite
All binary numbers are in network byte order. In a repository using the traditional SHA-1, checksums and object IDs (object names) mentioned below are all computed using SHA-1. Similarly, in SHA-256 repositories, these values are computed using SHA-256. Version 2 is described here unless stated otherwise.
A 12-byte header consisting of
4-byte signature:
The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache")4-byte version number: The current supported versions are 2, 3 and 4.
32-bit number of index entries.
Extensions
Extensions are identified by signature. Optional extensions can be ignored if Git does not understand them.
4-byte extension signature. If the first byte is 'A'..'Z' the extension is optional and can be ignored.
32-bit size of the extension
Extension data
Index entries are sorted in ascending order on the name field, interpreted as a string of unsigned bytes (i.e. memcmp() order, no localization, no special casing of directory separator '/'). Entries with the same name are sorted by their stage field.
An index entry typically represents a file. However, if sparse-checkout is enabled in cone mode (`core.sparseCheckoutCone` is enabled) and the `extensions.sparseIndex` extension is enabled, then the index may contain entries for directories outside of the sparse-checkout definition. These entries have mode `040000`, include the `SKIP_WORKTREE` bit, and the path ends in a directory separator.
32-bit ctime seconds, the last time a file's metadata changed this is stat(2) data
32-bit ctime nanosecond fractions this is stat(2) data
32-bit mtime seconds, the last time a file's data changed this is stat(2) data
32-bit mtime nanosecond fractions this is stat(2) data
32-bit dev this is stat(2) data
32-bit ino this is stat(2) data
32-bit mode, split into (high to low bits)
16-bit unused, must be zero
4-bit object type valid values in binary are 1000 (regular file), 1010 (symbolic link) and 1110 (gitlink)
3-bit unused, must be zero
9-bit unix permission. Only 0755 and 0644 are valid for regular files. Symbolic links and gitlinks have value 0 in this field.
32-bit uid this is stat(2) data
32-bit gid this is stat(2) data
32-bit file size This is the on-disk size from stat(2), truncated to 32-bit.
Object name for the represented object
A 16-bit 'flags' field split into (high to low bits)
1-bit assume-valid flag
1-bit extended flag (must be zero in version 2)
2-bit stage (during merge)
12-bit name length if the length is less than 0xFFF; otherwise 0xFFF is stored in this field.
(Version 3 or later) A 16-bit field, only applicable if the "extended flag" above is 1, split into (high to low bits).
1-bit reserved for future
1-bit skip-worktree flag (used by sparse checkout)
1-bit intent-to-add flag (used by "git add -N")
13-bit unused, must be zero
Entry path name (variable length) relative to top level directory (without leading slash). '/' is used as path separator. The special path components ".", ".." and ".git" (without quotes) are disallowed. Trailing slash is also disallowed.
The exact encoding is undefined, but the '.' and '/' characters are encoded in 7-bit ASCII and the encoding cannot contain a NUL byte (iow, this is a UNIX pathname).
(Version 4) In version 4, the entry path name is prefix-compressed relative to the path name for the previous entry (the very first entry is encoded as if the path name for the previous entry is an empty string). At the beginning of an entry, an integer N in the variable width encoding (the same encoding as the offset is encoded for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed by a NUL-terminated string S. Removing N bytes from the end of the path name for the previous entry, and replacing it with the string S yields the path name for this entry.
1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes while keeping the name NUL-terminated.
(Version 4) In version 4, the padding after the pathname does not exist.
Interpretation of index entries in split index mode is completely different. See below for details.
Since the index does not record entries for directories, the cache
entries cannot describe tree objects that already exist in the object
database for regions of the index that are unchanged from an existing
commit. The cache tree extension stores a recursive tree structure that
describes the trees that already exist and completely match sections of
the cache entries. This speeds up tree object generation from the index
for a new commit by only computing the trees that are "new" to that
commit. It also assists when comparing the index to another tree, such
as `HEAD^{tree}`, since sections of the index can be skipped when a tree
comparison demonstrates equality.The recursive tree structure uses nodes that store a number of cache entries, a list of subnodes, and an object ID (OID). The OID references the existing tree for that node, if it is known to exist. The subnodes correspond to subdirectories that themselves have cache tree nodes. The number of cache entries corresponds to the number of cache entries in the index that describe paths within that tree's directory.
The extension tracks the full directory structure in the cache tree extension, but this is generally smaller than the full cache entry list.
When a path is updated in index, Git invalidates all nodes of the recursive cache tree corresponding to the parent directories of that path. We store these tree nodes as being "invalid" by using "-1" as the number of cache entries. Invalid nodes still store a span of index entries, allowing Git to focus its efforts when reconstructing a full cache tree.
The signature for this extension is { 'T', 'R', 'E', 'E' }.A series of entries fill the entire extension; each of which consists of:
Object name for the object that would result from writing this span of index as a tree.
An entry can be in an invalidated state and is represented by having a negative number in the entry_count field. In this case, there is no object name and the next entry starts immediately after the newline. When writing an invalid entry, -1 should always be used as entry_count.
The entries are written out in the top-down, depth-first order. The first entry represents the root level of the repository, followed by the first subtree--let's call this A--of the root level (with its name relative to the root level), followed by the first subtree of A (with its name relative to A), and so on. The specified number of subtrees indicates when the current level of the recursive stack is complete.
A conflict is represented in the index as a set of higher stage entries. When a conflict is resolved (e.g. with "git add path"), these higher stage entries will be removed and a stage-0 entry with proper resolution is added.
When these higher stage entries are removed, they are saved in the resolve undo extension, so that conflicts can be recreated (e.g. with "git checkout -m"), in case users want to redo a conflict resolution from scratch.
The signature for this extension is { 'R', 'E', 'U', 'C' }.A series of entries fill the entire extension; each of which consists of:
In split index mode, the majority of index entries could be stored in a separate file. This extension records the changes to be made on top of that to produce the final index.
The signature for this extension is { 'l', 'i', 'n', 'k' }.The extension consists of:
An ewah-encoded replace bitmap, each bit represents an entry in the shared index. If a bit is set, its corresponding entry in the shared index will be replaced with an entry in this index file. All replaced entries are stored in sorted order in this index. The first "1" bit in the replace bitmap corresponds to the first index entry, the second "1" bit to the second entry and so on. Replaced entries may have empty path names to save space.
The remaining index entries after replaced ones will be added to the final index. These added entries are also sorted by entry name then stage.
Untracked cache saves the untracked file list and necessary data to
verify the cache. The signature for this extension is { 'U', 'N',
'T', 'R' }.The extension starts with
The remaining data of each directory block is grouped by type:
The file system monitor cache tracks files for which the core.fsmonitor
hook has told us about changes. The signature for this extension is
{ 'F', 'S', 'M', 'N' }.The extension starts with
The End of Index Entry (EOIE) is used to locate the end of the variable length index entries and the beginning of the extensions. Code can take advantage of this to quickly locate the index extensions without having to parse through all of the index entries.
Because it must be able to be loaded before the variable length cache
entries and other index extensions, this extension must be written last.
The signature for this extension is { 'E', 'O', 'I', 'E' }.The extension consists of:
Hash over the extension types and their sizes (but not their contents). E.g. if we have "TREE" extension that is N-bytes long, "REUC" extension that is M-bytes long, followed by "EOIE", then the hash would be:
Hash("TREE" + <binary-representation-of-N> +
"REUC" + <binary-representation-of-M>)The Index Entry Offset Table (IEOT) is used to help address the CPU
cost of loading the index by enabling multi-threading the process of
converting cache entries from the on-disk format to the in-memory format.
The signature for this extension is { 'I', 'E', 'O', 'T' }.The extension consists of:
When using sparse-checkout in cone mode, some entire directories within
the index can be summarized by pointing to a tree object instead of the
entire expanded list of paths within that tree. An index containing such
entries is a "sparse index". Index format versions 4 and less were not
implemented with such entries in mind. Thus, for these versions, an
index containing sparse directory entries will include this extension
with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
tools should avoid interacting with a sparse index unless they understand
this extension.Part of the the section called “git(1)” suite
$GIT_DIR/objects/pack/pack-.{pack,idx}
$GIT_DIR/objects/pack/pack-.rev
$GIT_DIR/objects/pack/pack-*.mtimes
$GIT_DIR/objects/pack/multi-pack-index
The Git pack format is how Git stores most of its primary repository data. Over the lifetime of a repository, loose objects (if any) and smaller packs are consolidated into larger pack(s). See the section called “git-gc(1)” and the section called “git-pack-objects(1)”.
The pack format is also used over-the-wire, see e.g. the section called “gitprotocol-v2(5)”, as well as being a part of other container formats in the case of the section called “gitformat-bundle(5)”.
In a repository using the traditional SHA-1, pack checksums, index checksums, and object IDs (object names) mentioned below are all computed using SHA-1. Similarly, in SHA-256 repositories, these values are computed using SHA-256.
CRC32 checksums are always computed over the entire packed object, including the header (n-byte type and length); the base object name or offset, if any; and the entire compressed object. The CRC32 algorithm used is that of zlib.
A header appears at the beginning and consists of the following:
4-byte signature:
The signature is: {'P', 'A', 'C', 'K'}4-byte version number (network byte order):
Git currently accepts version number 2 or 3 but
generates version 2 only.4-byte number of objects contained in the pack (network byte order)
Observation: we cannot have more than 4G versions ;-) and more than 4G objects in a pack.
The header is followed by a number of object entries, each of which looks like this:
(undeltified representation) n-byte type and length (3-bit type, (n-1)*7+4-bit length) compressed data
(deltified representation)
n-byte type and length (3-bit type, (n-1)*7+4-bit length)
base object name if OBJ_REF_DELTA or a negative relative
offset from the delta object's position in the pack if this
is an OBJ_OFS_DELTA object
compressed delta dataObservation: the length of each object is encoded in a variable length format and is not constrained to 32-bit or anything.
Valid object types are:
Type 5 is reserved for future expansion. Type 0 is invalid.
Unlike loose objects, packed objects do not have a prefix containing the type, size, and a NUL byte. These are not necessary because they can be determined by the n-byte type and length that prefixes the data and so they are omitted from the compressed and deltified data.
The computation of the object ID still uses this prefix by reconstructing it from the type and length as needed.
This document uses the following "size encoding" of non-negative integers: From each byte, the seven least significant bits are used to form the resulting integer. As long as the most significant bit is 1, this process continues; the byte with MSB 0 provides the last seven bits. The seven-bit chunks are concatenated. Later values are more significant.
This size encoding should not be confused with the "offset encoding", which is also used in this document.
When encoding the size of an undeltified object in a pack, the size is that of the uncompressed raw object. For deltified objects, it is the size of the uncompressed delta. The base object name or offset is not included in the size computation.
Conceptually there are only four object types: commit, tree, tag and blob. However to save space, an object could be stored as a "delta" of another "base" object. These representations are assigned new types ofs-delta and ref-delta, which is only valid in a pack file.
Both ofs-delta and ref-delta store the "delta" to be applied to another object (called base object) to reconstruct the object. The difference between them is, ref-delta directly encodes base object name. If the base object is in the same pack, ofs-delta encodes the offset of the base object in the pack instead.
The base object could also be deltified if it's in the same pack. Ref-delta can also refer to an object outside the pack (i.e. the so-called "thin pack"). When stored on disk however, the pack should be self contained to avoid cyclic dependency.
The delta data starts with the size of the base object and the size of the object to be reconstructed. These sizes are encoded using the size encoding from above. The remainder of the delta data is a sequence of instructions to reconstruct the object from the base object. If the base object is deltified, it must be converted to canonical form first. Each instruction appends more and more data to the target object until it's complete. There are two supported instructions so far: one for copying a byte range from the source object and one for inserting new data embedded in the instruction itself.
Each instruction has variable length. Instruction type is determined by the seventh bit of the first octet. The following diagrams follow the convention in RFC 1951 (Deflate compressed data format).
+----------+---------+---------+---------+---------+-------+-------+-------+ | 1xxxxxxx | offset1 | offset2 | offset3 | offset4 | size1 | size2 | size3 | +----------+---------+---------+---------+---------+-------+-------+-------+
This is the instruction format to copy a byte range from the source object. It encodes the offset to copy from and the number of bytes to copy. Offset and size are in little-endian order.
All offset and size bytes are optional. This is to reduce the instruction size when encoding small offsets or sizes. The first seven bits in the first octet determine which of the next seven octets is present. If bit zero is set, offset1 is present. If bit one is set offset2 is present and so on.
Note that a more compact instruction does not change offset and size encoding. For example, if only offset2 is omitted like below, offset3 still contains bits 16-23. It does not become offset2 and contains bits 8-15 even if it's right next to offset1.
+----------+---------+---------+ | 10000101 | offset1 | offset3 | +----------+---------+---------+
In its most compact form, this instruction only takes up one byte (0x80) with both offset and size omitted, which will have default values zero. There is another exception: size zero is automatically converted to 0x10000.
+----------+============+ | 0xxxxxxx | data | +----------+============+
This is the instruction to construct the target object without the base object. The following data is appended to the target object. The first seven bits of the first octet determine the size of data in bytes. The size must be non-zero.
The header is followed by sorted 24-byte entries, one entry per object in the pack. Each entry is:
4-byte network byte order integer, recording where the object is stored in the packfile as the offset from the beginning.
one object name of the appropriate size.
The file is concluded with a trailer:
A copy of the pack checksum at the end of the corresponding packfile.
Index checksum of all of the above.
Pack Idx file:
-- +--------------------------------+
fanout | fanout[0] = 2 (for example) |-.
table +--------------------------------+ |
| fanout[1] | |
+--------------------------------+ |
| fanout[2] | |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| fanout[255] = total objects |---.
-- +--------------------------------+ | |
main | offset | | |
index | object name 00XXXXXXXXXXXXXXXX | | |
table +--------------------------------+ | |
| offset | | |
| object name 00XXXXXXXXXXXXXXXX | | |
+--------------------------------+<+ |
.-| offset | |
| | object name 01XXXXXXXXXXXXXXXX | |
| +--------------------------------+ |
| | offset | |
| | object name 01XXXXXXXXXXXXXXXX | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| | offset | |
| | object name FFXXXXXXXXXXXXXXXX | |
--| +--------------------------------+<--+
trailer | | packfile checksum |
| +--------------------------------+
| | idxfile checksum |
| +--------------------------------+
.-------.
|
Pack file entry: <+packed object header:
1-byte size extension bit (MSB)
type (next 3 bit)
size0 (lower 4-bit)
n-byte sizeN (as long as MSB is set, each 7-bit)
size0..sizeN form 4+7+7+..+7 bit integer, size0
is the least significant part, and sizeN is the
most significant part.
packed object data:
If it is not DELTA, then deflated bytes (the size above
is the size before compression).
If it is REF_DELTA, then
base object name (the size above is the
size of the delta data that follows).
delta data, deflated.
If it is OFS_DELTA, then
n-byte offset (see below) interpreted as a negative
offset from the type-byte of the header of the
ofs-delta entry (the size above is the size of
the delta data that follows).
delta data, deflated.offset encoding:
n bytes with MSB set in all but the last one.
The offset is then the number constructed by
concatenating the lower 7 bit of each byte, and
for n >= 2 adding 2^7 + 2^14 + ... + 2^(7*(n-1))
to the result.have some other reorganizations. They have the format:
The same trailer as a v1 pack file:
A copy of the pack checksum at the end of the corresponding packfile.
Index checksum of all of the above.
A trailer, containing a:
checksum of the corresponding packfile, and
a checksum of all of the above.
All 4-byte numbers are in network order.
All 4-byte numbers are in network byte order.
The multi-pack-index files refer to multiple pack-files and loose objects.
In order to allow extensions that add extra data to the MIDX, we organize the body into "chunks" and provide a lookup table at the beginning of the body. The header includes certain length values, such as the number of packs, the number of base MIDX files, hash lengths and types.
All 4-byte numbers are in network order.
HEADER:
4-byte signature:
The signature is: {'M', 'I', 'D', 'X'}1-byte version number:
Git only writes or recognizes version 1.1-byte Object Id Version
We infer the length of object IDs (OIDs) from this value:
1 => SHA-1
2 => SHA-256
If the hash type does not match the repository's hash algorithm,
the multi-pack-index file should be ignored with a warning
presented to the user.1-byte number of "chunks"
1-byte number of base multi-pack-index files:
This value is currently always zero.4-byte number of pack files
CHUNK LOOKUP:
(C + 1) * 12 bytes providing the chunk offsets:
First 4 bytes describe chunk id. Value 0 is a terminating label.
Other 8 bytes provide offset in current file for chunk to start.
(Chunks are provided in file-order, so you can infer the length
using the next chunk position if necessary.)The CHUNK LOOKUP matches the table of contents from the chunk-based file format, see linkgit:gitformat-chunk[5].
The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless otherwise specified.
CHUNK DATA:
Packfile Names (ID: {'P', 'N', 'A', 'M'})
Store the names of packfiles as a sequence of NUL-terminated
strings. There is no extra padding between the filenames,
and they are listed in lexicographic order. The chunk itself
is padded at the end with between 0 and 3 NUL bytes to make the
chunk size a multiple of 4 bytes.Bitmapped Packfiles (ID: {'B', 'T', 'M', 'P'})
Stores a table of two 4-byte unsigned integers in network order.
Each table entry corresponds to a single pack (in the order that
they appear above in the `PNAM` chunk). The values for each table
entry are as follows:
- The first bit position (in pseudo-pack order, see below) to
contain an object from that pack.
- The number of bits whose objects are selected from that pack.OID Fanout (ID: {'O', 'I', 'D', 'F'})
The ith entry, F[i], stores the number of OIDs with first
byte at most i. Thus F[255] stores the total
number of objects.OID Lookup (ID: {'O', 'I', 'D', 'L'})
The OIDs for all objects in the MIDX are stored in lexicographic
order in this chunk.Object Offsets (ID: {'O', 'O', 'F', 'F'})
Stores two 4-byte values for every object.
1: The pack-int-id for the pack storing this object.
2: The offset within the pack.
If all offsets are less than 2^32, then the large offset chunk
will not exist and offsets are stored as in IDX v1.
If there is at least one offset value larger than 2^32-1, then
the large offset chunk must exist, and offsets larger than
2^31-1 must be stored in it instead. If the large offset chunk
exists and the 31st bit is on, then removing that bit reveals
the row in the large offsets containing the 8-byte offset of
this object.[Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'})
8-byte offsets into large packfiles.[Optional] Bitmap pack order (ID: {'R', 'I', 'D', 'X'})
A list of MIDX positions (one per object in the MIDX, num_objects in
total, each a 4-byte unsigned integer in network byte order), sorted
according to their relative bitmap/pseudo-pack positions.TRAILER:
Index checksum of the above contents.
Similar to the pack-based reverse index, the multi-pack index can also be used to generate a reverse index.
Instead of mapping between offset, pack-, and index position, this reverse index maps between an object's position within the MIDX, and that object's position within a pseudo-pack that the MIDX describes (i.e., the ith entry of the multi-pack reverse index holds the MIDX position of ith object in pseudo-pack order).
To clarify the difference between these orderings, consider a multi-pack reachability bitmap (which does not yet exist, but is what we are building towards here). Each bit needs to correspond to an object in the MIDX, and so we need an efficient mapping from bit position to MIDX position.
One solution is to let bits occupy the same position in the oid-sorted index stored by the MIDX. But because oids are effectively random, their resulting reachability bitmaps would have no locality, and thus compress poorly. (This is the reason that single-pack bitmaps use the pack ordering, and not the .idx ordering, for the same purpose.)
So we'd like to define an ordering for the whole MIDX based around pack ordering, which has far better locality (and thus compresses more efficiently). We can think of a pseudo-pack created by the concatenation of all of the packs in the MIDX. E.g., if we had a MIDX with three packs (a, b, c), with 10, 15, and 20 objects respectively, we can imagine an ordering of the objects like:
|a,0|a,1|...|a,9|b,0|b,1|...|b,14|c,0|c,1|...|c,19|
where the ordering of the packs is defined by the MIDX's pack list, and then the ordering of objects within each pack is the same as the order in the actual packfile.
Given the list of packs and their counts of objects, you can naïvely reconstruct that pseudo-pack ordering (e.g., the object at position 27 must be (c,1) because packs "a" and "b" consumed 25 of the slots). But there's a catch. Objects may be duplicated between packs, in which case the MIDX only stores one pointer to the object (and thus we'd want only one slot in the bitmap).
Callers could handle duplicates themselves by reading objects in order of their bit-position, but that's linear in the number of objects, and much too expensive for ordinary bitmap lookups. Building a reverse index solves this, since it is the logical inverse of the index, and that index has already removed duplicates. But, building a reverse index on the fly can be expensive. Since we already have an on-disk format for pack-based reverse indexes, let's reuse it for the MIDX's pseudo-pack, too.
Objects from the MIDX are ordered as follows to string together the pseudo-pack. Let pack(o) return the pack from which o was selected by the MIDX, and define an ordering of packs based on their numeric ID (as stored by the MIDX). Let offset(o) return the object offset of o within pack(o). Then, compare o1 and o2 as follows:
If one of pack(o1) and pack(o2) is preferred and the other is not, then the preferred one sorts first.
(This is a detail that allows the MIDX bitmap to determine which pack should be used by the pack-reuse mechanism, since it can ask the MIDX for the pack containing the object at bit position 0).
In short, a MIDX's pseudo-pack is the de-duplicated concatenation of objects in packs stored by the MIDX, laid out in pack order, and the packs arranged in MIDX order (with the preferred pack coming first).
The MIDX's reverse index is stored in the optional RIDX chunk within the MIDX itself.
The Bitmapped Packfiles (BTMP) chunk encodes additional information about the objects in the multi-pack index's reachability bitmap. Recall that objects from the MIDX are arranged in "pseudo-pack" order (see above) for reachability bitmaps.
From the example above, suppose we have packs "a", "b", and "c", with 10, 15, and 20 objects, respectively. In pseudo-pack order, those would be arranged as follows:
|a,0|a,1|...|a,9|b,0|b,1|...|b,14|c,0|c,1|...|c,19|
When working with single-pack bitmaps (or, equivalently, multi-pack reachability bitmaps with a preferred pack), the section called “git-pack-objects(1)” performs verbatim reuse, attempting to reuse chunks of the bitmapped or preferred packfile instead of adding objects to the packing list.
When a chunk of bytes is reused from an existing pack, any objects contained therein do not need to be added to the packing list, saving memory and CPU time. But a chunk from an existing packfile can only be reused when the following conditions are met:
The BTMP chunk encodes the necessary information in order to implement multi-pack reuse over a set of packfiles as described above. Specifically, the BTMP chunk encodes three pieces of information (all 32-bit unsigned integers in network byte-order) for each packfile p that is stored in the MIDX, as follows:
For example, the BTMP chunk corresponding to the above example (with packs a, b, and c) would look like:
bitmap_pos | bitmap_nr | |
packfile a | 0 | 10 |
packfile b | 10 | 15 |
packfile c | 25 | 20 |
With this information in place, we can treat each packfile as individually reusable in the same fashion as verbatim pack reuse is performed on individual packs prior to the implementation of the BTMP chunk.
The cruft packs feature offer an alternative to Git's traditional mechanism of removing unreachable objects. This document provides an overview of Git's pruning mechanism, and how a cruft pack can be used instead to accomplish the same.
To remove unreachable objects from your repository, Git offers git repack -Ad (see the section called “git-repack(1)”). Quoting from the documentation:
[...] unreachable objects in a previous pack become loose, unpacked objects, instead of being left in the old pack. [...] loose unreachable objects will be pruned according to normal expiry rules with the next 'git gc' invocation.
Unreachable objects aren't removed immediately, since doing so could race with an incoming push which may reference an object which is about to be deleted. Instead, those unreachable objects are stored as loose objects and stay that way until they are older than the expiration window, at which point they are removed by the section called “git-prune(1)”.
Git must store these unreachable objects loose in order to keep track of their per-object mtimes. If these unreachable objects were written into one big pack, then either freshening that pack (because an object contained within it was re-written) or creating a new pack of unreachable objects would cause the pack's mtime to get updated, and the objects within it would never leave the expiration window. Instead, objects are stored loose in order to keep track of the individual object mtimes and avoid a situation where all cruft objects are freshened at once.
This can lead to undesirable situations when a repository contains many unreachable objects which have not yet left the grace period. Having large directories in the shards of .git/objects can lead to decreased performance in the repository. But given enough unreachable objects, this can lead to inode starvation and degrade the performance of the whole system. Since we can never pack those objects, these repositories often take up a large amount of disk space, since we can only zlib compress them, but not store them in delta chains.
A cruft pack eliminates the need for storing unreachable objects in a loose state by including the per-object mtimes in a separate file alongside a single pack containing all loose objects.
A cruft pack is written by git repack --cruft when generating a new pack. the section called “git-pack-objects(1)”'s --cruft option. Note that git repack --cruft is a classic all-into-one repack, meaning that everything in the resulting pack is reachable, and everything else is unreachable. Once written, the --cruft option instructs git repack to generate another pack containing only objects not packed in the previous step (which equates to packing all unreachable objects together). This progresses as follows:
This mode is invoked internally by the section called “git-repack(1)” when instructed to write a cruft pack. Crucially, the set of in-core kept packs is exactly the set of packs which will not be deleted by the repack; in other words, they contain all of the repository's reachable objects.
When a repository already has a cruft pack, git repack --cruft typically only adds objects to it. An exception to this is when git repack is given the --cruft-expiration option, which allows the generated cruft pack to omit expired objects instead of waiting for the section called “git-gc(1)” to expire those objects later on.
It is the section called “git-gc(1)” that is typically responsible for removing expired unreachable objects.
Notable alternatives to this design include:
On the location of mtime data, a new auxiliary file tied to the pack was chosen to avoid complicating the .idx format. If the .idx format were ever to gain support for optional chunks of data, it may make sense to consolidate the .mtimes format into the .idx itself.
Part of the the section called “git(1)” suite
Git uses cryptographic signatures in various places, currently objects (tags, commits, mergetags) and transactions (pushes). In every case, the command which is about to create an object or transaction determines a payload from that, calls an external program to obtain a detached signature for the payload (gpg -bsa in the case of PGP signatures), and embeds the signature into the object or transaction.
Signatures begin with an "ASCII Armor" header line and end with a tail line, which differ depending on signature type (as selected by gpg.format, see the section called “git-config(1)”). These are, for gpg.format values:
Signatures sometimes appear as a part of the normal payload (e.g. a signed tag has the signature block appended after the payload that the signature applies to), and sometimes appear in the value of an object header (e.g. a merge commit that merged a signed tag would have the entire tag contents on its "mergetag" header). In the case of the latter, the usual multi-line formatting rule for object headers applies. I.e. the second and subsequent lines are prefixed with a SP to signal that the line is continued from the previous line.
This is even true for an originally empty line. In the following examples, the end of line that ends with a whitespace letter is highlighted with a $ sign; if you are trying to recreate these example by hand, do not cut and paste them--they are there primarily to highlight extra whitespace at the end of some lines.
The signed payload and the way the signature is embedded depends on the type of the object resp. transaction.
object 04b871796dc0420f8e7561a895b52484b701d51a type commit tag signedtag tagger C O Mitter <committer@example.com> 1465981006 +0000 signed tag signed tag message body -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= =jpXa -----END PGP SIGNATURE-----
gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 gpg: Good signature from "Eris Discordia <discord@example.net>" gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 object 04b871796dc0420f8e7561a895b52484b701d51a type commit tag signedtag tagger C O Mitter <committer@example.com> 1465981006 +0000 signed tag signed tag message body
tree eebfed94e75e7760540d1485c740902590a00332 parent 04b871796dc0420f8e7561a895b52484b701d51a author A U Thor <author@example.com> 1465981137 +0000 committer C O Mitter <committer@example.com> 1465981137 +0000 gpgsig -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 $ iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/ HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7 DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4 HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1 EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I= =jKHM -----END PGP SIGNATURE----- signed commit signed commit message body
gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189 gpg: Good signature from "Eris Discordia <discord@example.net>" gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 tree eebfed94e75e7760540d1485c740902590a00332 parent 04b871796dc0420f8e7561a895b52484b701d51a author A U Thor <author@example.com> 1465981137 +0000 committer C O Mitter <committer@example.com> 1465981137 +0000 signed commit signed commit message body
tree c7b1cff039a93f3600a1d18b82d26688668c7dea parent c33429be94b5f2d3ee9b0adad223f877f174b05d parent 04b871796dc0420f8e7561a895b52484b701d51a author A U Thor <author@example.com> 1465982009 +0000 committer C O Mitter <committer@example.com> 1465982009 +0000 mergetag object 04b871796dc0420f8e7561a895b52484b701d51a type commit tag signedtag tagger C O Mitter <committer@example.com> 1465981006 +0000 $ signed tag $ signed tag message body -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 $ iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= =jpXa -----END PGP SIGNATURE----- Merge tag 'signedtag' into downstream signed tag signed tag message body # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 # gpg: Good signature from "Eris Discordia <discord@example.net>" # gpg: WARNING: This key is not certified with a trusted signature! # gpg: There is no indication that the signature belongs to the owner. # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
commit 9863f0c76ff78712b6800e199a46aa56afbcbd49
merged tag 'signedtag'
gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
gpg: Good signature from "Eris Discordia <discord@example.net>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
Merge: c33429b 04b8717
Author: A U Thor <author@example.com>
Date: Wed Jun 15 09:13:29 2016 +0000
Merge tag 'signedtag' into downstream
signed tag
signed tag message body
# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
# gpg: Good signature from "Eris Discordia <discord@example.net>"
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189Part of the the section called “git(1)” suite
This document aims to describe some advanced concepts related to packing in Git.
Many concepts are currently described scattered between manual pages of various Git commands, including the section called “git-pack-objects(1)”, the section called “git-repack(1)”, and others, as well as the section called “gitformat-pack(5)”, and parts of the Documentation/technical tree.
There are many aspects of packing in Git that are not covered in this document that instead live in the aforementioned areas. Over time, those scattered bits may coalesce into this document.
Pseudo-merge bitmaps are considered an experimental feature, so the configuration and many of the ideas are subject to change.
Reachability bitmaps are most efficient when we have on-disk stored bitmaps for one or more of the starting points of a traversal. For this reason, Git prefers storing bitmaps for commits at the tips of refs, because traversals tend to start with those points.
But if you have a large number of refs, it's not feasible to store a bitmap for every ref tip. It takes up space, and just OR-ing all of those bitmaps together is expensive.
One way we can deal with that is to create bitmaps that represent groups of refs. When a traversal asks about the entire group, then we can use this single bitmap instead of considering each ref individually. Because these bitmaps represent the set of objects which would be reachable in a hypothetical merge of all of the commits, we call them pseudo-merge bitmaps.
A "pseudo-merge bitmap" is used to refer to a pair of bitmaps, as follows:
Pseudo-merge bitmaps can accelerate bitmap traversals when all commits for a given pseudo-merge are listed on either side of the traversal, either directly (by explicitly asking for them as part of the HAVES or WANTS) or indirectly (by encountering them during a fill-in traversal).
For example, suppose there exists a pseudo-merge bitmap with a large number of commits, all of which are listed in the WANTS section of some bitmap traversal query. When pseudo-merge bitmaps are enabled, the bitmap machinery can quickly determine there is a pseudo-merge which satisfies some subset of the wanted objects on either side of the query. Then, we can inflate the EWAH-compressed bitmap, and OR it in to the resulting bitmap. By contrast, without pseudo-merge bitmaps, we would have to repeat the decompression and OR-ing step over a potentially large number of individual bitmaps, which can take proportionally more time.
Another benefit of pseudo-merges arises when there is some combination of (a) a large number of references, with (b) poor bitmap coverage, and (c) deep, nested trees, making fill-in traversal relatively expensive. For example, suppose that there are a large enough number of tags where bitmapping each of the tags individually is infeasible. Without pseudo-merge bitmaps, computing the result of, say, git rev-list --use-bitmap-index --count --objects --tags would likely require a large amount of fill-in traversal. But when a large quantity of those tags are stored together in a pseudo-merge bitmap, the bitmap machinery can take advantage of the fact that we only care about the union of objects reachable from all of those tags, and answer the query much faster.
Reference tips are grouped into different pseudo-merge groups according to two criteria. A reference name matches one or more of the defined pseudo-merge patterns, and optionally one or more capture groups within that pattern which further partition the group.
Within a group, commits may be considered "stable", or "unstable" depending on their age. These are adjusted by setting the bitmapPseudoMerge.<name>.stableThreshold and bitmapPseudoMerge.<name>.threshold configuration values, respectively.
All stable commits are grouped into pseudo-merges of equal size (bitmapPseudoMerge.<name>.stableSize). If the stableSize configuration is set to, say, 100, then the first 100 commits (ordered by committer date) which are older than the stableThreshold value will form one group, the next 100 commits will form another group, and so on.
Among unstable commits, the pseudo-merge machinery will attempt to combine older commits into large groups as opposed to newer commits which will appear in smaller groups. This is based on the heuristic that references whose tip commit is older are less likely to be modified to point at a different commit than a reference whose tip commit is newer.
The size of groups is determined by a power-law decay function, and the decay parameter roughly corresponds to "k" in f(n) = C*n^(-k/100), where f(n) describes the size of the n-th pseudo-merge group. The sample rate controls what percentage of eligible commits are considered as candidates. The threshold parameter indicates the minimum age (so as to avoid including too-recent commits in a pseudo-merge group, making it less likely to be valid). The "maxMerges" parameter sets an upper-bound on the number of pseudo-merge commits an individual group
The "stable"-related parameters control "stable" pseudo-merge groups, comprised of a fixed number of commits which are older than the configured "stable threshold" value and may be grouped together in chunks of "stableSize" in order of age.
The exact configuration for pseudo-merges is as follows:
The configuration options in bitmapPseudoMerge.* are considered EXPERIMENTAL and may be subject to change or be removed entirely in the future. For more information about the pseudo-merge bitmap feature, see the "Pseudo-merge bitmaps" section of the section called “gitpacking(7)”.
Regular expression used to match reference names. Commits pointed to by references matching this pattern (and meeting the below criteria, like bitmapPseudoMerge.<name>.sampleRate and bitmapPseudoMerge.<name>.threshold) will be considered for inclusion in a pseudo-merge bitmap.
Commits are grouped into pseudo-merge groups based on whether or not any reference(s) that point at a given commit match the pattern, which is an extended regular expression.
Within a pseudo-merge group, commits may be further grouped into sub-groups based on the capture groups in the pattern. These sub-groupings are formed from the regular expressions by concatenating any capture groups from the regular expression, with a - dash in between.
For example, if the pattern is refs/tags/, then all tags (provided they meet the below criteria) will be considered candidates for the same pseudo-merge group. However, if the pattern is instead refs/remotes/([0-9])+/tags/, then tags from different remotes will be grouped into separate pseudo-merge groups, based on the remote number.
Determines the rate at which consecutive pseudo-merge bitmap groups decrease in size. Must be non-negative. This parameter can be thought of as k in the function f(n) = C * n^-k, where f(n) is the size of the `n`th group.
Setting the decay rate equal to 0 will cause all groups to be the same size. Setting the decay rate equal to 1 will cause the n`th group to be `1/n the size of the initial group. Higher values of the decay rate cause consecutive groups to shrink at an increasing rate. The default is 1.
If all groups are the same size, it is possible that groups containing newer commits will be able to be used less often than earlier groups, since it is more likely that the references pointing at newer commits will be updated more often than a reference pointing at an old commit.
Determines the maximum number of pseudo-merge commits among which commits may be distributed.
For pseudo-merge groups whose pattern does not contain any capture groups, this setting is applied for all commits matching the regular expression. For patterns that have one or more capture groups, this setting is applied for each distinct capture group.
For example, if your capture group is refs/tags/, then this setting will distribute all tags into a maximum of maxMerges pseudo-merge commits. However, if your capture group is, say, refs/remotes/([0-9]+)/tags/, then this setting will be applied to each remote's set of tags individually.
Must be non-negative. The default value is 64.
Determines the minimum age of commits (among reference tips, as above, however stable commits are still considered candidates even when they have been covered by a bitmap) which are candidates for a stable a pseudo-merge bitmap. The default is 1.month.ago.
Setting this threshold to a smaller value (e.g., 1.week.ago) will cause more stable groups to be generated (which impose a one-time generation cost) but those groups will likely become stale over time. Using a larger value incurs the opposite penalty (fewer stable groups which are more useful).
Suppose that you have a repository with a large number of references, and you want a bare-bones configuration of pseudo-merge bitmaps that will enhance bitmap coverage of the refs/ namespace. You may start with a configuration like so:
[bitmapPseudoMerge "all"]
pattern = "refs/"
threshold = now
stableThreshold = never
sampleRate = 100
maxMerges = 64This will create pseudo-merge bitmaps for all references, regardless of their age, and group them into 64 pseudo-merge commits.
If you wanted to separate tags from branches when generating pseudo-merge commits, you would instead define the pattern with a capture group, like so:
[bitmapPseudoMerge "all"]
pattern = "refs/(heads/tags)/"Suppose instead that you are working in a fork-network repository, with each fork specified by some numeric ID, and whose refs reside in refs/virtual/NNN/ (where NNN is the numeric ID corresponding to some fork) in the network. In this instance, you may instead write something like:
[bitmapPseudoMerge "all"]
pattern = "refs/virtual/([0-9]+)/(heads|tags)/"
threshold = now
stableThreshold = never
sampleRate = 100
maxMerges = 64Which would generate pseudo-merge group identifiers like "1234-heads", and "5678-tags" (for branches in fork "1234", and tags in remote "5678", respectively).
Part of the the section called “git(1)” suite
this document describes capabilities for versions 0 and 1 of the pack protocol. For version 2, please refer to the the section called “gitprotocol-v2(5)” doc.
Servers SHOULD support all capabilities defined in this document.
On the very first line of the initial server response of either receive-pack and upload-pack the first reference is followed by a NUL byte and then a list of space delimited server capabilities. These allow the server to declare what it can and cannot support to the client.
Client will then send a space separated list of capabilities it wants to be in effect. The client MUST NOT ask for capabilities the server did not say it supports.
Server MUST diagnose and abort if capabilities it does not understand were sent. Server MUST NOT ignore capabilities that client requested and server advertised. As a consequence of these rules, server MUST NOT advertise capabilities it does not understand.
The atomic, report-status, report-status-v2, delete-refs, quiet, and push-cert capabilities are sent and recognized by the receive-pack (push to server) process.
The ofs-delta and side-band-64k capabilities are sent and recognized by both upload-pack and receive-pack protocols. The agent and session-id capabilities may optionally be sent in both protocols.
All other capabilities are only recognized by the upload-pack (fetch from server) process.
The multi_ack capability allows the server to return "ACK obj-id continue" as soon as it finds a commit that it can use as a common base, between the client's wants and the client's have set.
By sending this early, the server can potentially head off the client from walking any further down that particular branch of the client's repository history. The client may still need to walk down other branches, sending have lines for those, until the server has a complete cut across the DAG, or the client has said "done".
Without multi_ack, a client sends have lines in --date-order until the server has found a common base. That means the client will send have lines that are already known by the server to be common, because they overlap in time with another branch on which the server hasn't found a common base yet.
For example suppose the client has commits in caps that the server doesn't and the server has commits in lower case that the client doesn't, as in the following diagram:
+---- u ---------------------- x
/ +----- y
/ /
a -- b -- c -- d -- E -- F
\
+--- Q -- R -- SIf the client wants x,y and starts out by saying have F,S, the server doesn't know what F,S is. Eventually the client says "have d" and the server sends "ACK d continue" to let the client know to stop walking down that line (so don't send c-b-a), but it's not done yet, it needs a base for x. The client keeps going with S-R-Q, until a gets reached, at which point the server has a clear base and it all ends.
Without multi_ack the client would have sent that c-b-a chain anyway, interleaved with S-R-Q.
This is an extension of multi_ack that permits the client to better understand the server's in-memory state. See the section called “gitprotocol-pack(5)”, section "Packfile Negotiation" for more information.
This capability should only be used with the smart HTTP protocol. If multi_ack_detailed and no-done are both present, then the sender is free to immediately send a pack following its first "ACK obj-id ready" message.
Without no-done in the smart HTTP protocol, the server session would end and the client has to make another trip to send "done" before the server can send the pack. no-done removes the last round and thus slightly reduces latency.
A thin pack is one with deltas which reference base objects not contained within the pack (but are known to exist at the receiving end). This can reduce the network traffic significantly, but it requires the receiving end to know how to "thicken" these packs by adding the missing bases to the pack.
The upload-pack server advertises thin-pack when it can generate and send a thin pack. A client requests the thin-pack capability when it understands how to "thicken" it, notifying the server that it can receive such a pack. A client MUST NOT request the thin-pack capability if it cannot turn a thin pack into a self-contained pack.
Receive-pack, on the other hand, is assumed by default to be able to handle thin packs, but can ask the client not to use the feature by advertising the no-thin capability. A client MUST NOT send a thin pack if the server advertises the no-thin capability.
The reasons for this asymmetry are historical. The receive-pack program did not exist until after the invention of thin packs, so historically the reference implementation of receive-pack always understood thin packs. Adding no-thin later allowed receive-pack to disable the feature in a backwards-compatible manner.
This capability means that the server can send, and the client can understand, multiplexed progress reports and error info interleaved with the packfile itself.
These two options are mutually exclusive. A modern client always favors side-band-64k.
Either mode indicates that the packfile data will be streamed broken up into packets of up to either 1000 bytes in the case of side_band, or 65520 bytes in the case of side_band_64k. Each packet is made up of a leading 4-byte pkt-line length of how much data is in the packet, followed by a 1-byte stream code, followed by the actual data.
The stream code can be one of:
1 - pack data 2 - progress messages 3 - fatal error message just before stream aborts
The "side-band-64k" capability came about as a way for newer clients that can handle much larger packets to request packets that are actually crammed nearly full, while maintaining backward compatibility for the older clients.
Further, with side-band and its up to 1000-byte messages, it's actually 999 bytes of payload and 1 byte for the stream code. With side-band-64k, same deal, you have up to 65519 bytes of data and 1 byte for the stream code.
The client MUST send only one of "side-band" and "side- band-64k". The server MUST diagnose it as an error if client requests both.
The server can send, and the client can understand, PACKv2 with delta referring to its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile.
The server may optionally send a capability of the form agent=X to notify the client that the server is running version X. The client may optionally return its own agent string by responding with an agent=Y capability (but it MUST NOT do so if the server did not mention the agent capability). The X and Y strings may contain any printable ASCII characters except space (i.e., the byte range 32 < x < 127), and are typically of the form "package/version" (e.g., "git/1.8.3.1"). The agent strings are purely informative for statistics and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features.
This capability, which takes a hash algorithm as an argument, indicates that the server supports the given hash algorithms. It may be sent multiple times; if so, the first one given is the one used in the ref advertisement.
When provided by the client, this indicates that it intends to use the given hash algorithm to communicate. The algorithm provided must be one that the server supports.
If this capability is not provided, it is assumed that the only supported algorithm is SHA-1.
This parameterized capability is used to inform the receiver which symbolic ref points to which ref; for example, "symref=HEAD:refs/heads/master" tells the receiver that HEAD points to master. This capability can be repeated to represent multiple symrefs.
Servers SHOULD include this capability for the HEAD symref if it is one of the refs being sent.
Clients MAY use the parameters from this capability to select the proper initial branch when cloning a repository.
This capability adds "deepen", "shallow" and "unshallow" commands to the fetch-pack/upload-pack protocol so clients can request shallow clones.
This capability adds "deepen-since" command to fetch-pack/upload-pack protocol so the client can request shallow clones that are cut at a specific time, instead of depth. Internally it's equivalent of doing "rev-list --max-age=<timestamp>" on the server side. "deepen-since" cannot be used with "deepen".
This capability adds "deepen-not" command to fetch-pack/upload-pack protocol so the client can request shallow clones that are cut at a specific revision, instead of depth. Internally it's equivalent of doing "rev-list --not <rev>" on the server side. "deepen-not" cannot be used with "deepen", but can be used with "deepen-since".
If this capability is requested by the client, the semantics of "deepen" command is changed. The "depth" argument is the depth from the current shallow boundary, instead of the depth from remote refs.
The client was started with "git clone -q" or something similar, and doesn't want that side band 2. Basically the client just says "I do not wish to receive stream 2 on sideband, so do not send it to me, and if you did, I will drop it on the floor anyway". However, the sideband channel 3 is still used for error responses.
The include-tag capability is about sending annotated tags if we are sending objects they point to. If we pack an object to the client, and a tag object points exactly at that object, we pack the tag object too. In general this allows a client to get all new annotated tags when it fetches a branch, in a single network connection.
Clients MAY always send include-tag, hardcoding it into a request when the server advertises this capability. The decision for a client to request include-tag only has to do with the client's desires for tag data, whether or not a server had advertised objects in the refs/tags/* namespace.
Servers MUST pack the tags if their referent is packed and the client has requested include-tags.
Clients MUST be prepared for the case where a server has ignored include-tag and has not actually sent tags in the pack. In such cases the client SHOULD issue a subsequent fetch to acquire the tags that include-tag would have otherwise given the client.
The server SHOULD send include-tag, if it supports it, regardless of whether or not there are tags available.
The receive-pack process can receive a report-status capability, which tells it that the client wants a report of what happened after a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server will respond with whether the packfile unpacked successfully and if each reference was updated successfully. If any of those were not successful, it will send back an error message. See the section called “gitprotocol-pack(5)” for example messages.
Capability report-status-v2 extends capability report-status by adding new "option" directives in order to support reference rewritten by the "proc-receive" hook. The "proc-receive" hook may handle a command for a pseudo-reference which may create or update a reference with different name, new-oid, and old-oid. While the capability report-status cannot report for such case. See the section called “gitprotocol-pack(5)” for details.
If the server sends back the delete-refs capability, it means that it is capable of accepting a zero-id value as the target value of a reference update. It is not sent back by the client, it simply informs the client that it can be sent zero-id values to delete references.
If the receive-pack server advertises the quiet capability, it is capable of silencing human-readable progress output which otherwise may be shown when processing the received pack. A send-pack client should respond with the quiet capability to suppress server-side progress reporting if the local progress reporting is also being suppressed (e.g., via push -q, or if stderr does not go to a tty).
If the server sends the atomic capability it is capable of accepting atomic pushes. If the pushing client requests this capability, the server will update the refs in one atomic transaction. Either all refs are updated or none.
If the server sends the push-options capability it is able to accept push options after the update commands have been sent, but before the packfile is streamed. If the pushing client requests this capability, the server will pass the options to the pre- and post- receive hooks that process this push request.
If the upload-pack server advertises this capability, fetch-pack may send "want" lines with object names that exist at the server but are not advertised by upload-pack. For historical reasons, the name of this capability contains "sha1". Object names are always given using the object format negotiated through the object-format capability.
If the upload-pack server advertises this capability, fetch-pack may send "want" lines with object names that exist at the server but are not advertised by upload-pack. For historical reasons, the name of this capability contains "sha1". Object names are always given using the object format negotiated through the object-format capability.
The receive-pack server that advertises this capability is willing to accept a signed push certificate, and asks the <nonce> to be included in the push certificate. A send-pack client MUST NOT send a push-cert packet unless the receive-pack server advertises this capability.
If the upload-pack server advertises the filter capability, fetch-pack may send "filter" commands to request a partial clone or partial fetch and request that the server omit various objects from the packfile.
The server may advertise a session ID that can be used to identify this process across multiple requests. The client may advertise its own session ID back to the server as well.
Session IDs should be unique to a given process. They must fit within a packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see api-trace2 for details), but this may change and users of the session ID should not rely on this fact.
Part of the the section called “git(1)” suite
This document defines things common to various over-the-wire protocols and file formats used in Git.
ABNF notation as described by RFC 5234 is used within the protocol documents, except the following replacement core rules are used:
HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
We also define the following common rules:
NUL = %x00 zero-id = 40*"0" obj-id = 40*(HEXDIGIT) refname = "HEAD" refname /= "refs/" <see discussion below>
A refname is a hierarchical octet string beginning with "refs/" and not violating the git-check-ref-format command's validation rules. More specifically, they:
Much (but not all) of the payload is described around pkt-lines.
A pkt-line is a variable length binary string. The first four bytes of the line, the pkt-len, indicates the total length of the line, in hexadecimal. The pkt-len includes the 4 bytes used to contain the length's hexadecimal representation.
A pkt-line MAY contain binary data, so implementors MUST ensure pkt-line parsing/formatting routines are 8-bit clean.
A non-binary line SHOULD BE terminated by an LF, which if present MUST be included in the total length. Receivers MUST treat pkt-lines with non-binary data the same whether or not they contain the trailing LF (stripping the LF if present, and not complaining when it is missing).
The maximum length of a pkt-line's data component is 65516 bytes. Implementations MUST NOT send pkt-line whose length exceeds 65520 (65516 bytes of payload + 4 bytes of length data).
Implementations SHOULD NOT send an empty pkt-line ("0004").
A pkt-line with a length field of 0 ("0000"), called a flush-pkt, is a special case and MUST be handled differently than an empty pkt-line ("0004").
pkt-line = data-pkt / flush-pkt data-pkt = pkt-len pkt-payload pkt-len = 4*(HEXDIG) pkt-payload = (pkt-len - 4)*(OCTET) flush-pkt = "0000"
Examples (as C-style strings):
pkt-line actual value --------------------------------- "0006a\n" "a\n" "0005a" "a" "000bfoobar\n" "foobar\n" "0004" ""
Part of the the section called “git(1)” suite
Git supports two HTTP based transfer protocols. A "dumb" protocol which requires only a standard HTTP server on the server end of the connection, and a "smart" protocol which requires a Git aware CGI (or server module). This document describes both protocols.
As a design feature smart clients can automatically upgrade "dumb" protocol URLs to smart URLs. This permits all users to have the same published URL, and the peers automatically select the most efficient transport available to them.
URLs for Git repositories accessed by HTTP use the standard HTTP URL syntax documented by RFC 1738, so they are of the form:
http://<host>:<port>/<path>?<searchpart>
Within this documentation the placeholder $GIT_URL will stand for the http:// repository URL entered by the end-user.
Servers SHOULD handle all requests to locations matching $GIT_URL, as both the "smart" and "dumb" HTTP protocols used by Git operate by appending additional path components onto the end of the user supplied $GIT_URL string.
An example of a dumb client requesting a loose object:
$GIT_URL: http://example.com:8080/git/repo.git URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
An example of a smart request to a catch-all gateway:
$GIT_URL: http://example.com/daemon.cgi?svc=git&q= URL request: http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack
An example of a request to a submodule:
$GIT_URL: http://example.com/git/repo.git/path/submodule.git URL request: http://example.com/git/repo.git/path/submodule.git/info/refs
Clients MUST strip a trailing /, if present, from the user supplied $GIT_URL string to prevent empty path tokens (//) from appearing in any URL sent to a server. Compatible clients MUST expand $GIT_URL/info/refs as foo/info/refs and not foo//info/refs.
Standard HTTP authentication is used if authentication is required to access a repository, and MAY be configured and enforced by the HTTP server software.
Because Git repositories are accessed by standard path components server administrators MAY use directory based permissions within their HTTP server to control repository access.
Clients SHOULD support Basic authentication as described by RFC 2617. Servers SHOULD support Basic authentication by relying upon the HTTP server placed in front of the Git server software.
Servers SHOULD NOT require HTTP cookies for the purposes of authentication or access control.
Clients and servers MAY support other common forms of HTTP based authentication, such as Digest authentication.
Clients and servers SHOULD support SSL, particularly to protect passwords when relying on Basic HTTP authentication.
The Git over HTTP protocol (much like HTTP itself) is stateless from the perspective of the HTTP server side. All state MUST be retained and managed by the client process. This permits simple round-robin load-balancing on the server side, without needing to worry about state management.
Clients MUST NOT require state management on the server side in order to function correctly.
Servers MUST NOT require HTTP cookies in order to function correctly. Clients MAY store and forward HTTP cookies during request processing as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any cookies sent by a client.
Except where noted, all standard HTTP behavior SHOULD be assumed by both client and server. This includes (but is not necessarily limited to):
If there is no repository at $GIT_URL, or the resource pointed to by a location matching $GIT_URL does not exist, the server MUST NOT respond with 200 OK response. A server SHOULD respond with 404 Not Found, 410 Gone, or any other suitable HTTP status code which does not imply the resource exists as requested.
If there is a repository at $GIT_URL, but access is not currently permitted, the server MUST respond with the 403 Forbidden HTTP status code.
Servers SHOULD support both HTTP 1.0 and HTTP 1.1. Servers SHOULD support chunked encoding for both request and response bodies.
Clients SHOULD support both HTTP 1.0 and HTTP 1.1. Clients SHOULD support chunked encoding for both request and response bodies.
Servers MAY return ETag and/or Last-Modified headers.
Clients MAY revalidate cached entities by including If-Modified-Since and/or If-None-Match request headers.
Servers MAY return 304 Not Modified if the relevant headers appear in the request and the entity has not changed. Clients MUST treat 304 Not Modified identical to 200 OK by reusing the cached entity.
Clients MAY reuse a cached entity without revalidation if the Cache-Control and/or Expires header permits caching. Clients and servers MUST follow RFC 2616 for cache controls.
All HTTP clients MUST begin either a fetch or a push exchange by discovering the references available on the remote repository.
HTTP clients that only support the "dumb" protocol MUST discover references by making a request for the special info/refs file of the repository.
Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs, without any search/query parameters.
C: GET $GIT_URL/info/refs HTTP/1.0
S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}The Content-Type of the returned info/refs entity SHOULD be text/plain; charset=utf-8, but MAY be any content type. Clients MUST NOT attempt to validate the returned Content-Type. Dumb servers MUST NOT return a return type starting with application/x-git-.
Cache-Control headers MAY be returned to disable caching of the returned entity.
When examining the response clients SHOULD only examine the HTTP status code. Valid responses are 200 OK, or 304 Not Modified.
The returned content is a UNIX formatted text file describing each ref and its known value. The file SHOULD be sorted by name according to the C locale ordering. The file SHOULD NOT include the default ref named HEAD.
info_refs = *( ref_record ) ref_record = any_ref / peeled_ref
any_ref = obj-id HTAB refname LF
peeled_ref = obj-id HTAB refname LF
obj-id HTAB refname "^{}" LFHTTP clients that support the "smart" protocol (or both the "smart" and "dumb" protocols) MUST discover references by making a parameterized request for the info/refs file of the repository.
The request MUST contain exactly one query parameter, service=$servicename, where $servicename MUST be the service name the client wishes to contact to complete the operation. The request MUST NOT contain additional query parameters.
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
dumb server reply:
S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}smart server reply:
S: 200 OK
S: Content-Type: application/x-git-upload-pack-advertisement
S: Cache-Control: no-cache
S:
S: 001e# service=git-upload-pack\n
S: 0000
S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
S: 0000The client may send Extra Parameters (see the section called “gitprotocol-pack(5)”) as a colon-separated string in the Git-Protocol HTTP header.
Uses the --http-backend-info-refs option to the section called “git-upload-pack(1)”.
Dumb servers MUST respond with the dumb server reply format.
See the prior section under dumb clients for a more detailed description of the dumb server response.
If the server does not recognize the requested service name, or the requested service name has been disabled by the server administrator, the server MUST respond with the 403 Forbidden HTTP status code.
Otherwise, smart servers MUST respond with the smart server reply format for the requested service name.
Cache-Control headers SHOULD be used to disable caching of the returned entity.
The Content-Type MUST be application/x-$servicename-advertisement. Clients SHOULD fall back to the dumb protocol if another content type is returned. When falling back to the dumb protocol clients SHOULD NOT make an additional request to $GIT_URL/info/refs, but instead SHOULD use the response already in hand. Clients MUST NOT continue if they do not support the dumb protocol.
Clients MUST validate the status code is either 200 OK or 304 Not Modified.
Clients MUST validate the first five bytes of the response entity matches the regex ^[0-9a-f]{4}#. If this test fails, clients MUST NOT continue.
Clients MUST parse the entire response as a sequence of pkt-line records.
Clients MUST verify the first pkt-line is # service=$servicename. Servers MUST set $servicename to be the request parameter value. Servers SHOULD include an LF at the end of this line. Clients MUST ignore an LF at the end of the line.
Servers MUST terminate the response with the magic 0000 end pkt-line marker.
The returned response is a pkt-line stream describing each ref and its known value. The stream SHOULD be sorted by name according to the C locale ordering. The stream SHOULD include the default ref named HEAD as the first ref. The stream MUST include capability declarations behind a NUL on the first ref.
The returned response contains "version 1" if "version=1" was sent as an Extra Parameter.
smart_reply = PKT-LINE("# service=$servicename" LF)
"0000"
*1("version 1")
ref_list
"0000"
ref_list = empty_list / non_empty_listempty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF)
*ref_recordcap-list = capability *(SP capability) capability = 1*(LC_ALPHA / DIGIT / "-" / "_") LC_ALPHA = %x61-7A
ref_record = any_ref / peeled_ref
any_ref = PKT-LINE(obj-id SP name LF)
peeled_ref = PKT-LINE(obj-id SP name LF)
PKT-LINE(obj-id SP name "^{}" LFThis service reads from the repository pointed to by $GIT_URL.
Clients MUST first perform ref discovery with $GIT_URL/info/refs?service=git-upload-pack.
C: POST $GIT_URL/git-upload-pack HTTP/1.0 C: Content-Type: application/x-git-upload-pack-request C: C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n C: 0000
S: 200 OK S: Content-Type: application/x-git-upload-pack-result S: Cache-Control: no-cache S: S: ....ACK %s, continue S: ....NAK
Clients MUST NOT reuse or revalidate a cached response. Servers MUST include sufficient Cache-Control headers to prevent caching of the response.
Servers SHOULD support all capabilities defined here.
Clients MUST send at least one "want" command in the request body. Clients MUST NOT reference an id in a "want" command which did not appear in the response obtained through ref discovery unless the server advertises capability allow-tip-sha1-in-want or allow-reachable-sha1-in-want.
compute_request = want_list
have_list
request_end
request_end = "0000" / "done"want_list = PKT-LINE(want SP cap_list LF)
*(want_pkt)
want_pkt = PKT-LINE(want LF)
want = "want" SP id
cap_list = capability *(SP capability)have_list = *PKT-LINE("have" SP id LF)TODO: Document this further.
The computation to select the minimal pack proceeds as follows (C = client, S = server):
init step:
C: Use ref discovery to obtain the advertised refs.
C: Place any object seen into set advertised.
C: Build an empty set, common, to hold the objects that are later determined to be on both ends.
C: Build a set, want, of the objects from advertised that the client wants to fetch, based on what it saw during ref discovery.
C: Start a queue, c_pending, ordered by commit time (popping newest first). Add all client refs. When a commit is popped from the queue its parents SHOULD be automatically inserted back. Commits MUST only enter the queue once.
one compute step:
C: Send one $GIT_URL/git-upload-pack request:
C: 0032want <want-#1>............................... C: 0032want <want-#2>............................... .... C: 0032have <common-#1>............................. C: 0032have <common-#2>............................. .... C: 0032have <have-#1>............................... C: 0032have <have-#2>............................... .... C: 0000
The stream is organized into "commands", with each command appearing by itself in a pkt-line. Within a command line, the text leading up to the first space is the command name, and the remainder of the line to the first LF is the value. Command lines are terminated with an LF as the last byte of the pkt-line value.
Commands MUST appear in the following order, if they appear at all in the request stream:
The stream is terminated by a pkt-line flush (0000).
A single "want" or "have" command MUST have one hex formatted object name as its value. Multiple object names MUST be sent by sending multiple commands. Object names MUST be given using the object format negotiated through the object-format capability (default SHA-1).
The have list is created by popping the first 32 commits from c_pending. Fewer can be supplied if c_pending empties.
If the client has sent 256 "have" commits and has not yet received one of those back from s_common, or the client has emptied c_pending it SHOULD include a "done" command to let the server know it won't proceed:
C: 0009done
S: Parse the git-upload-pack request:
Verify all objects in want are directly reachable from refs.
The server MAY walk backwards through history or through the reflog to permit slightly stale requests.
If no "want" objects are received, send an error: TODO: Define error if no "want" lines are requested.
If any "want" object is not reachable, send an error: When a Git server receives an invalid or malformed want line, it responds with an error message that includes the offending object name.
Create an empty list, s_common.
If "have" was sent:
Loop through the objects in the order supplied by the client.
For each object, if the server has the object reachable from a ref, add it to s_common. If a commit is added to s_common, do not add any ancestors, even if they also appear in have.
S: Send the git-upload-pack response:
If the server has found a closed set of objects to pack or the request ends with "done", it replies with the pack. TODO: Document the pack based response
S: PACK...
The returned stream is the side-band-64k protocol supported by the git-upload-pack service, and the pack is embedded into stream 1. Progress messages from the server side MAY appear in stream 2.
Here a "closed set of objects" is defined to have at least one path from every "want" to at least one "common" object.
If the server needs more information, it replies with a status continue response: TODO: Document the non-pack response
C: Parse the upload-pack response: TODO: Document parsing response
Do another compute step.
This service reads from the repository pointed to by $GIT_URL.
Clients MUST first perform ref discovery with $GIT_URL/info/refs?service=git-receive-pack.
C: POST $GIT_URL/git-receive-pack HTTP/1.0 C: Content-Type: application/x-git-receive-pack-request C: C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status C: 0000 C: PACK....
S: 200 OK S: Content-Type: application/x-git-receive-pack-result S: Cache-Control: no-cache S: S: ....
Clients MUST NOT reuse or revalidate a cached response. Servers MUST include sufficient Cache-Control headers to prevent caching of the response.
Servers SHOULD support all capabilities defined here.
Clients MUST send at least one command in the request body. Within the command portion of the request body clients SHOULD send the id obtained through ref discovery as old_id.
update_request = command_list
"PACK" <binary-data>command_list = PKT-LINE(command NUL cap_list LF)
*(command_pkt)
command_pkt = PKT-LINE(command LF)
cap_list = *(SP capability) SPcommand = create / delete / update create = zero-id SP new_id SP name delete = old_id SP zero-id SP name update = old_id SP new_id SP name
TODO: Document this further.
Part of the the section called “git(1)” suite
Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a server to a client. The three transports (ssh, git, file) use the same protocol to transfer data. http is documented in the section called “gitprotocol-http(5)”.
The processes invoked in the canonical Git implementation are upload-pack on the server side and fetch-pack on the client side for fetching data; then receive-pack on the server and send-pack on the client for pushing data. The protocol functions to have a server tell a client what is currently on the server, then for the two to negotiate the smallest amount of data to send in order to fully update one or the other.
The descriptions below build on the pkt-line format described in the section called “gitprotocol-common(5)”. When the grammar indicates PKT-LINE(...), unless otherwise noted the usual pkt-line LF rules apply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not present.
An error packet is a special pkt-line that contains an error string.
error-line = PKT-LINE("ERR" SP explanation-text)Throughout the protocol, where PKT-LINE(...) is expected, an error packet MAY be sent. Once this packet is sent by a client or a server, the data transfer process defined in this protocol is terminated.
There are three transports over which the packfile protocol is initiated. The Git transport is a simple, unauthenticated server that takes the command (almost always upload-pack, though Git servers can be configured to be globally writable, in which receive- pack initiation is also allowed) with which the client wishes to communicate and executes it and connects it to the requesting process.
In the SSH transport, the client just runs the upload-pack or receive-pack process on the server over the SSH protocol and then communicates with that invoked process over the SSH connection.
The file:// transport runs the upload-pack or receive-pack process locally and communicates with it over a pipe.
The protocol provides a mechanism in which clients can send additional information in its first message to the server. These are called "Extra Parameters", and are supported by the Git, SSH, and HTTP protocols.
Each Extra Parameter takes the form of <key>=<value> or <key>.
Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is "version" with a value of 1 or 2. See the section called “gitprotocol-v2(5)” for more information on protocol version 2.
The Git transport starts off by sending the command and repository on the wire using the pkt-line format, followed by a NUL byte and a hostname parameter, terminated by a NUL byte.
0033git-upload-pack /project.git\0host=myserver.com\0
The transport may send Extra Parameters by adding an additional NUL byte, and then adding one or more NUL-terminated strings:
003egit-upload-pack /project.git\0host=myserver.com\0\0version=1\0
git-proto-request = request-command SP pathname NUL
[ host-parameter NUL ] [ NUL extra-parameters ]
request-command = "git-upload-pack" / "git-receive-pack" /
"git-upload-archive" ; case sensitive
pathname = *( %x01-ff ) ; exclude NUL
host-parameter = "host=" hostname [ ":" port ]
extra-parameters = 1*extra-parameter
extra-parameter = 1*( %x01-ff ) NULhost-parameter is used for the git-daemon name based virtual hosting. See --interpolated-path option to git daemon, with the %H/%CH format characters.
Basically what the Git client is doing to connect to an upload-pack process on the server side over the Git protocol is this:
$ echo -e -n \ "003agit-upload-pack /schacon/gitbook.git\0host=example.com\0" | nc -v example.com 9418
Initiating the upload-pack or receive-pack processes over SSH is executing the binary on the server via SSH remote execution. It is basically equivalent to running this:
$ ssh git.example.com "git-upload-pack '/project.git'"
For a server to support Git pushing and pulling for a given user over SSH, that user needs to be able to execute one or both of those commands via the SSH shell that they are provided on login. On some systems, that shell access is limited to only being able to run those two commands, or even just one of them.
In an ssh:// format URI, it's absolute in the URI, so the / after the host name (or port number) is sent as an argument, which is then read by the remote git-upload-pack exactly as is, so it's effectively an absolute path in the remote filesystem.
git clone ssh://user@example.com/project.git
|
v
ssh user@example.com "git-upload-pack '/project.git'"In a "user@host:path" format URI, it's relative to the user's home directory, because the Git client will run:
git clone user@example.com:project.git
|
v
ssh user@example.com "git-upload-pack 'project.git'"The exception is if a ~ is used, in which case we execute it without the leading /.
ssh://user@example.com/~alice/project.git,
|
v
ssh user@example.com "git-upload-pack '~alice/project.git'"Depending on the value of the protocol.version configuration variable, Git may attempt to send Extra Parameters as a colon-separated string in the GIT_PROTOCOL environment variable. This is done only if the ssh.variant configuration variable indicates that the ssh command supports passing environment variables as an argument.
A few things to remember here:
When one Git repository wants to get data that a second repository has, the first can fetch from the second. This operation determines what data the server has that the client does not then streams that data down to the client in packfile format.
When the client initially connects the server will immediately respond with a version number (if "version=1" is sent as an Extra Parameter), and a listing of each reference it has (all branches and tags) along with the object name that each reference currently points to.
$ echo -e -n "0045git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" |
nc -v example.com 9418
000eversion 1
00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack
side-band side-band-64k ofs-delta shallow no-progress include-tag
00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0
003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
0000The returned response is a pkt-line stream describing each ref and its current value. The stream MUST be sorted by name according to the C locale ordering.
If HEAD is a valid ref, HEAD MUST appear as the first advertised ref. If HEAD is not a valid ref, HEAD MUST NOT appear in the advertisement list at all, but other refs may still appear.
The stream MUST include capability declarations behind a NUL on the first ref. The peeled value of a ref (that is "ref^{}") MUST be immediately after the ref itself, if presented. A conforming server MUST peel the ref if it's an annotated tag.
advertised-refs = *1("version 1")
(no-refs / list-of-refs)
*shallow
flush-pkt
no-refs = PKT-LINE(zero-id SP "capabilities^{}"
NUL capability-list)
list-of-refs = first-ref *other-ref
first-ref = PKT-LINE(obj-id SP refname
NUL capability-list)
other-ref = PKT-LINE(other-tip / other-peeled)
other-tip = obj-id SP refname
other-peeled = obj-id SP refname "^{}"
shallow = PKT-LINE("shallow" SP obj-id)
capability-list = capability *(SP capability)
capability = 1*(LC_ALPHA / DIGIT / "-" / "_")
LC_ALPHA = %x61-7AServer and client MUST use lowercase for obj-id, both MUST treat obj-id as case-insensitive.
See protocol-capabilities.txt for a list of allowed server capabilities and descriptions.
After reference and capabilities discovery, the client can decide to terminate the connection by sending a flush-pkt, telling the server it can now gracefully terminate, and disconnect, when it does not need any pack data. This can happen with the ls-remote command, and also can happen when the client already is up to date.
Otherwise, it enters the negotiation phase, where the client and server determine what the minimal packfile necessary for transport is, by telling the server what objects it wants, its shallow objects (if any), and the maximum commit depth it wants (if any). The client will also send a list of the capabilities it wants to be in effect, out of what the server said it could do with the first want line.
upload-request = want-list
*shallow-line
*1depth-request
[filter-request]
flush-pkt
want-list = first-want
*additional-want
shallow-line = PKT-LINE("shallow" SP obj-id)
depth-request = PKT-LINE("deepen" SP depth) /
PKT-LINE("deepen-since" SP timestamp) /
PKT-LINE("deepen-not" SP ref)
first-want = PKT-LINE("want" SP obj-id SP capability-list)
additional-want = PKT-LINE("want" SP obj-id)
depth = 1*DIGIT
filter-request = PKT-LINE("filter" SP filter-spec)Clients MUST send all the obj-ids it wants from the reference discovery phase as want lines. Clients MUST send at least one want command in the request body. Clients MUST NOT mention an obj-id in a want command which did not appear in the response obtained through ref discovery.
The client MUST write all obj-ids which it only has shallow copies of (meaning that it does not have the parents of a commit) as shallow lines so that the server is aware of the limitations of the client's history.
The client now sends the maximum commit history depth it wants for this transaction, which is the number of commits it wants from the tip of the history, if any, as a deepen line. A depth of 0 is the same as not making a depth request. The client does not want to receive any commits beyond this depth, nor does it want objects needed only to complete those commits. Commits whose parents are not received as a result are defined as shallow and marked as such in the server. This information is sent back to the client in the next step.
The client can optionally request that pack-objects omit various objects from the packfile using one of several filtering techniques. These are intended for use with partial clone and partial fetch operations. An object that does not meet a filter-spec value is omitted unless explicitly requested in a want line. See rev-list for possible filter-spec values.
Once all the want's and 'shallow's (and optional 'deepen) are transferred, clients MUST send a flush-pkt, to tell the server side that it is done sending the list.
Otherwise, if the client sent a positive depth request, the server will determine which commits will and will not be shallow and send this information to the client. If the client did not request a positive depth, this step is skipped.
shallow-update = *shallow-line
*unshallow-line
flush-pkt
shallow-line = PKT-LINE("shallow" SP obj-id)
unshallow-line = PKT-LINE("unshallow" SP obj-id)If the client has requested a positive depth, the server will compute the set of commits which are no deeper than the desired depth. The set of commits starts at the client's wants.
The server writes shallow lines for each commit whose parents will not be sent as a result. The server writes an unshallow line for each commit which the client has indicated is shallow, but is no longer shallow at the currently requested depth (that is, its parents will now be sent). The server MUST NOT mark as unshallow anything which the client has not indicated was shallow.
Now the client will send a list of the obj-ids it has using have lines, so the server can make a packfile that only contains the objects that the client needs. In multi_ack mode, the canonical implementation will send up to 32 of these at a time, then will send a flush-pkt. The canonical implementation will skip ahead and send the next 32 immediately, so that there is always a block of 32 "in-flight on the wire" at a time.
upload-haves = have-list
compute-end
have-list = *have-line
have-line = PKT-LINE("have" SP obj-id)
compute-end = flush-pkt / PKT-LINE("done")If the server reads have lines, it then will respond by ACKing any of the obj-ids the client said it had that the server also has. The server will ACK obj-ids differently depending on which ack mode is chosen by the client.
In multi_ack mode:
In multi_ack_detailed mode:
Without either multi_ack or multi_ack_detailed:
After the client has gotten enough ACK responses that it can determine that the server has enough information to send an efficient packfile (in the canonical implementation, this is determined when it has received enough ACKs that it can color everything left in the --date-order queue as common with the server, or the --date-order queue is empty), or the client determines that it wants to give up (in the canonical implementation, this is determined when the client sends 256 have lines without getting any of them ACKed by the server - meaning there is nothing in common and the server should just send all of its objects), then the client will send a done command. The done command signals to the server that the client is ready to receive its packfile data.
However, the 256 limit only turns on in the canonical client implementation if we have received at least one "ACK %s continue" during a prior round. This helps to ensure that at least one common ancestor is found before we give up entirely.
Once the done line is read from the client, the server will either send a final ACK obj-id or it will send a NAK. obj-id is the object name of the last commit determined to be common. The server only sends ACK after done if there is at least one common base and multi_ack or multi_ack_detailed is enabled. The server always sends NAK after done if there is no common base found.
Instead of ACK or NAK, the server may send an error message (for example, if it does not recognize an object in a want line received from the client).
Then the server will start sending its packfile data.
server-response = *ack_multi ack / nak
ack_multi = PKT-LINE("ACK" SP obj-id ack_status)
ack_status = "continue" / "common" / "ready"
ack = PKT-LINE("ACK" SP obj-id)
nak = PKT-LINE("NAK")A simple clone may look like this (with no have lines):
C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
side-band-64k ofs-delta\n
C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n
C: 0000
C: 0009done\n
S: 0008NAK\n
S: [PACKFILE]An incremental update (fetch) response might look like this:
C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
side-band-64k ofs-delta\n
C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
C: 0000
C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
C: [30 more have lines]
C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n
C: 0000
S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n
S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n
S: 0008NAK\n
C: 0009done\n
S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n
S: [PACKFILE]Now that the client and server have finished negotiation about what the minimal amount of data that needs to be sent to the client is, the server will construct and send the required data in packfile format.
See the section called “gitformat-pack(5)” for what the packfile itself actually looks like.
If side-band or side-band-64k capabilities have been specified by the client, the server will send the packfile data multiplexed.
Each packet starting with the packet-line length of the amount of data that follows, followed by a single byte specifying the sideband the following data is coming in on.
In side-band mode, it will send up to 999 data bytes plus 1 control code, for a total of up to 1000 bytes in a pkt-line. In side-band-64k mode it will send up to 65519 data bytes plus 1 control code, for a total of up to 65520 bytes in a pkt-line.
The sideband byte will be a 1, 2 or a 3. Sideband 1 will contain packfile data, sideband 2 will be used for progress information that the client will generally print to stderr and sideband 3 is used for error information.
If no side-band capability was specified, the server will stream the entire packfile without multiplexing.
Pushing data to a server will invoke the receive-pack process on the server, which will allow the client to tell it which references it should update and then send all the data the server will need for those new references to be complete. Once all the data is received and validated, the server will then update its references to what the client specified.
The protocol itself contains no authentication mechanisms. That is to be handled by the transport, such as SSH, before the receive-pack process is invoked. If receive-pack is configured over the Git transport, those repositories will be writable by anyone who can access that port (9418) as that transport is unauthenticated.
The reference discovery phase is done nearly the same way as it is in the fetching protocol. Each reference obj-id and name on the server is sent in packet-line format to the client, followed by a flush-pkt. The only real difference is that the capability listing is different - the only possible values are report-status, report-status-v2, delete-refs, ofs-delta, atomic and push-options.
Once the client knows what references the server is at, it can send a list of reference update requests. For each reference on the server that it wants to update, it sends a line listing the obj-id currently on the server, the obj-id the client would like to update it to and the name of the reference.
This list is followed by a flush-pkt.
update-requests = *shallow ( command-list | push-cert )
shallow = PKT-LINE("shallow" SP obj-id)
command-list = PKT-LINE(command NUL capability-list)
*PKT-LINE(command)
flush-pkt
command = create / delete / update
create = zero-id SP new-id SP name
delete = old-id SP zero-id SP name
update = old-id SP new-id SP name
old-id = obj-id
new-id = obj-id
push-cert = PKT-LINE("push-cert" NUL capability-list LF)
PKT-LINE("certificate version 0.1" LF)
PKT-LINE("pusher" SP ident LF)
PKT-LINE("pushee" SP url LF)
PKT-LINE("nonce" SP nonce LF)
*PKT-LINE("push-option" SP push-option LF)
PKT-LINE(LF)
*PKT-LINE(command LF)
*PKT-LINE(gpg-signature-lines LF)
PKT-LINE("push-cert-end" LF)
push-option = 1*( VCHAR | SP )If the server has advertised the push-options capability and the client has specified push-options as part of the capability list above, the client then sends its push options followed by a flush-pkt.
push-options = *PKT-LINE(push-option) flush-pkt
For backwards compatibility with older Git servers, if the client sends a push cert and push options, it MUST send its push options both embedded within the push cert and after the push cert. (Note that the push options within the cert are prefixed, but the push options after the cert are not.) Both these lists MUST be the same, modulo the prefix.
After that the packfile that should contain all the objects that the server will need to complete the new references will be sent.
packfile = "PACK" 28*(OCTET)
If the receiving end does not support delete-refs, the sending end MUST NOT ask for delete command.
If the receiving end does not support push-cert, the sending end MUST NOT send a push-cert command. When a push-cert command is sent, command-list MUST NOT be sent; the commands recorded in the push certificate is used instead.
The packfile MUST NOT be sent if the only command used is delete.
A packfile MUST be sent if either create or update command is used, even if the server already has all the necessary objects. In this case the client MUST send an empty packfile. The only time this is likely to happen is if the client is creating a new branch or a tag that points to an existing obj-id.
The server will receive the packfile, unpack it, then validate each reference that is being updated that it hasn't changed while the request was being processed (the obj-id is still the same as the old-id), and it will run any update hooks to make sure that the update is acceptable. If all of that is fine, the server will then update the references.
A push certificate begins with a set of header lines. After the header and an empty line, the protocol commands follow, one per line. Note that the trailing LF in push-cert PKT-LINEs is not optional; it must be present.
Currently, the following header fields are defined:
The GPG signature lines are a detached signature for the contents recorded in the push certificate before the signature block begins. The detached signature is used to certify that the commands were given by the pusher, who must be the signer.
After receiving the pack data from the sender, the receiver sends a report if report-status or report-status-v2 capability is in effect. It is a short listing of what happened in that update. It will first list the status of the packfile unpacking as either unpack ok or unpack [error]. Then it will list the status for each of the references that it tried to update. Each line is either ok [refname] if the update was successful, or ng [refname] [error] if the update was not.
report-status = unpack-status
1*(command-status)
flush-pkt
unpack-status = PKT-LINE("unpack" SP unpack-result)
unpack-result = "ok" / error-msg
command-status = command-ok / command-fail
command-ok = PKT-LINE("ok" SP refname)
command-fail = PKT-LINE("ng" SP refname SP error-msg)
error-msg = 1*(OCTET) ; where not "ok"The report-status-v2 capability extends the protocol by adding new option lines in order to support reporting of reference rewritten by the proc-receive hook. The proc-receive hook may handle a command for a pseudo-reference which may create or update one or more references, and each reference may have different name, different new-oid, and different old-oid.
report-status-v2 = unpack-status
1*(command-status-v2)
flush-pkt
unpack-status = PKT-LINE("unpack" SP unpack-result)
unpack-result = "ok" / error-msg
command-status-v2 = command-ok-v2 / command-fail
command-ok-v2 = command-ok
*option-line
command-ok = PKT-LINE("ok" SP refname)
command-fail = PKT-LINE("ng" SP refname SP error-msg)
error-msg = 1*(OCTET) ; where not "ok"
option-line = *1(option-refname)
*1(option-old-oid)
*1(option-new-oid)
*1(option-forced-update)
option-refname = PKT-LINE("option" SP "refname" SP refname)
option-old-oid = PKT-LINE("option" SP "old-oid" SP obj-id)
option-new-oid = PKT-LINE("option" SP "new-oid" SP obj-id)
option-force = PKT-LINE("option" SP "forced-update")Updates can be unsuccessful for a number of reasons. The reference can have changed since the reference discovery phase was originally sent, meaning someone pushed in the meantime. The reference being pushed could be a non-fast-forward reference and the update hooks or configuration could be set to not allow that, etc. Also, some references can be updated while others can be rejected.
An example client/server communication might look like this:
S: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n S: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n S: 0000 C: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n C: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n C: 0000 C: [PACKDATA] S: 000eunpack ok\n S: 0018ok refs/heads/debug\n S: 002ang refs/heads/master non-fast-forward\n
Part of the the section called “git(1)” suite
This document presents a specification for a version 2 of Git's wire protocol. Protocol v2 will improve upon v1 in the following ways:
In protocol v2 communication is command oriented. When first contacting a server a list of capabilities will be advertised. Some of these capabilities will be commands which a client can request be executed. Once a command has completed, a client can reuse the connection and request that other commands be executed.
All communication is done using packet-line framing, just as in v1. See the section called “gitprotocol-pack(5)” and the section called “gitprotocol-common(5)” for more information.
In protocol v2 these special packets will have the following semantics:
In general a client can request to speak protocol v2 by sending version=2 through the respective side-channel for the transport being used which inevitably sets GIT_PROTOCOL. More information can be found in the section called “gitprotocol-pack(5)” and the section called “gitprotocol-http(5)”, as well as the GIT_PROTOCOL definition in the section called “git(1)”. In all cases the response from the server is the capability advertisement.
When using the git:// transport, you can request to use protocol v2 by sending "version=2" as an extra parameter:
003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0
When using either the ssh:// or file:// transport, the GIT_PROTOCOL environment variable must be set explicitly to include "version=2". The server may need to be configured to allow this environment variable to pass.
When using the http:// or https:// transport a client makes a "smart" info/refs request as described in the section called “gitprotocol-http(5)” and requests that v2 be used by supplying "version=2" in the Git-Protocol header.
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 C: Git-Protocol: version=2
A v2 server would reply:
S: 200 OK S: <Some headers> S: ... S: S: 000eversion 2\n S: <capability-advertisement>
Subsequent requests are then made directly to the service $GIT_URL/git-upload-pack. (This works the same for git-receive-pack).
Uses the --http-backend-info-refs option to the section called “git-upload-pack(1)”.
The server may need to be configured to pass this header's contents via the GIT_PROTOCOL variable. See the discussion in the section called “git-http-backend(1)”.
A server which decides to communicate (based on a request from a client) using protocol version 2, notifies the client by sending a version string in its initial response followed by an advertisement of its capabilities. Each capability is a key with an optional value. Clients must ignore all unknown keys. Semantics of unknown values are left to the definition of each key. Some capabilities will describe commands which can be requested to be executed by the client.
capability-advertisement = protocol-version
capability-list
flush-pktprotocol-version = PKT-LINE("version 2" LF)
capability-list = *capability
capability = PKT-LINE(key[=value] LF)key = 1*(ALPHA | DIGIT | "-_")
value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;")After receiving the capability advertisement, a client can then issue a request to select the command it wants with any particular capabilities or arguments. There is then an optional section where the client can provide any command specific parameters or queries. Only a single command can be requested at a time.
request = empty-request | command-request
empty-request = flush-pkt
command-request = command
capability-list
delim-pkt
command-args
flush-pkt
command = PKT-LINE("command=" key LF)
command-args = *command-specific-argcommand-specific-args are packet line framed arguments defined by each individual command.
The server will then check to ensure that the client's request is comprised of a valid command as well as valid capabilities which were advertised. If the request is valid the server will then execute the command. A server MUST wait till it has received the client's entire request before issuing a response. The format of the response is determined by the command being executed, but in all cases a flush-pkt indicates the end of the response.
When a command has finished, and the client has received the entire response from the server, a client can either request that another command be executed or can terminate the connection. A client may optionally send an empty request consisting of just a flush-pkt to indicate that no more requests will be made.
There are two different types of capabilities: normal capabilities, which can be used to convey information or alter the behavior of a request, and commands, which are the core actions that a client wants to perform (fetch, push, etc).
Protocol version 2 is stateless by default. This means that all commands must only last a single round and be stateless from the perspective of the server side, unless the client has requested a capability indicating that state should be maintained by the server. Clients MUST NOT require state management on the server side in order to function correctly. This permits simple round-robin load-balancing on the server side, without needing to worry about state management.
The server can advertise the agent capability with a value X (in the form agent=X) to notify the client that the server is running version X. The client may optionally send its own agent string by including the agent capability with a value Y (in the form agent=Y) in its request to the server (but it MUST NOT do so if the server did not advertise the agent capability). The X and Y strings may contain any printable ASCII characters except space (i.e., the byte range 33 ⇐ x ⇐ 126), and are typically of the form "package/version-os" (e.g., "git/1.8.3.1-Linux") where os is the operating system name (e.g., "Linux"). X and Y can be configured using the GIT_USER_AGENT environment variable and it takes priority. The os is retrieved using the sysname field of the uname(2) system call or its equivalent. The agent strings are purely informative for statistics and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features.
ls-refs is the command used to request a reference advertisement in v2. Unlike the current reference advertisement, ls-refs takes in arguments which can be used to limit the refs sent from the server.
Additional features not supported in the base command will be advertised as the value of the command in the capability advertisement in the form of a space separated list of features: "<command>=<feature-1> <feature-2>"
ls-refs takes in the following arguments:
symrefs
In addition to the object pointed by it, show the underlying ref
pointed by it when showing a symbolic ref.
peel
Show peeled tags.
ref-prefix <prefix>
When specified, only references having a prefix matching one of
the provided prefixes are displayed. Multiple instances may be
given, in which case references matching any prefix will be
shown. Note that this is purely for optimization; a server MAY
show refs not matching the prefix if it chooses, and clients
should filter the result themselves.If the unborn feature is advertised the following argument can be included in the client's request.
unborn
The server will send information about HEAD even if it is a symref
pointing to an unborn branch in the form "unborn HEAD
symref-target:<target>".The output of ls-refs is as follows:
output = *ref
flush-pkt
obj-id-or-unborn = (obj-id | "unborn")
ref = PKT-LINE(obj-id-or-unborn SP refname *(SP ref-attribute) LF)
ref-attribute = (symref | peeled)
symref = "symref-target:" symref-target
peeled = "peeled:" obj-idfetch is the command used to fetch a packfile in v2. It can be looked at as a modified version of the v1 fetch where the ref-advertisement is stripped out (since the ls-refs command fills that role) and the message format is tweaked to eliminate redundancies and permit easy addition of future extensions.
Additional features not supported in the base command will be advertised as the value of the command in the capability advertisement in the form of a space separated list of features: "<command>=<feature-1> <feature-2>"
A fetch request can take the following arguments:
want <oid>
Indicates to the server an object which the client wants to
retrieve. Wants can be anything and are not limited to
advertised objects.have <oid>
Indicates to the server an object which the client has locally.
This allows the server to make a packfile which only contains
the objects that the client needs. Multiple 'have' lines can be
supplied.done
Indicates to the server that negotiation should terminate (or
not even begin if performing a clone) and that the server should
use the information supplied in the request to construct the
packfile.thin-pack
Request that a thin pack be sent, which is a pack with deltas
which reference base objects not contained within the pack (but
are known to exist at the receiving end). This can reduce the
network traffic significantly, but it requires the receiving end
to know how to "thicken" these packs by adding the missing bases
to the pack.no-progress
Request that progress information that would normally be sent on
side-band channel 2, during the packfile transfer, should not be
sent. However, the side-band channel 3 is still used for error
responses.include-tag
Request that annotated tags should be sent if the objects they
point to are being sent.ofs-delta
Indicate that the client understands PACKv2 with delta referring
to its base by position in pack rather than by an oid. That is,
they can read OBJ_OFS_DELTA (aka type 6) in a packfile.If the shallow feature is advertised the following arguments can be included in the clients request as well as the potential addition of the shallow-info section in the server's response as explained below.
shallow <oid>
A client must notify the server of all commits for which it only
has shallow copies (meaning that it doesn't have the parents of
a commit) by supplying a 'shallow <oid>' line for each such
object so that the server is aware of the limitations of the
client's history. This is so that the server is aware that the
client may not have all objects reachable from such commits.deepen <depth>
Requests that the fetch/clone should be shallow having a commit
depth of <depth> relative to the remote side.deepen-relative
Requests that the semantics of the "deepen" command be changed
to indicate that the depth requested is relative to the client's
current shallow boundary, instead of relative to the requested
commits.deepen-since <timestamp>
Requests that the shallow clone/fetch should be cut at a
specific time, instead of depth. Internally it's equivalent to
doing "git rev-list --max-age=<timestamp>". Cannot be used with
"deepen".deepen-not <rev>
Requests that the shallow clone/fetch should be cut at a
specific revision specified by '<rev>', instead of a depth.
Internally it's equivalent of doing "git rev-list --not <rev>".
Cannot be used with "deepen", but can be used with
"deepen-since".If the filter feature is advertised, the following argument can be included in the client's request:
filter <filter-spec>
Request that various objects from the packfile be omitted
using one of several filtering techniques. These are intended
for use with partial clone and partial fetch operations. See
`rev-list` for possible "filter-spec" values. When communicating
with other processes, senders SHOULD translate scaled integers
(e.g. "1k") into a fully-expanded form (e.g. "1024") to aid
interoperability with older receivers that may not understand
newly-invented scaling suffixes. However, receivers SHOULD
accept the following suffixes: 'k', 'm', and 'g' for 1024,
1048576, and 1073741824, respectively.If the ref-in-want feature is advertised, the following argument can be included in the client's request as well as the potential addition of the wanted-refs section in the server's response as explained below.
want-ref <ref>
Indicates to the server that the client wants to retrieve a
particular ref, where <ref> is the full name of a ref on the
server. It is a protocol error to send want-ref for the
same ref more than once.If the sideband-all feature is advertised, the following argument can be included in the client's request:
sideband-all
Instruct the server to send the whole response multiplexed, not just
the packfile section. All non-flush and non-delim PKT-LINE in the
response (not only in the packfile section) will then start with a byte
indicating its sideband (1, 2, or 3), and the server may send "0005\2"
(a PKT-LINE of sideband 2 with no payload) as a keepalive packet.If the packfile-uris feature is advertised, the following argument can be included in the client's request as well as the potential addition of the packfile-uris section in the server's response as explained below. Note that at most one packfile-uris line can be sent to the server.
packfile-uris <comma-separated-list-of-protocols>
Indicates to the server that the client is willing to receive
URIs of any of the given protocols in place of objects in the
sent packfile. Before performing the connectivity check, the
client should download from all given URIs. Currently, the
protocols supported are "http" and "https".If the wait-for-done feature is advertised, the following argument can be included in the client's request.
wait-for-done
Indicates to the server that it should never send "ready", but
should wait for the client to say "done" before sending the
packfile.The response of fetch is broken into a number of sections separated by delimiter packets (0001), with each section beginning with its section header. Most sections are sent only when the packfile is sent.
output = acknowledgements flush-pkt |
[acknowledgments delim-pkt] [shallow-info delim-pkt]
[wanted-refs delim-pkt] [packfile-uris delim-pkt]
packfile flush-pktacknowledgments = PKT-LINE("acknowledgments" LF)
(nak | *ack)
(ready)
ready = PKT-LINE("ready" LF)
nak = PKT-LINE("NAK" LF)
ack = PKT-LINE("ACK" SP obj-id LF)shallow-info = PKT-LINE("shallow-info" LF)
*PKT-LINE((shallow | unshallow) LF)
shallow = "shallow" SP obj-id
unshallow = "unshallow" SP obj-idwanted-refs = PKT-LINE("wanted-refs" LF)
*PKT-LINE(wanted-ref LF)
wanted-ref = obj-id SP refnamepackfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri
packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)packfile = PKT-LINE("packfile" LF)
*PKT-LINE(%x01-03 *%x00-ff)acknowledgments section
* If the client determines that it is finished with negotiations by
sending a "done" line (thus requiring the server to send a packfile),
the acknowledgments sections MUST be omitted from the server's
response.If the server has found a suitable cut point and has decided to send a "ready" line, then the server can decide to (as an optimization) omit any "ACK" lines it would have sent during its response. This is because the server will have already determined the objects it plans to send to the client and no further negotiation is needed.
shallow-info section
* If the client has requested a shallow fetch/clone, a shallow
client requests a fetch or the server is shallow then the
server's response may include a shallow-info section. The
shallow-info section will be included if (due to one of the
above conditions) the server needs to inform the client of any
shallow boundaries or adjustments to the clients already
existing shallow boundaries.The server MUST NOT send any "unshallow" lines for anything which the client has not indicated was shallow as a part of its request.
wanted-refs section
* This section is only included if the client has requested a
ref using a 'want-ref' line and if a packfile section is also
included in the response.The server MUST NOT send any refs which were not requested using want-ref lines.
packfile-uris section
* This section is only included if the client sent
'packfile-uris' and the server has at least one such URI to
send.The hashes are 40 hex characters long. When Git upgrades to a new hash algorithm, this might need to be updated. (It should match whatever index-pack outputs after "pack\t" or "keep\t".
packfile section
* This section is only included if the client has sent 'want'
lines in its request and either requested that no more
negotiation be done by sending 'done' or if the server has
decided it has found a sufficient cut point to produce a
packfile.The data transfer of the packfile is always multiplexed, using the same semantics of the side-band-64k capability from protocol version 1. This means that each packet, during the packfile data stream, is made up of a leading 4-byte pkt-line length (typical of the pkt-line format), followed by a 1-byte stream code, followed by the actual data.
The stream code can be one of:
1 - pack data
2 - progress messages
3 - fatal error message just before stream abortsIf advertised, indicates that any number of server specific options can be included in a request. This is done by sending each option as a "server-option=<option>" capability line in the capability-list section of a request.
The provided options must not contain a NUL or LF character.
The server can advertise the object-format capability with a value X (in the form object-format=X) to notify the client that the server is able to deal with objects using hash algorithm X. If not specified, the server is assumed to only handle SHA-1. If the client would like to use a hash algorithm other than SHA-1, it should specify its object-format string.
The server may advertise a session ID that can be used to identify this process across multiple requests. The client may advertise its own session ID back to the server as well.
Session IDs should be unique to a given process. They must fit within a packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see api-trace2 for details), but this may change and users of the session ID should not rely on this fact.
object-info is the command to retrieve information about one or more objects. Its main purpose is to allow a client to make decisions based on this information without having to fully fetch objects. Object size is the only information that is currently supported.
An object-info request takes the following arguments:
size Requests size information to be returned for each listed object id.
oid <oid> Indicates to the server an object which the client wants to obtain information for.
The response of object-info is a list of the requested object ids and associated requested information, each separated by a single space.
output = info flush-pkt
info = PKT-LINE(attrs) LF)
*PKT-LINE(obj-info LF)attrs = attr | attrs SP attrs
attr = "size"
obj-info = obj-id SP obj-size
If the bundle-uri capability is advertised, the server supports the bundle-uri command.
The capability is currently advertised with no value (i.e. not "bundle-uri=somevalue"), a value may be added in the future for supporting command-wide extensions. Clients MUST ignore any unknown capability values and proceed with the 'bundle-uri` dialog they support.
The bundle-uri command is intended to be issued before fetch to get URIs to bundle files (see the section called “git-bundle(1)”) to "seed" and inform the subsequent fetch command.
The client CAN issue bundle-uri before or after any other valid command. To be useful to clients it's expected that it'll be issued after an ls-refs and before fetch, but CAN be issued at any time in the dialog.
The intent of the feature is optimize for server resource consumption in the common case by changing the common case of fetching a very large PACK during the section called “git-clone(1)” into a smaller incremental fetch.
It also allows servers to achieve better caching in combination with an uploadpack.packObjectsHook (see the section called “git-config(1)”).
By having new clones or fetches be a more predictable and common negotiation against the tips of recently produces *.bundle file(s). Servers might even pre-generate the results of such negotiations for the uploadpack.packObjectsHook as new pushes come in.
One way that servers could take advantage of these bundles is that the server would anticipate that fresh clones will download a known bundle, followed by catching up to the current state of the repository using ref tips found in that bundle (or bundles).
A bundle-uri request takes no arguments, and as noted above does not currently advertise a capability value. Both may be added in the future.
When the client issues a command=bundle-uri request, the response is a list of key-value pairs provided as packet lines with value <key>=<value>. Each <key> should be interpreted as a config key from the bundle.* namespace to construct a list of bundles. These keys are grouped by a bundle.<id>. subsection, where each key corresponding to a given <id> contributes attributes to the bundle defined by that <id>. See the section called “git-config(1)” for the specific details of these keys and how the Git client will interpret their values.
Clients MUST parse the line according to the above format, lines that do not conform to the format SHOULD be discarded. The user MAY be warned in such a case.
The content at the advertised URIs MUST be one of two types.
The advertised URI may contain a bundle file that git bundle verify would accept. I.e. they MUST contain one or more reference tips for use by the client, MUST indicate prerequisites (in any) with standard "-" prefixes, and MUST indicate their "object-format", if applicable.
The advertised URI may alternatively contain a plaintext file that git config --list would accept (with the --file option). The key-value pairs in this list are in the bundle.* namespace (see the section called “git-config(1)”).
A client MUST above all gracefully degrade on errors, whether that error is because of bad missing/data in the bundle URI(s), because that client is too dumb to e.g. understand and fully parse out bundle headers and their prerequisite relationships, or something else.
Server operators should feel confident in turning on "bundle-uri" and not worry if e.g. their CDN goes down that clones or fetches will run into hard failures. Even if the server bundle(s) are incomplete, or bad in some way the client should still end up with a functioning repository, just as if it had chosen not to use this protocol extension.
All subsequent discussion on client and server interaction MUST keep this in mind.
The ordering of the returned bundle uris is not significant. Clients MUST parse their headers to discover their contained OIDS and prerequisites. A client MUST consider the content of the bundle(s) themselves and their header as the ultimate source of truth.
A server MAY even return bundle(s) that don't have any direct relationship to the repository being cloned (either through accident, or intentional "clever" configuration), and expect a client to sort out what data they'd like from the bundle(s), if any.
A client MAY perform an early disconnect while still downloading the bundle(s) (having streamed and parsed their headers). In such a case the client MUST gracefully recover from any errors related to finishing the download and validation of the bundle(s).
I.e. a client might need to re-connect and issue a fetch command, and possibly fall back to not making use of bundle-uri at all.
This "MAY" behavior is specified as such (and not a "SHOULD") on the assumption that a server advertising bundle uris is more likely than not to be serving up a relatively large repository, and to be pointing to URIs that have a good chance of being in working order. A client MAY e.g. look at the payload size of the bundles as a heuristic to see if an early disconnect is worth it, should falling back on a full "fetch" dialog be necessary.
A client SHOULD commence a negotiation of a PACK from the server via the "fetch" command using the OID tips found in advertised bundles, even if's still in the process of downloading those bundle(s).
This allows for aggressive early disconnects from any interactive server dialog. The client blindly trusts that the advertised OID tips are relevant, and issues them as have lines, it then requests any tips it would like (usually from the "ls-refs" advertisement) via want lines. The server will then compute a (hopefully small) PACK with the expected difference between the tips from the bundle(s) and the data requested.
The only connection the client then needs to keep active is to the concurrently downloading static bundle(s), when those and the incremental PACK are retrieved they should be inflated and validated. Any errors at this point should be gracefully recovered from, see above.
The client constructs a bundle list from the <key>=<value> pairs provided by the server. These pairs are part of the bundle.* namespace as documented in the section called “git-config(1)”. In this section, we discuss some of these keys and describe the actions the client will do in response to this information.
In particular, the bundle.version key specifies an integer value. The only accepted value at the moment is 1, but if the client sees an unexpected value here then the client MUST ignore the bundle list.
As long as bundle.version is understood, all other unknown keys MAY be ignored by the client. The server will guarantee compatibility with older clients, though newer clients may be better able to use the extra keys to minimize downloads.
Any backwards-incompatible addition of pre-URI key-value will be guarded by a new bundle.version value or values in bundle-uri capability advertisement itself, and/or by new future bundle-uri request arguments.
Some example key-value pairs that are not currently implemented but could be implemented in the future include:
A "oid=<OID>" shortcut and "prerequisite=<OID>" shortcut. For expressing the common case of a bundle with one tip and no prerequisites, or one tip and one prerequisite.
This would allow for optimizing the common case of servers who'd like to provide one "big bundle" containing only their "main" branch, and/or incremental updates thereof.
A client receiving such a response MAY assume that they can skip retrieving the header from a bundle at the indicated URI, and thus save themselves and the server(s) the request(s) needed to inspect the headers of that bundle or bundles.
The server may advertise some promisor remotes it is using or knows about to a client which may want to use them as its promisor remotes, instead of this repository. In this case <pr-info> should be of the form:
pr-info = pr-fields | pr-info ";" pr-fields
pr-fields = pr-field | pr-fields "," pr-field
pr-field = field-name "=" field-value
where all the field-name and field-value in a given pr-fields are field names and values related to a single promisor remote. A given field-name MUST NOT appear more than once in given pr-fields.
The server MUST advertise at least the "name" and "url" field names along with the associated field values, which are the name of a valid remote and its URL, in each pr-fields. The "name" and "url" fields MUST appear first in each pr-fields, in that order.
After these mandatory fields, the server MAY advertise the following optional fields in any order:
No other fields are defined by the protocol at this time. Field names are case-sensitive and MUST be transmitted exactly as specified above. Clients MUST ignore fields they don't recognize to allow for future protocol extensions.
For now, the client can only use information transmitted through these fields to decide if it accepts the advertised promisor remote. In the future that information might be used for other purposes though.
Field values MUST be urlencoded.
If the client decides to use one or more promisor remotes the server advertised, it can reply with "promisor-remote=<pr-names>" where <pr-names> should be of the form:
pr-names = pr-name | pr-names ";" pr-name
where pr-name is the urlencoded name of a promisor remote the server advertised and the client accepts.
Note that, everywhere in this document, the ; and , characters MUST be encoded if they appear in pr-name or field-value.
If the server doesn't know any promisor remote that could be good for a client to use, or prefers a client not to use any promisor remote it uses or knows about, it shouldn't advertise the "promisor-remote" capability at all.
In this case, or if the client doesn't want to use any promisor remote the server advertised, the client shouldn't advertise the "promisor-remote" capability at all in its reply.
On the server side, the "promisor.advertise" and "promisor.sendFields" configuration options can be used to control what it advertises. On the client side, the "promisor.acceptFromServer" configuration option can be used to control what it accepts. See the documentation of these configuration options for more information.
Note that in the future it would be nice if the "promisor-remote" protocol capability could be used by the server, when responding to git fetch or git clone, to advertise better-connected remotes that the client can use as promisor remotes, instead of this repository, so that the client can lazily fetch objects from these other better-connected remotes. This would require the server to omit in its response the objects available on the better-connected remotes that the client has accepted. This hasn't been implemented yet though. So for now this "promisor-remote" capability is useful only when the server advertises some promisor remotes it already uses to borrow objects from.
Part of the the section called “git(1)” suite