gitformat-pack

title: gitformat-pack(5)

summary: Git pack format

text:
# gitformat-pack(5)

## NAME
gitformat-pack - Git pack format

## SYNOPSIS

```
$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
```

## DESCRIPTION
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 git-gc(1) and git-pack-objects(1).

The pack format is also used over-the-wire, see e.g. gitprotocol-v2(5), as well as being a part of other container formats in the case of gitformat-bundle(5).

## CHECKSUMS AND OBJECT IDS
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.

## PACK-*.PACK FILES HAVE THE FOLLOWING FORMAT:
•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 data
```

```
Observation: the length of each object is encoded in a variable
length format and is not constrained to 32-bit or anything.
```

•The trailer records a pack checksum of all of the above.

### Object types
Valid object types are:

•OBJ_COMMIT (1)

•OBJ_TREE (2)

•OBJ_BLOB (3)

•OBJ_TAG (4)

•OBJ_OFS_DELTA (6)

•OBJ_REF_DELTA (7)

Type 5 is reserved for future expansion. Type 0 is invalid.

### Size encoding
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.

### Deltified representation
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).

Instruction to copy from base object

```
+----------+---------+---------+---------+---------+-------+-------+-------+
| 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.

Instruction to add new data

```
+----------+============+
| 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.

Reserved instruction

```
+----------+============
| 00000000 |
+----------+============
```

This is the instruction reserved for future expansion.

## ORIGINAL (VERSION 1) PACK-*.IDX FILES HAVE THE FOLLOWING FORMAT:
•The header consists of 256 4-byte network byte order integers. N-th entry of this table records the number of objects in the corresponding pack, the first byte of whose object name is less than or equal to N. This is called the first-level fan-out table.

•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.
```

## VERSION 2 PACK-*.IDX FILES SUPPORT PACKS LARGER THAN 4 GIB, AND

```
have some other reorganizations.  They have the format:
```

•A 4-byte magic number \377tOc which is an unreasonable fanout[0] value.

•A 4-byte version number (= 2)

•A 256-entry fan-out table just like v1.

•A table of sorted object names. These are packed together without offset values to reduce the cache footprint of the binary search for a specific object name.

•A table of 4-byte CRC32 values of the packed object data. This is new in v2 so compressed data can be copied directly from pack to pack during repacking without undetected data corruption.

•A table of 4-byte offset values (in network byte order). These are usually 31-bit pack file offsets, but large offsets are encoded as an index into the next table with the msbit set.

•A table of 8-byte offset entries (empty for pack files less than 2 GiB). Pack files are organized with heavily used objects toward the front, so most object references should not need to refer to this table.

•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.
```

## PACK-*.REV FILES HAVE THE FORMAT:
•A 4-byte magic number 0x52494458 (RIDX).

•A 4-byte version identifier (= 1).

•A 4-byte hash function identifier (= 1 for SHA-1, 2 for SHA-256).

•A table of index positions (one per packed object, num_objects in total, each a 4-byte unsigned integer in network order), sorted by their corresponding offsets in the packfile.

•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.

## PACK-*.MTIMES FILES HAVE THE FORMAT:
All 4-byte numbers are in network byte order.

•A 4-byte magic number 0x4d544d45 (MTME).

•A 4-byte version identifier (= 1).

•A 4-byte hash function identifier (= 1 for SHA-1, 2 for SHA-256).

•A table of 4-byte unsigned integers. The ith value is the modification time (mtime) of the ith object in the corresponding pack by lexicographic (index) order. The mtimes count standard epoch seconds.

•A trailer, containing a checksum of the corresponding packfile, and a checksum of all of the above (each having length according to the specified hash function).

## MULTI-PACK-INDEX (MIDX) FILES HAVE THE FOLLOWING FORMAT:
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.
```

## MULTI-PACK-INDEX REVERSE INDEXES
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).

•If pack(o1) ≠ pack(o2), then sort the two objects in descending order based on the pack ID.

•Otherwise, pack(o1) = pack(o2), and the objects are sorted in pack-order (i.e., o1 sorts ahead of o2 exactly when offset(o1) < offset(o2)).

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.

### BTMP chunk
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), 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 chunk contains only objects which were requested by the caller (i.e. does not contain any objects which the caller didn’t ask for explicitly or implicitly).

•All objects stored in non-thin packs as offset- or reference-deltas also include their base object in the resulting pack.

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:

bitmap_pos

The first bit position (in pseudo-pack order) in the multi-pack index’s reachability bitmap occupied by an object from p.

bitmap_nr

The number of bit positions (including the one at bitmap_pos) that encode objects from that pack p.

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.

## CRUFT PACKS
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.

### Background
To remove unreachable objects from your repository, Git offers git repack -Ad (see 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 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.

### Cruft packs
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. 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:

1.Enumerate every object, marking any object which is (a) not contained in a kept-pack, and (b) whose mtime is within the grace period as a traversal tip.

2.Perform a reachability traversal based on the tips gathered in the previous step, adding every object along the way to the pack.

3.Write the pack out, along with a .mtimes file that records the per-object timestamps.

This mode is invoked internally by 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 git-gc(1) to expire those objects later on.

It is git-gc(1) that is typically responsible for removing expired unreachable objects.

### Alternatives
Notable alternatives to this design include:

•The location of the per-object mtime data.

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.

## GIT
Part of the git(1) suite


gitformat-signature

package: git-core

title: gitformat-signature(5)

summary: Git cryptographic signature formats

text:
# gitformat-signature(5)

## NAME
gitformat-signature - Git cryptographic signature formats

## SYNOPSIS

```
<[tag|commit] object header(s)>
<over-the-wire protocol>
```

## DESCRIPTION
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 git-config(1)). These are, for gpg.format values:

gpg (PGP)

-----BEGIN PGP SIGNATURE----- and -----END PGP SIGNATURE-----. Or, if gpg is told to produce RFC1991 signatures, -----BEGIN PGP MESSAGE----- and -----END PGP MESSAGE-----

ssh (SSH)

-----BEGIN SSH SIGNATURE----- and -----END SSH SIGNATURE-----

x509 (X.509)

-----BEGIN SIGNED MESSAGE----- and -----END SIGNED MESSAGE-----

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.

## TAG SIGNATURES
•created by: git tag -s

•payload: annotated tag object

•embedding: append the signature to the unsigned tag object

•example: tag signedtag with subject signed tag

```
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-----
```

•verify with: git verify-tag [-v] or git tag -v

```
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
```

## COMMIT SIGNATURES
•created by: git commit -S

•payload: commit object

•embedding: header entry gpgsig (content is preceded by a space)

•example: commit with subject signed commit

```
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
```

•verify with: git verify-commit [-v] (or git show --show-signature)

```
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
```

## MERGETAG SIGNATURES
•created by: git merge on signed tag

•payload/embedding: the whole signed tag object is embedded into the (merge) commit object as header entry mergetag

•example: merge of the signed tag signedtag as above

```
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
```

•verify with: verification is embedded in merge commit message by default, alternatively with git show --show-signature:

```
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 7189
```

## GIT
Part of the git(1) suite

branch: sisyphus


githooks

title: githooks(5)

summary: Hooks used by Git

text:
# githooks(5)

## NAME
githooks - Hooks used by Git

## SYNOPSIS
$GIT_DIR/hooks/* (or `git config core.hooksPath`/*)

## DESCRIPTION
Hooks are programs you can place in a hooks directory to trigger actions at certain points in git’s execution. Hooks that don’t have the executable bit set are ignored.

By default the hooks directory is $GIT_DIR/hooks, but that can be changed via the core.hooksPath configuration variable (see git-config(1)).

Before Git invokes a hook, it changes its working directory to either $GIT_DIR in a bare repository or the root of the working tree in a non-bare repository. An exception are hooks triggered during a push (pre-receive, update, post-receive, post-update, push-to-checkout) which are always executed in $GIT_DIR.

Environment variables, such as GIT_DIR, GIT_WORK_TREE, etc., are exported so that Git commands run by the hook can correctly locate the repository. If your hook needs to invoke Git commands in a foreign repository or in a different working tree of the same repository, then it should clear these environment variables so they do not interfere with Git operations at the foreign location. For example:

```
local_desc=$(git describe)
foreign_desc=$(unset $(git rev-parse --local-env-vars); git -C ../foreign-repo describe)
```

Hooks can get their arguments via the environment, command-line arguments, and stdin. See the documentation for each hook below for details.

git init may copy hooks to the new repository, depending on its configuration. See the "TEMPLATE DIRECTORY" section in git-init(1) for details. When the rest of this document refers to "default hooks" it’s talking about the default template shipped with Git.

The currently supported hooks are described below.

## HOOKS

### applypatch-msg
This hook is invoked by git-am(1). It takes a single parameter, the name of the file that holds the proposed commit log message. Exiting with a non-zero status causes git am to abort before applying the patch.

The hook is allowed to edit the message file in place, and can be used to normalize the message into some project standard format. It can also be used to refuse the commit after inspecting the message file.

The default applypatch-msg hook, when enabled, runs the commit-msg hook, if the latter is enabled.

### pre-applypatch
This hook is invoked by git-am(1). It takes no parameter, and is invoked after the patch is applied, but before a commit is made.

If it exits with non-zero status, then the working tree will not be committed after applying the patch.

It can be used to inspect the current working tree and refuse to make a commit if it does not pass certain tests.

The default pre-applypatch hook, when enabled, runs the pre-commit hook, if the latter is enabled.

### post-applypatch
This hook is invoked by git-am(1). It takes no parameter, and is invoked after the patch is applied and a commit is made.

This hook is meant primarily for notification, and cannot affect the outcome of git am.

### pre-commit
This hook is invoked by git-commit(1), and can be bypassed with the --no-verify option. It takes no parameters, and is invoked before obtaining the proposed commit log message and making a commit. Exiting with a non-zero status from this script causes the git commit command to abort before creating a commit.

The default pre-commit hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when such a line is found.

All the git commit hooks are invoked with the environment variable GIT_EDITOR=: if the command will not bring up an editor to modify the commit message.

The default pre-commit hook, when enabled—and with the hooks.allownonascii config option unset or set to false—prevents the use of non-ASCII filenames.

### pre-merge-commit
This hook is invoked by git-merge(1), and can be bypassed with the --no-verify option. It takes no parameters, and is invoked after the merge has been carried out successfully and before obtaining the proposed commit log message to make a commit. Exiting with a non-zero status from this script causes the git merge command to abort before creating a commit.

The default pre-merge-commit hook, when enabled, runs the pre-commit hook, if the latter is enabled.

This hook is invoked with the environment variable GIT_EDITOR=: if the command will not bring up an editor to modify the commit message.

If the merge cannot be carried out automatically, the conflicts need to be resolved and the result committed separately (see git-merge(1)). At that point, this hook will not be executed, but the pre-commit hook will, if it is enabled.

### prepare-commit-msg
This hook is invoked by git-commit(1) right after preparing the default log message, and before the editor is started.

It takes one to three parameters. The first is the name of the file that contains the commit log message. The second is the source of the commit message, and can be: message (if a -m or -F option was given); template (if a -t option was given or the configuration option commit.template is set); merge (if the commit is a merge or a .git/MERGE_MSG file exists); squash (if a .git/SQUASH_MSG file exists); or commit, followed by a commit object name (if a -c, -C or --amend option was given).

If the exit status is non-zero, git commit will abort.

The purpose of the hook is to edit the message file in place, and it is not suppressed by the --no-verify option. A non-zero exit means a failure of the hook and aborts the commit. It should not be used as a replacement for the pre-commit hook.

The sample prepare-commit-msg hook that comes with Git removes the help message found in the commented portion of the commit template.

### commit-msg
This hook is invoked by git-commit(1) and git-merge(1), and can be bypassed with the --no-verify option. It takes a single parameter, the name of the file that holds the proposed commit log message. Exiting with a non-zero status causes the command to abort.

The hook is allowed to edit the message file in place, and can be used to normalize the message into some project standard format. It can also be used to refuse the commit after inspecting the message file.

The default commit-msg hook, when enabled, detects duplicate Signed-off-by trailers, and aborts the commit if one is found.

### post-commit
This hook is invoked by git-commit(1). It takes no parameters, and is invoked after a commit is made.

This hook is meant primarily for notification, and cannot affect the outcome of git commit.

### pre-rebase
This hook is called by git-rebase(1) and can be used to prevent a branch from getting rebased. The hook may be called with one or two parameters. The first parameter is the upstream from which the series was forked. The second parameter is the branch being rebased, and is not set when rebasing the current branch.

### post-checkout
This hook is invoked when a git-checkout(1) or git-switch(1) is run after having updated the worktree. The hook is given three parameters: the ref of the previous HEAD, the ref of the new HEAD (which may or may not have changed), and a flag indicating whether the checkout was a branch checkout (changing branches, flag=1) or a file checkout (retrieving a file from the index, flag=0). This hook cannot affect the outcome of git switch or git checkout, other than that the hook’s exit status becomes the exit status of these two commands.

It is also run after git-clone(1), unless the --no-checkout (-n) option is used. The first parameter given to the hook is the null-ref, the second the ref of the new HEAD and the flag is always 1. Likewise for git worktree add unless --no-checkout is used.

This hook can be used to perform repository validity checks, auto-display differences from the previous HEAD if different, or set working dir metadata properties.

### post-merge
This hook is invoked by git-merge(1), which happens when a git pull is done on a local repository. The hook takes a single parameter, a status flag specifying whether or not the merge being done was a squash merge. This hook cannot affect the outcome of git merge and is not executed, if the merge failed due to conflicts.

This hook can be used in conjunction with a corresponding pre-commit hook to save and restore any form of metadata associated with the working tree (e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl for an example of how to do this.

### pre-push
This hook is called by git-push(1) and can be used to prevent a push from taking place. The hook is called with two parameters which provide the name and location of the destination remote, if a named remote is not being used both values will be the same.

Information about what is to be pushed is provided on the hook’s standard input with lines of the form:

```
<local-ref> SP <local-object-name> SP <remote-ref> SP <remote-object-name> LF
```

For instance, if the command git push origin master:foreign were run the hook would receive a line like the following:

```
refs/heads/master 67890 refs/heads/foreign 12345
```

although the full object name would be supplied. If the foreign ref does not yet exist the <remote-object-name> will be the all-zeroes object name. If a ref is to be deleted, the <local-ref> will be supplied as (delete) and the <local-object-name> will be the all-zeroes object name. If the local commit was specified by something other than a name which could be expanded (such as HEAD~, or an object name) it will be supplied as it was originally given.

If this hook exits with a non-zero status, git push will abort without pushing anything. Information about why the push is rejected may be sent to the user by writing to standard error.

### pre-receive
This hook is invoked by git-receive-pack(1) when it reacts to git push and updates reference(s) in its repository. Just before starting to update refs on the remote repository, the pre-receive hook is invoked. Its exit status determines the success or failure of the update.

This hook executes once for the receive operation. It takes no arguments, but for each ref to be updated it receives on standard input a line of the format:

```
<old-oid> SP <new-oid> SP <ref-name> LF
```

where <old-oid> is the old object name stored in the ref, <new-oid> is the new object name to be stored in the ref and <ref-name> is the full name of the ref. When creating a new ref, <old-oid> is the all-zeroes object name.

If the hook exits with non-zero status, none of the refs will be updated. If the hook exits with zero, updating of individual refs can still be prevented by the update hook.

Both standard output and standard error output are forwarded to git send-pack on the other end, so you can simply echo messages for the user.

The number of push options given on the command line of git push --push-option=... can be read from the environment variable GIT_PUSH_OPTION_COUNT, and the options themselves are found in GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,... If it is negotiated to not use the push options phase, the environment variables will not be set. If the client selects to use push options, but doesn’t transmit any, the count variable will be set to zero, GIT_PUSH_OPTION_COUNT=0.

See the section on "Quarantine Environment" in git-receive-pack(1) for some caveats.

### update
This hook is invoked by git-receive-pack(1) when it reacts to git push and updates reference(s) in its repository. Just before updating the ref on the remote repository, the update hook is invoked. Its exit status determines the success or failure of the ref update.

The hook executes once for each ref to be updated, and takes three parameters:

•the name of the ref being updated,

•the old object name stored in the ref,

•and the new object name to be stored in the ref.

A zero exit from the update hook allows the ref to be updated. Exiting with a non-zero status prevents git receive-pack from updating that ref.

This hook can be used to prevent forced update on certain refs by making sure that the object name is a commit object that is a descendant of the commit object named by the old object name. That is, to enforce a "fast-forward only" policy.

It could also be used to log the old..new status. However, it does not know the entire set of branches, so it would end up firing one e-mail per ref when used naively, though. The post-receive hook is more suited to that.

In an environment that restricts the users' access only to git commands over the wire, this hook can be used to implement access control without relying on filesystem ownership and group membership. See git-shell(1) for how you might use the login shell to restrict the user’s access to only git commands.

Both standard output and standard error output are forwarded to git send-pack on the other end, so you can simply echo messages for the user.

The default update hook, when enabled—and with hooks.allowunannotated config option unset or set to false—prevents unannotated tags from being pushed.

### proc-receive
This hook is invoked by git-receive-pack(1). If the server has set the multi-valued config variable receive.procReceiveRefs, and the commands sent to receive-pack have matching reference names, these commands will be executed by this hook, instead of by the internal execute_commands() function. This hook is responsible for updating the relevant references and reporting the results back to receive-pack.

This hook executes once for the receive operation. It takes no arguments, but uses a pkt-line format protocol to communicate with receive-pack to read commands, push-options and send results. In the following example for the protocol, the letter S stands for receive-pack and the letter H stands for this hook.

```
# Version and features negotiation.
S: PKT-LINE(version=1\0push-options atomic...)
S: flush-pkt
H: PKT-LINE(version=1\0push-options...)
H: flush-pkt
```

```
# Send commands from server to the hook.
S: PKT-LINE(<old-oid> <new-oid> <ref>)
S: ... ...
S: flush-pkt
# Send push-options only if the 'push-options' feature is enabled.
S: PKT-LINE(push-option)
S: ... ...
S: flush-pkt
```

```
# Receive results from the hook.
# OK, run this command successfully.
H: PKT-LINE(ok <ref>)
# NO, I reject it.
H: PKT-LINE(ng <ref> <reason>)
# Fall through, let 'receive-pack' execute it.
H: PKT-LINE(ok <ref>)
H: PKT-LINE(option fall-through)
# OK, but has an alternate reference.  The alternate reference name
# and other status can be given in option directives.
H: PKT-LINE(ok <ref>)
H: PKT-LINE(option refname <refname>)
H: PKT-LINE(option old-oid <old-oid>)
H: PKT-LINE(option new-oid <new-oid>)
H: PKT-LINE(option forced-update)
H: ... ...
H: flush-pkt
```

Each command for the proc-receive hook may point to a pseudo-reference and always has a zero-old as its old-oid, while the proc-receive hook may update an alternate reference and the alternate reference may exist already with a non-zero old-oid. For this case, this hook will use "option" directives to report extended attributes for the reference given by the leading "ok" directive.

The report of the commands of this hook should have the same order as the input. The exit status of the proc-receive hook only determines the success or failure of the group of commands sent to it, unless atomic push is in use.

### post-receive
This hook is invoked by git-receive-pack(1) when it reacts to git push and updates reference(s) in its repository. The hook executes on the remote repository once after all the proposed ref updates are processed and if at least one ref is updated as the result.

The hook takes no arguments. It receives one line on standard input for each ref that is successfully updated following the same format as the pre-receive hook.

This hook does not affect the outcome of git receive-pack, as it is called after the real work is done.

This supersedes the post-update hook in that it gets both old and new values of all the refs in addition to their names.

Both standard output and standard error output are forwarded to git send-pack on the other end, so you can simply echo messages for the user.

The default post-receive hook is empty, but there is a sample script post-receive-email provided in the contrib/hooks directory in Git distribution, which implements sending commit emails.

The number of push options given on the command line of git push --push-option=... can be read from the environment variable GIT_PUSH_OPTION_COUNT, and the options themselves are found in GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,... If it is negotiated to not use the push options phase, the environment variables will not be set. If the client selects to use push options, but doesn’t transmit any, the count variable will be set to zero, GIT_PUSH_OPTION_COUNT=0.

See the "post-receive" section in git-receive-pack(1) for additional details.

### post-update
This hook is invoked by git-receive-pack(1) when it reacts to git push and updates reference(s) in its repository. It executes on the remote repository once after all the refs have been updated.

It takes a variable number of parameters, each of which is the name of ref that was actually updated.

This hook is meant primarily for notification, and cannot affect the outcome of git receive-pack.

The post-update hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, so it is a poor place to do log old..new. The post-receive hook does get both original and updated values of the refs. You might consider it instead if you need them.

When enabled, the default post-update hook runs git update-server-info to keep the information used by dumb transports (e.g., HTTP) up to date. If you are publishing a Git repository that is accessible via HTTP, you should probably enable this hook.

Both standard output and standard error output are forwarded to git send-pack on the other end, so you can simply echo messages for the user.

### reference-transaction
This hook is invoked by any Git command that performs reference updates. It executes whenever a reference transaction is prepared, committed or aborted and may thus get called multiple times. The hook also supports symbolic reference updates.

The hook takes exactly one argument, which is the current state the given reference transaction is in:

•"prepared": All reference updates have been queued to the transaction and references were locked on disk.

•"committed": The reference transaction was committed and all references now have their respective new value.

•"aborted": The reference transaction was aborted, no changes were performed and the locks have been released.

For each reference update that was added to the transaction, the hook receives on standard input a line of the format:

```
<old-value> SP <new-value> SP <ref-name> LF
```

where <old-value> is the old object name passed into the reference transaction, <new-value> is the new object name to be stored in the ref and <ref-name> is the full name of the ref. When force updating the reference regardless of its current value or when the reference is to be created anew, <old-value> is the all-zeroes object name. To distinguish these cases, you can inspect the current value of <ref-name> via git rev-parse.

For symbolic reference updates the <old_value> and <new-value> fields could denote references instead of objects. A reference will be denoted with a ref: prefix, like ref:<ref-target>.

The exit status of the hook is ignored for any state except for the "prepared" state. In the "prepared" state, a non-zero exit status will cause the transaction to be aborted. The hook will not be called with "aborted" state in that case.

### push-to-checkout
This hook is invoked by git-receive-pack(1) when it reacts to git push and updates reference(s) in its repository, and when the push tries to update the branch that is currently checked out and the receive.denyCurrentBranch configuration variable is set to updateInstead. Such a push by default is refused if the working tree and the index of the remote repository has any difference from the currently checked out commit; when both the working tree and the index match the current commit, they are updated to match the newly pushed tip of the branch. This hook is to be used to override the default behaviour.

The hook receives the commit with which the tip of the current branch is going to be updated. It can exit with a non-zero status to refuse the push (when it does so, it must not modify the index or the working tree). Or it can make any necessary changes to the working tree and to the index to bring them to the desired state when the tip of the current branch is updated to the new commit, and exit with a zero status.

For example, the hook can simply run git read-tree -u -m HEAD "$1" in order to emulate git fetch that is run in the reverse direction with git push, as the two-tree form of git read-tree -u -m is essentially the same as git switch or git checkout that switches branches while keeping the local changes in the working tree that do not interfere with the difference between the branches.

### pre-auto-gc
This hook is invoked by git gc --auto (see git-gc(1)). It takes no parameter, and exiting with non-zero status from this script causes the git gc --auto to abort.

### post-rewrite
This hook is invoked by commands that rewrite commits (git-commit(1) when called with --amend and git-rebase(1); however, full-history (re)writing tools like git-fast-import(1) or git-filter-repo[1] typically do not call it!). Its first argument denotes the command it was invoked by: currently one of amend or rebase. Further command-dependent arguments may be passed in the future.

The hook receives a list of the rewritten commits on stdin, in the format

```
<old-object-name> SP <new-object-name> [ SP <extra-info> ] LF
```

The extra-info is again command-dependent. If it is empty, the preceding SP is also omitted. Currently, no commands pass any extra-info.

The hook always runs after the automatic note copying (see "notes.rewrite.<command>" in git-config(1)) has happened, and thus has access to these notes.

The following command-specific comments apply:

rebase

For the squash and fixup operation, all commits that were squashed are listed as being rewritten to the squashed commit. This means that there will be several lines sharing the same new-object-name. The commits are guaranteed to be listed in the order that they were processed by rebase.

### sendemail-validate
This hook is invoked by git-send-email(1).

It takes these command line arguments. They are, 1. the name of the file which holds the contents of the email to be sent. 2. The name of the file which holds the SMTP headers of the email.

The SMTP headers are passed in the exact same way as they are passed to the user’s Mail Transport Agent (MTA). In effect, the email given to the user’s MTA, is the contents of $2 followed by the contents of $1.

An example of a few common headers is shown below. Take notice of the capitalization and multi-line tab structure.

```
From: Example <from@example.com>
To: to@example.com
Cc: cc@example.com,

        A <author@example.com>,

        One <one@example.com>,

        two@example.com
Subject: PATCH-STRING
```

Exiting with a non-zero status causes git send-email to abort before sending any e-mails.

The following environment variables are set when executing the hook.

GIT_SENDEMAIL_FILE_COUNTER

A 1-based counter incremented by one for every file holding an e-mail to be sent (excluding any FIFOs). This counter does not follow the patch series counter scheme. It will always start at 1 and will end at GIT_SENDEMAIL_FILE_TOTAL.

GIT_SENDEMAIL_FILE_TOTAL

The total number of files that will be sent (excluding any FIFOs). This counter does not follow the patch series counter scheme. It will always be equal to the number of files being sent, whether there is a cover letter or not.

These variables may for instance be used to validate patch series.

The sample sendemail-validate hook that comes with Git checks that all sent patches (excluding the cover letter) can be applied on top of the upstream repository default branch without conflicts. Some placeholders are left for additional validation steps to be performed after all patches of a given series have been applied.

### fsmonitor-watchman
This hook is invoked when the configuration option core.fsmonitor is set to .git/hooks/fsmonitor-watchman or .git/hooks/fsmonitor-watchmanv2 depending on the version of the hook to use.

Version 1 takes two arguments, a version (1) and the time in elapsed nanoseconds since midnight, January 1, 1970.

Version 2 takes two arguments, a version (2) and a token that is used for identifying changes since the token. For watchman this would be a clock id. This version must output to stdout the new token followed by a NUL before the list of files.

The hook should output to stdout the list of all files in the working directory that may have changed since the requested time. The logic should be inclusive so that it does not miss any potential changes. The paths should be relative to the root of the working directory and be separated by a single NUL.

It is OK to include files which have not actually changed. All changes including newly-created and deleted files should be included. When files are renamed, both the old and the new name should be included.

Git will limit what files it checks for changes as well as which directories are checked for untracked files based on the path names given.

An optimized way to tell git "all files have changed" is to return the filename /.

The exit status determines whether git will use the data from the hook to limit its search. On error, it will fall back to verifying all files and folders.

### p4-changelist
This hook is invoked by git-p4 submit.

The p4-changelist hook is executed after the changelist message has been edited by the user. It can be bypassed with the --no-verify option. It takes a single parameter, the name of the file that holds the proposed changelist text. Exiting with a non-zero status causes the command to abort.

The hook is allowed to edit the changelist file and can be used to normalize the text into some project standard format. It can also be used to refuse the Submit after inspect the message file.

Run git-p4 submit --help for details.

### p4-prepare-changelist
This hook is invoked by git-p4 submit.

The p4-prepare-changelist hook is executed right after preparing the default changelist message and before the editor is started. It takes one parameter, the name of the file that contains the changelist text. Exiting with a non-zero status from the script will abort the process.

The purpose of the hook is to edit the message file in place, and it is not suppressed by the --no-verify option. This hook is called even if --prepare-p4-only is set.

Run git-p4 submit --help for details.

### p4-post-changelist
This hook is invoked by git-p4 submit.

The p4-post-changelist hook is invoked after the submit has successfully occurred in P4. It takes no parameters and is meant primarily for notification and cannot affect the outcome of the git p4 submit action.

Run git-p4 submit --help for details.

### p4-pre-submit
This hook is invoked by git-p4 submit. It takes no parameters and nothing from standard input. Exiting with non-zero status from this script prevent git-p4 submit from launching. It can be bypassed with the --no-verify command line option. Run git-p4 submit --help for details.

### post-index-change
This hook is invoked when the index is written in read-cache.c do_write_locked_index.

The first parameter passed to the hook is the indicator for the working directory being updated. "1" meaning working directory was updated or "0" when the working directory was not updated.

The second parameter passed to the hook is the indicator for whether or not the index was updated and the skip-worktree bit could have changed. "1" meaning skip-worktree bits could have been updated and "0" meaning they were not.

Only one parameter should be set to "1" when the hook runs. The hook running passing "1", "1" should not be possible.

## SEE ALSO
git-hook(1)

## GIT
Part of the git(1) suite

## NOTES
1.

git-filter-repo

https://github.com/newren/git-filter-repo


gitignore

title: gitignore(5)

text:
# gitignore(5)

## NAME
gitignore - Specifies intentionally untracked files to ignore

## SYNOPSIS
$XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, .gitignore

## DESCRIPTION
A gitignore file specifies intentionally untracked files that Git should ignore. Files already tracked by Git are not affected; see the NOTES below for details.

Each line in a gitignore file specifies a pattern. When deciding whether to ignore a path, Git normally checks gitignore patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of precedence, the last matching pattern decides the outcome):

•Patterns read from the command line for those commands that support them.

•Patterns read from a .gitignore file in the same directory as the path, or in any parent directory (up to the top-level of the working tree), with patterns in the higher level files being overridden by those in lower level files down to the directory containing the file. These patterns match relative to the location of the .gitignore file. A project normally includes such .gitignore files in its repository, containing patterns for files generated as part of the project build.

•Patterns read from $GIT_DIR/info/exclude.

•Patterns read from the file specified by the configuration variable core.excludesFile.

Which file to place a pattern in depends on how the pattern is meant to be used.

•Patterns which should be version-controlled and distributed to other repositories via clone (i.e., files that all developers will want to ignore) should go into a .gitignore file.

•Patterns which are specific to a particular repository but which do not need to be shared with other related repositories (e.g., auxiliary files that live inside the repository but are specific to one user’s workflow) should go into the $GIT_DIR/info/exclude file.

•Patterns which a user wants Git to ignore in all situations (e.g., backup or temporary files generated by the user’s editor of choice) generally go into a file specified by core.excludesFile in the user’s ~/.gitconfig. Its default value is $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore is used instead.

The underlying Git plumbing tools, such as git ls-files and git read-tree, read gitignore patterns specified by command-line options, or from files specified by command-line options. Higher-level Git tools, such as git status and git add, use patterns from the sources specified above.

## PATTERN FORMAT
•A blank line matches no files, so it can serve as a separator for readability.

•A line starting with # serves as a comment. Put a backslash ("\") in front of the first hash for patterns that begin with a hash.

•Trailing spaces are ignored unless they are quoted with backslash ("\").

•An optional prefix "!" which negates the pattern; any matching file excluded by a previous pattern will become included again. It is not possible to re-include a file if a parent directory of that file is excluded. Git doesn’t list excluded directories for performance reasons, so any patterns on contained files have no effect, no matter where they are defined. Put a backslash ("\") in front of the first "!" for patterns that begin with a literal "!", for example, "\!important!.txt".

•The slash "/" is used as the directory separator. Separators may occur at the beginning, middle or end of the .gitignore search pattern.

•If there is a separator at the beginning or middle (or both) of the pattern, then the pattern is relative to the directory level of the particular .gitignore file itself. Otherwise the pattern may also match at any level below the .gitignore level.

•If there is a separator at the end of the pattern then the pattern will only match directories, otherwise the pattern can match both files and directories.

•For example, a pattern doc/frotz/ matches doc/frotz directory, but not a/doc/frotz directory; however frotz/ matches frotz and a/frotz that is a directory (all paths are relative from the .gitignore file).

•An asterisk "*" matches anything except a slash. The character "?" matches any one character except "/". The range notation, e.g. [a-zA-Z], can be used to match one of the characters in a range. See fnmatch(3) and the FNM_PATHNAME flag for a more detailed description.

Two consecutive asterisks ("**") in patterns matched against full pathname may have special meaning:

•A leading "**" followed by a slash means match in all directories. For example, "**/foo" matches file or directory "foo" anywhere, the same as pattern "foo". "**/foo/bar" matches file or directory "bar" anywhere that is directly under directory "foo".

•A trailing "/**" matches everything inside. For example, "abc/**" matches all files inside directory "abc", relative to the location of the .gitignore file, with infinite depth.

•A slash followed by two consecutive asterisks then a slash matches zero or more directories. For example, "a/**/b" matches "a/b", "a/x/b", "a/x/y/b" and so on.

•Other consecutive asterisks are considered regular asterisks and will match according to the previous rules.

## CONFIGURATION
The optional configuration variable core.excludesFile indicates a path to a file containing patterns of file names to exclude, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to those in $GIT_DIR/info/exclude.

## NOTES
The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked.

To stop tracking a file that is currently tracked, use git rm --cached to remove the file from the index. The filename can then be added to the .gitignore file to stop the file from being reintroduced in later commits.

Git does not follow symbolic links when accessing a .gitignore file in the working tree. This keeps behavior consistent when the file is accessed from the index or a tree versus from the filesystem.

## EXAMPLES
•The pattern hello.* matches any file or directory whose name begins with hello.. If one wants to restrict this only to the directory and not in its subdirectories, one can prepend the pattern with a slash, i.e. /hello.*; the pattern now matches hello.txt, hello.c but not a/hello.java.

•The pattern foo/ will match a directory foo and paths underneath it, but will not match a regular file or a symbolic link foo (this is consistent with the way how pathspec works in general in Git)

•The pattern doc/frotz and /doc/frotz have the same effect in any .gitignore file. In other words, a leading slash is not relevant if there is already a middle slash in the pattern.

•The pattern foo/*, matches foo/test.json (a regular file), foo/bar (a directory), but it does not match foo/bar/hello.c (a regular file), as the asterisk in the pattern does not match bar/hello.c which has a slash in it.

```
    $ git status

    [...]

    # Untracked files:

    [...]

    #       Documentation/foo.html

    #       Documentation/gitignore.html

    #       file.o

    #       lib.a

    #       src/internal.o

    [...]

    $ cat .git/info/exclude

    # ignore objects and archives, anywhere in the tree.

    *.[oa]

    $ cat Documentation/.gitignore

    # ignore generated html files,

    *.html

    # except foo.html which is maintained by hand

    !foo.html

    $ git status

    [...]

    # Untracked files:

    [...]

    #       Documentation/foo.html

    [...]
```

Another example:

```
    $ cat .gitignore

    vmlinux*

    $ ls arch/foo/kernel/vm*

    arch/foo/kernel/vmlinux.lds.S

    $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
```

The second .gitignore prevents Git from ignoring arch/foo/kernel/vmlinux.lds.S.

Example to exclude everything except a specific directory foo/bar (note the /* - without the slash, the wildcard would also exclude everything within foo/bar):

```
    $ cat .gitignore

    # exclude everything except directory foo/bar

    /*

    !/foo

    /foo/*

    !/foo/bar
```

## SEE ALSO
git-rm(1), gitrepository-layout(5), git-check-ignore(1)

## GIT
Part of the git(1) suite


gitmailmap

title: gitmailmap(5)

summary: Map author/committer names and/or E\-Mail addresses

text:
# gitmailmap(5)

## NAME
gitmailmap - Map author/committer names and/or E-Mail addresses

## SYNOPSIS
$GIT_WORK_TREE/.mailmap

## DESCRIPTION
If the file .mailmap exists at the toplevel of the repository, or at the location pointed to by the mailmap.file or mailmap.blob configuration options (see git-config(1)), it is used to map author and committer names and email addresses to canonical real names and email addresses.

## SYNTAX
The # character begins a comment to the end of line, blank lines are ignored.

In the simple form, each line in the file consists of the canonical real name of an author, whitespace, and an email address used in the commit (enclosed by < and >) to map to the name. For example:

```
Proper Name <commit@email.xx>
```

The more complex forms are:

```
<proper@email.xx> <commit@email.xx>
```

which allows mailmap to replace only the email part of a commit, and:

```
Proper Name <proper@email.xx> <commit@email.xx>
```

which allows mailmap to replace both the name and the email of a commit matching the specified commit email address, and:

```
Proper Name <proper@email.xx> Commit Name <commit@email.xx>
```

which allows mailmap to replace both the name and the email of a commit matching both the specified commit name and email address.

Both E-Mails and names are matched case-insensitively. For example this would also match the Commit Name <commit@email.xx> above:

```
Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
```

## NOTES
Git does not follow symbolic links when accessing a .mailmap file in the working tree. This keeps behavior consistent when the file is accessed from the index or a tree versus from the filesystem.

## EXAMPLES
Your history contains commits by two authors, Jane and Joe, whose names appear in the repository under several forms:

```
Joe Developer <joe@example.com>
Joe R. Developer <joe@example.com>
Jane Doe <jane@example.com>
Jane Doe <jane@laptop.(none)>
Jane D. <jane@desktop.(none)>
```

Now suppose that Joe wants his middle name initial used, and Jane prefers her family name fully spelled out. A .mailmap file to correct the names would look like:

```
Joe R. Developer <joe@example.com>
Jane Doe <jane@example.com>
Jane Doe <jane@desktop.(none)>
```

Note that there’s no need to map the name for <jane@laptop.(none)> to only correct the names. However, leaving the obviously broken <jane@laptop.(none)> and <jane@desktop.(none)> E-Mails as-is is usually not what you want. A .mailmap file which also corrects those is:

```
Joe R. Developer <joe@example.com>
Jane Doe <jane@example.com> <jane@laptop.(none)>
Jane Doe <jane@example.com> <jane@desktop.(none)>
```

Finally, let’s say that Joe and Jane shared an E-Mail address, but not a name, e.g. by having these two commits in the history generated by a bug reporting system. I.e. names appearing in history as:

```
Joe <bugs@example.com>
Jane <bugs@example.com>
```

A full .mailmap file which also handles those cases (an addition of two lines to the above example) would be:

```
Joe R. Developer <joe@example.com>
Jane Doe <jane@example.com> <jane@laptop.(none)>
Jane Doe <jane@example.com> <jane@desktop.(none)>
Joe R. Developer <joe@example.com> Joe <bugs@example.com>
Jane Doe <jane@example.com> Jane <bugs@example.com>
```

## SEE ALSO
git-check-mailmap(1)

## GIT
Part of the git(1) suite


gitmodules

title: gitmodules(5)

summary: Defining submodule properties

text:
# gitmodules(5)

## NAME
gitmodules - Defining submodule properties

## SYNOPSIS
$GIT_WORK_TREE/.gitmodules

## DESCRIPTION
The .gitmodules file, located in the top-level directory of a Git working tree, is a text file with a syntax matching the requirements of git-config(1).

The file contains one subsection per submodule, and the subsection value is the name of the submodule. The name is set to the path where the submodule has been added unless it was customized with the --name option of git submodule add. Each submodule section also contains the following required keys:

submodule.<name>.path

Defines the path, relative to the top-level directory of the Git working tree, where the submodule is expected to be checked out. The path name must not end with a /. All submodule paths must be unique within the .gitmodules file.

submodule.<name>.url

Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to git-clone(1) or (if it begins with ./ or ../) a location relative to the superproject’s origin repository.

In addition, there are a number of optional keys:

submodule.<name>.update

Defines the default update procedure for the named submodule, i.e. how the submodule is updated by the git submodule update command in the superproject. This is only used by git submodule init to initialize the configuration variable of the same name. Allowed values here are checkout, rebase, merge or none, but not !command (for security reasons). See the description of the update command in git-submodule(1) for more details.

submodule.<name>.branch

A remote branch name for tracking updates in the upstream submodule. If the option is not specified, it defaults to the remote HEAD. A special value of . is used to indicate that the name of the branch in the submodule should be the same name as the current branch in the current repository. See the --remote documentation in git-submodule(1) for details.

submodule.<name>.fetchRecurseSubmodules

This option can be used to control recursive fetching of this submodule. If this option is also present in the submodule’s entry in .git/config of the superproject, the setting there will override the one found in .gitmodules. Both settings can be overridden on the command line by using the --[no-]recurse-submodules option to git fetch and git pull.

submodule.<name>.ignore

Defines under what circumstances git status and the diff family show a submodule as modified. The following values are supported: all

The submodule will never be considered modified (but will nonetheless show up in the output of status and commit when it has been staged).

dirty

All changes to the submodule’s work tree will be ignored, only committed differences between the HEAD of the submodule and its recorded state in the superproject are taken into account.

untracked

Only untracked files in submodules will be ignored. Committed differences and modifications to tracked files will show up.

none

No modifications to submodules are ignored, all of committed differences, and modifications to tracked and untracked files are shown. This is the default option.

If this option is also present in the submodule’s entry in .git/config of the superproject, the setting there will override the one found in .gitmodules.

Both settings can be overridden on the command line by using the --ignore-submodules option. The git submodule commands are not affected by this setting.

submodule.<name>.shallow

When set to true, a clone of this submodule will be performed as a shallow clone (with a history depth of 1) unless the user explicitly asks for a non-shallow clone.

## NOTES
Git does not allow the .gitmodules file within a working tree to be a symbolic link, and will refuse to check out such a tree entry. This keeps behavior consistent when the file is accessed from the index or a tree versus from the filesystem, and helps Git reliably enforce security checks of the file contents.

## EXAMPLES
Consider the following .gitmodules file:

```
[submodule "libfoo"]

        path = include/foo

        url = git://foo.com/git/lib.git
[submodule "libbar"]

        path = include/bar

        url = git://bar.com/git/lib.git
```

This defines two submodules, libfoo and libbar. These are expected to be checked out in the paths include/foo and include/bar, and for both submodules a URL is specified which can be used for cloning the submodules.

## SEE ALSO
git-submodule(1), gitsubmodules(7), git-config(1)

## GIT
Part of the git(1) suite


gitprotocol-capabilities

title: gitprotocol-capabilities(5)

summary: Protocol v0 and v1 capabilities

text:
# gitprotocol-capabilities(5)

## NAME
gitprotocol-capabilities - Protocol v0 and v1 capabilities

## SYNOPSIS

```
<over-the-wire-protocol>
```

## DESCRIPTION

Note this document describes capabilities for versions 0 and 1 of the pack protocol. For version 2, please refer to the 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.

## MULTI_ACK
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 -- S
```

If 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.

## MULTI_ACK_DETAILED
This is an extension of multi_ack that permits the client to better understand the server’s in-memory state. See gitprotocol-pack(5), section "Packfile Negotiation" for more information.

## NO-DONE
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.

## THIN-PACK
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.

## SIDE-BAND, SIDE-BAND-64K
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.

## OFS-DELTA
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.

## AGENT
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.

## OBJECT-FORMAT
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.

## SYMREF
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.

## SHALLOW
This capability adds "deepen", "shallow" and "unshallow" commands to the fetch-pack/upload-pack protocol so clients can request shallow clones.

## DEEPEN-SINCE
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".

## DEEPEN-NOT
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".

## DEEPEN-RELATIVE
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.

## NO-PROGRESS
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.

## INCLUDE-TAG
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.

## REPORT-STATUS
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 gitprotocol-pack(5) for example messages.

## REPORT-STATUS-V2
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 gitprotocol-pack(5) for details.

## DELETE-REFS
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.

## QUIET
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).

## ATOMIC
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.

## PUSH-OPTIONS
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.

## ALLOW-TIP-SHA1-IN-WANT
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.

## ALLOW-REACHABLE-SHA1-IN-WANT
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.

## PUSH-CERT=<NONCE>
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.

## FILTER
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.

## SESSION-ID=<SESSION-ID>
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[1] for details), but this may change and users of the session ID should not rely on this fact.

## GIT
Part of the git(1) suite

## NOTES
1.

api-trace2

file:///usr/share/doc/git/technical/api-trace2.html


gitprotocol-common

title: gitprotocol-common(5)

summary: Things common to various protocols

text:
# gitprotocol-common(5)

## NAME
gitprotocol-common - Things common to various protocols

## SYNOPSIS

```
<over-the-wire-protocol>
```

## DESCRIPTION
This document defines things common to various over-the-wire protocols and file formats used in Git.

## ABNF NOTATION
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:

1.They can include slash / for hierarchical (directory) grouping, but no slash-separated component can begin with a dot ..

2.They must contain at least one /. This enforces the presence of a category like heads/, tags/ etc. but the actual names are not restricted.

3.They cannot have two consecutive dots .. anywhere.

4.They cannot have ASCII control characters (i.e. bytes whose values are lower than \040, or \177 DEL), space, tilde ~, caret ^, colon :, question-mark ?, asterisk *, or open bracket [ anywhere.

5.They cannot end with a slash / or a dot ..

6.They cannot end with the sequence .lock.

7.They cannot contain a sequence @{.

8.They cannot contain a \\.

## PKT-LINE FORMAT
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"            ""
```

## GIT
Part of the git(1) suite