title: gitprotocol-v2(5)

summary: Git Wire Protocol, Version 2

text:
# gitprotocol-v2(5)

## NAME
gitprotocol-v2 - Git Wire Protocol, Version 2

## SYNOPSIS

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

## DESCRIPTION
This document presents a specification for a version 2 of Git’s wire protocol. Protocol v2 will improve upon v1 in the following ways:

•Instead of multiple service names, multiple commands will be supported by a single service

•Easily extendable as capabilities are moved into their own section of the protocol, no longer being hidden behind a NUL byte and limited by the size of a pkt-line

•Separate out other information hidden behind NUL bytes (e.g. agent string as a capability and symrefs can be requested using ls-refs)

•Reference advertisement will be omitted unless explicitly requested

•ls-refs command to explicitly request some refs

•Designed with http and stateless-rpc in mind. With clear flush semantics the http remote helper can simply act as a proxy

In protocol v2 communication is command oriented. When first contacting a server a list of capabilities will be advertised. Some of these capabilities will be commands which a client can request be executed. Once a command has completed, a client can reuse the connection and request that other commands be executed.

## PACKET-LINE FRAMING
All communication is done using packet-line framing, just as in v1. See gitprotocol-pack(5) and gitprotocol-common(5) for more information.

In protocol v2 these special packets will have the following semantics:

•0000 Flush Packet (flush-pkt) - indicates the end of a message

•0001 Delimiter Packet (delim-pkt) - separates sections of a message

•0002 Response End Packet (response-end-pkt) - indicates the end of a response for stateless connections

## INITIAL CLIENT REQUEST
In general a client can request to speak protocol v2 by sending version=2 through the respective side-channel for the transport being used which inevitably sets GIT_PROTOCOL. More information can be found in gitprotocol-pack(5) and gitprotocol-http(5), as well as the GIT_PROTOCOL definition in git.txt. In all cases the response from the server is the capability advertisement.

### Git Transport
When using the git:// transport, you can request to use protocol v2 by sending "version=2" as an extra parameter:

```
003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0
```

### SSH and File Transport
When using either the ssh:// or file:// transport, the GIT_PROTOCOL environment variable must be set explicitly to include "version=2". The server may need to be configured to allow this environment variable to pass.

### HTTP Transport
When using the http:// or https:// transport a client makes a "smart" info/refs request as described in gitprotocol-http(5) and requests that v2 be used by supplying "version=2" in the Git-Protocol header.

```
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
C: Git-Protocol: version=2
```

A v2 server would reply:

```
S: 200 OK
S: <Some headers>
S: ...
S:
S: 000eversion 2\n
S: <capability-advertisement>
```

Subsequent requests are then made directly to the service $GIT_URL/git-upload-pack. (This works the same for git-receive-pack).

Uses the --http-backend-info-refs option to git-upload-pack(1).

The server may need to be configured to pass this header’s contents via the GIT_PROTOCOL variable. See the discussion in git-http-backend.txt.

## CAPABILITY ADVERTISEMENT
A server which decides to communicate (based on a request from a client) using protocol version 2, notifies the client by sending a version string in its initial response followed by an advertisement of its capabilities. Each capability is a key with an optional value. Clients must ignore all unknown keys. Semantics of unknown values are left to the definition of each key. Some capabilities will describe commands which can be requested to be executed by the client.

```
capability-advertisement = protocol-version

                           capability-list

                           flush-pkt
```

```
protocol-version = PKT-LINE("version 2" LF)
capability-list = *capability
capability = PKT-LINE(key[=value] LF)
```

```
key = 1*(ALPHA | DIGIT | "-_")
value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;")
```

## COMMAND REQUEST
After receiving the capability advertisement, a client can then issue a request to select the command it wants with any particular capabilities or arguments. There is then an optional section where the client can provide any command specific parameters or queries. Only a single command can be requested at a time.

```
request = empty-request | command-request
empty-request = flush-pkt
command-request = command

                  capability-list

                  delim-pkt

                  command-args

                  flush-pkt
command = PKT-LINE("command=" key LF)
command-args = *command-specific-arg
```

```
command-specific-args are packet line framed arguments defined by
each individual command.
```

The server will then check to ensure that the client’s request is comprised of a valid command as well as valid capabilities which were advertised. If the request is valid the server will then execute the command. A server MUST wait till it has received the client’s entire request before issuing a response. The format of the response is determined by the command being executed, but in all cases a flush-pkt indicates the end of the response.

When a command has finished, and the client has received the entire response from the server, a client can either request that another command be executed or can terminate the connection. A client may optionally send an empty request consisting of just a flush-pkt to indicate that no more requests will be made.

## CAPABILITIES
There are two different types of capabilities: normal capabilities, which can be used to convey information or alter the behavior of a request, and commands, which are the core actions that a client wants to perform (fetch, push, etc).

Protocol version 2 is stateless by default. This means that all commands must only last a single round and be stateless from the perspective of the server side, unless the client has requested a capability indicating that state should be maintained by the server. Clients MUST NOT require state management on the server side in order to function correctly. This permits simple round-robin load-balancing on the server side, without needing to worry about state management.

### agent
The server can advertise the agent capability with a value X (in the form agent=X) to notify the client that the server is running version X. The client may optionally send its own agent string by including the agent capability with a value Y (in the form agent=Y) in its request to the server (but it MUST NOT do so if the server did not advertise the agent capability). The X and Y strings may contain any printable ASCII characters except space (i.e., the byte range 33 ⟨ x ⟨ 126), and are typically of the form "package/version-os" (e.g., "git/1.8.3.1-Linux") where os is the operating system name (e.g., "Linux"). X and Y can be configured using the GIT_USER_AGENT environment variable and it takes priority. The os is retrieved using the sysname field of the uname(2) system call or its equivalent. The agent strings are purely informative for statistics and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features.

### ls-refs
ls-refs is the command used to request a reference advertisement in v2. Unlike the current reference advertisement, ls-refs takes in arguments which can be used to limit the refs sent from the server.

Additional features not supported in the base command will be advertised as the value of the command in the capability advertisement in the form of a space separated list of features: "<command>=<feature-1> <feature-2>"

ls-refs takes in the following arguments:

```
symrefs

    In addition to the object pointed by it, show the underlying ref

    pointed by it when showing a symbolic ref.
peel

    Show peeled tags.
ref-prefix <prefix>

    When specified, only references having a prefix matching one of

    the provided prefixes are displayed. Multiple instances may be

    given, in which case references matching any prefix will be

    shown. Note that this is purely for optimization; a server MAY

    show refs not matching the prefix if it chooses, and clients

    should filter the result themselves.
```

If the unborn feature is advertised the following argument can be included in the client’s request.

```
unborn

    The server will send information about HEAD even if it is a symref

    pointing to an unborn branch in the form "unborn HEAD

    symref-target:<target>".
```

The output of ls-refs is as follows:

```
output = *ref

         flush-pkt
obj-id-or-unborn = (obj-id | "unborn")
ref = PKT-LINE(obj-id-or-unborn SP refname *(SP ref-attribute) LF)
ref-attribute = (symref | peeled)
symref = "symref-target:" symref-target
peeled = "peeled:" obj-id
```

### fetch
fetch is the command used to fetch a packfile in v2. It can be looked at as a modified version of the v1 fetch where the ref-advertisement is stripped out (since the ls-refs command fills that role) and the message format is tweaked to eliminate redundancies and permit easy addition of future extensions.

Additional features not supported in the base command will be advertised as the value of the command in the capability advertisement in the form of a space separated list of features: "<command>=<feature-1> <feature-2>"

A fetch request can take the following arguments:

```
want <oid>

    Indicates to the server an object which the client wants to

    retrieve.  Wants can be anything and are not limited to

    advertised objects.
```

```
have <oid>

    Indicates to the server an object which the client has locally.

    This allows the server to make a packfile which only contains

    the objects that the client needs. Multiple 'have' lines can be

    supplied.
```

```
done

    Indicates to the server that negotiation should terminate (or

    not even begin if performing a clone) and that the server should

    use the information supplied in the request to construct the

    packfile.
```

```
thin-pack

    Request that a thin pack be sent, which is a pack with deltas

    which reference base objects not contained within the pack (but

    are known to exist at the receiving end). This can reduce the

    network traffic significantly, but it requires the receiving end

    to know how to "thicken" these packs by adding the missing bases

    to the pack.
```

```
no-progress

    Request that progress information that would normally be sent on

    side-band channel 2, during the packfile transfer, should not be

    sent.  However, the side-band channel 3 is still used for error

    responses.
```

```
include-tag

    Request that annotated tags should be sent if the objects they

    point to are being sent.
```

```
ofs-delta

    Indicate that the client understands PACKv2 with delta referring

    to its base by position in pack rather than by an oid.  That is,

    they can read OBJ_OFS_DELTA (aka type 6) in a packfile.
```

If the shallow feature is advertised the following arguments can be included in the clients request as well as the potential addition of the shallow-info section in the server’s response as explained below.

```
shallow <oid>

    A client must notify the server of all commits for which it only

    has shallow copies (meaning that it doesn't have the parents of

    a commit) by supplying a 'shallow <oid>' line for each such

    object so that the server is aware of the limitations of the

    client's history.  This is so that the server is aware that the

    client may not have all objects reachable from such commits.
```

```
deepen <depth>

    Requests that the fetch/clone should be shallow having a commit

    depth of <depth> relative to the remote side.
```

```
deepen-relative

    Requests that the semantics of the "deepen" command be changed

    to indicate that the depth requested is relative to the client's

    current shallow boundary, instead of relative to the requested

    commits.
```

```
deepen-since <timestamp>

    Requests that the shallow clone/fetch should be cut at a

    specific time, instead of depth.  Internally it's equivalent to

    doing "git rev-list --max-age=<timestamp>". Cannot be used with

    "deepen".
```

```
deepen-not <rev>

    Requests that the shallow clone/fetch should be cut at a

    specific revision specified by '<rev>', instead of a depth.

    Internally it's equivalent of doing "git rev-list --not <rev>".

    Cannot be used with "deepen", but can be used with

    "deepen-since".
```

If the filter feature is advertised, the following argument can be included in the client’s request:

```
filter <filter-spec>

    Request that various objects from the packfile be omitted

    using one of several filtering techniques. These are intended

    for use with partial clone and partial fetch operations. See

    `rev-list` for possible "filter-spec" values. When communicating

    with other processes, senders SHOULD translate scaled integers

    (e.g. "1k") into a fully-expanded form (e.g. "1024") to aid

    interoperability with older receivers that may not understand

    newly-invented scaling suffixes. However, receivers SHOULD

    accept the following suffixes: 'k', 'm', and 'g' for 1024,

    1048576, and 1073741824, respectively.
```

If the ref-in-want feature is advertised, the following argument can be included in the client’s request as well as the potential addition of the wanted-refs section in the server’s response as explained below.

```
want-ref <ref>

    Indicates to the server that the client wants to retrieve a

    particular ref, where <ref> is the full name of a ref on the

    server.  It is a protocol error to send want-ref for the

    same ref more than once.
```

If the sideband-all feature is advertised, the following argument can be included in the client’s request:

```
sideband-all

    Instruct the server to send the whole response multiplexed, not just

    the packfile section. All non-flush and non-delim PKT-LINE in the

    response (not only in the packfile section) will then start with a byte

    indicating its sideband (1, 2, or 3), and the server may send "0005\2"

    (a PKT-LINE of sideband 2 with no payload) as a keepalive packet.
```

If the packfile-uris feature is advertised, the following argument can be included in the client’s request as well as the potential addition of the packfile-uris section in the server’s response as explained below. Note that at most one packfile-uris line can be sent to the server.

```
packfile-uris <comma-separated-list-of-protocols>

    Indicates to the server that the client is willing to receive

    URIs of any of the given protocols in place of objects in the

    sent packfile. Before performing the connectivity check, the

    client should download from all given URIs. Currently, the

    protocols supported are "http" and "https".
```

If the wait-for-done feature is advertised, the following argument can be included in the client’s request.

```
wait-for-done

    Indicates to the server that it should never send "ready", but

    should wait for the client to say "done" before sending the

    packfile.
```

The response of fetch is broken into a number of sections separated by delimiter packets (0001), with each section beginning with its section header. Most sections are sent only when the packfile is sent.

```
output = acknowledgements flush-pkt |

         [acknowledgments delim-pkt] [shallow-info delim-pkt]

         [wanted-refs delim-pkt] [packfile-uris delim-pkt]

         packfile flush-pkt
```

```
acknowledgments = PKT-LINE("acknowledgments" LF)

                  (nak | *ack)

                  (ready)
ready = PKT-LINE("ready" LF)
nak = PKT-LINE("NAK" LF)
ack = PKT-LINE("ACK" SP obj-id LF)
```

```
shallow-info = PKT-LINE("shallow-info" LF)

               *PKT-LINE((shallow | unshallow) LF)
shallow = "shallow" SP obj-id
unshallow = "unshallow" SP obj-id
```

```
wanted-refs = PKT-LINE("wanted-refs" LF)

              *PKT-LINE(wanted-ref LF)
wanted-ref = obj-id SP refname
```

```
packfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri
packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)
```

```
packfile = PKT-LINE("packfile" LF)

           *PKT-LINE(%x01-03 *%x00-ff)
```

```
acknowledgments section

    * If the client determines that it is finished with negotiations by

      sending a "done" line (thus requiring the server to send a packfile),

      the acknowledgments sections MUST be omitted from the server's

      response.
```

•Always begins with the section header "acknowledgments"

•The server will respond with "NAK" if none of the object ids sent as have lines were common.

•The server will respond with "ACK obj-id" for all of the object ids sent as have lines which are common.

•A response cannot have both "ACK" lines as well as a "NAK" line.

•The server will respond with a "ready" line indicating that the server has found an acceptable common base and is ready to make and send a packfile (which will be found in the packfile section of the same response)

•If the server has found a suitable cut point and has decided to send a "ready" line, then the server can decide to (as an optimization) omit any "ACK" lines it would have sent during its response. This is because the server will have already determined the objects it plans to send to the client and no further negotiation is needed.

```
shallow-info section

    * If the client has requested a shallow fetch/clone, a shallow

      client requests a fetch or the server is shallow then the

      server's response may include a shallow-info section.  The

      shallow-info section will be included if (due to one of the

      above conditions) the server needs to inform the client of any

      shallow boundaries or adjustments to the clients already

      existing shallow boundaries.
```

•Always begins with the section header "shallow-info"

•If a positive depth is requested, the server will compute the set of commits which are no deeper than the desired depth.

•The server sends a "shallow obj-id" line for each commit whose parents will not be sent in the following packfile.

•The server sends an "unshallow obj-id" line for each commit which the client has indicated is shallow, but is no longer shallow as a result of the fetch (due to its parents being sent in the following packfile).

•The server MUST NOT send any "unshallow" lines for anything which the client has not indicated was shallow as a part of its request.

```
wanted-refs section

    * This section is only included if the client has requested a

      ref using a 'want-ref' line and if a packfile section is also

      included in the response.
```

•Always begins with the section header "wanted-refs".

•The server will send a ref listing ("<oid> <refname>") for each reference requested using want-ref lines.

•The server MUST NOT send any refs which were not requested using want-ref lines.

```
packfile-uris section

    * This section is only included if the client sent

      'packfile-uris' and the server has at least one such URI to

      send.
```

•Always begins with the section header "packfile-uris".

•For each URI the server sends, it sends a hash of the pack’s contents (as output by git index-pack) followed by the URI.

•The hashes are 40 hex characters long. When Git upgrades to a new hash algorithm, this might need to be updated. (It should match whatever index-pack outputs after "pack\t" or "keep\t".

```
packfile section

    * This section is only included if the client has sent 'want'

      lines in its request and either requested that no more

      negotiation be done by sending 'done' or if the server has

      decided it has found a sufficient cut point to produce a

      packfile.
```

•Always begins with the section header "packfile"

•The transmission of the packfile begins immediately after the section header

•The data transfer of the packfile is always multiplexed, using the same semantics of the side-band-64k capability from protocol version 1. This means that each packet, during the packfile data stream, is made up of a leading 4-byte pkt-line length (typical of the pkt-line format), followed by a 1-byte stream code, followed by the actual data.

```
The stream code can be one of:

      1 - pack data

      2 - progress messages

      3 - fatal error message just before stream aborts
```

### server-option
If advertised, indicates that any number of server specific options can be included in a request. This is done by sending each option as a "server-option=<option>" capability line in the capability-list section of a request.

The provided options must not contain a NUL or LF character.

### object-format
The server can advertise the object-format capability with a value X (in the form object-format=X) to notify the client that the server is able to deal with objects using hash algorithm X. If not specified, the server is assumed to only handle SHA-1. If the client would like to use a hash algorithm other than SHA-1, it should specify its object-format string.

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

### object-info
object-info is the command to retrieve information about one or more objects. Its main purpose is to allow a client to make decisions based on this information without having to fully fetch objects. Object size is the only information that is currently supported.

An object-info request takes the following arguments:

```
size
Requests size information to be returned for each listed object id.
```

```
oid <oid>
Indicates to the server an object which the client wants to obtain
information for.
```

The response of object-info is a list of the requested object ids and associated requested information, each separated by a single space.

```
output = info flush-pkt
```

```
info = PKT-LINE(attrs) LF)

        *PKT-LINE(obj-info LF)
```

```
attrs = attr | attrs SP attrs
```

```
attr = "size"
```

```
obj-info = obj-id SP obj-size
```

### bundle-uri
If the bundle-uri capability is advertised, the server supports the ‘bundle-uri’ command.

The capability is currently advertised with no value (i.e. not "bundle-uri=somevalue"), a value may be added in the future for supporting command-wide extensions. Clients MUST ignore any unknown capability values and proceed with the 'bundle-uri` dialog they support.

The bundle-uri command is intended to be issued before fetch to get URIs to bundle files (see git-bundle(1)) to "seed" and inform the subsequent fetch command.

The client CAN issue bundle-uri before or after any other valid command. To be useful to clients it’s expected that it’ll be issued after an ls-refs and before fetch, but CAN be issued at any time in the dialog.

DISCUSSION of bundle-uri

The intent of the feature is optimize for server resource consumption in the common case by changing the common case of fetching a very large PACK during git-clone(1) into a smaller incremental fetch.

It also allows servers to achieve better caching in combination with an uploadpack.packObjectsHook (see git-config(1)).

By having new clones or fetches be a more predictable and common negotiation against the tips of recently produces *.bundle file(s). Servers might even pre-generate the results of such negotiations for the uploadpack.packObjectsHook as new pushes come in.

One way that servers could take advantage of these bundles is that the server would anticipate that fresh clones will download a known bundle, followed by catching up to the current state of the repository using ref tips found in that bundle (or bundles).

PROTOCOL for bundle-uri

A bundle-uri request takes no arguments, and as noted above does not currently advertise a capability value. Both may be added in the future.

When the client issues a command=bundle-uri request, the response is a list of key-value pairs provided as packet lines with value <key>=<value>. Each <key> should be interpreted as a config key from the bundle.* namespace to construct a list of bundles. These keys are grouped by a bundle.<id>. subsection, where each key corresponding to a given <id> contributes attributes to the bundle defined by that <id>. See git-config(1) for the specific details of these keys and how the Git client will interpret their values.

Clients MUST parse the line according to the above format, lines that do not conform to the format SHOULD be discarded. The user MAY be warned in such a case.

bundle-uri CLIENT AND SERVER EXPECTATIONS

URI CONTENTS

The content at the advertised URIs MUST be one of two types. The advertised URI may contain a bundle file that git bundle verify would accept. I.e. they MUST contain one or more reference tips for use by the client, MUST indicate prerequisites (in any) with standard "-" prefixes, and MUST indicate their "object-format", if applicable.

The advertised URI may alternatively contain a plaintext file that git config --list would accept (with the --file option). The key-value pairs in this list are in the bundle.* namespace (see git-config(1)).

bundle-uri CLIENT ERROR RECOVERY

A client MUST above all gracefully degrade on errors, whether that error is because of bad missing/data in the bundle URI(s), because that client is too dumb to e.g. understand and fully parse out bundle headers and their prerequisite relationships, or something else. Server operators should feel confident in turning on "bundle-uri" and not worry if e.g. their CDN goes down that clones or fetches will run into hard failures. Even if the server bundle(s) are incomplete, or bad in some way the client should still end up with a functioning repository, just as if it had chosen not to use this protocol extension.

All subsequent discussion on client and server interaction MUST keep this in mind.

bundle-uri SERVER TO CLIENT

The ordering of the returned bundle uris is not significant. Clients MUST parse their headers to discover their contained OIDS and prerequisites. A client MUST consider the content of the bundle(s) themselves and their header as the ultimate source of truth. A server MAY even return bundle(s) that don’t have any direct relationship to the repository being cloned (either through accident, or intentional "clever" configuration), and expect a client to sort out what data they’d like from the bundle(s), if any.

bundle-uri CLIENT TO SERVER

The client SHOULD provide reference tips found in the bundle header(s) as have lines in any subsequent fetch request. A client MAY also ignore the bundle(s) entirely if doing so is deemed worse for some reason, e.g. if the bundles can’t be downloaded, it doesn’t like the tips it finds etc.

WHEN ADVERTISED BUNDLE(S) REQUIRE NO FURTHER NEGOTIATION

If after issuing bundle-uri and ls-refs, and getting the header(s) of the bundle(s) the client finds that the ref tips it wants can be retrieved entirely from advertised bundle(s), the client MAY disconnect from the Git server. The results of such a clone or fetch should be indistinguishable from the state attained without using bundle-uri.

EARLY CLIENT DISCONNECTIONS AND ERROR RECOVERY

A client MAY perform an early disconnect while still downloading the bundle(s) (having streamed and parsed their headers). In such a case the client MUST gracefully recover from any errors related to finishing the download and validation of the bundle(s). I.e. a client might need to re-connect and issue a fetch command, and possibly fall back to not making use of bundle-uri at all.

This "MAY" behavior is specified as such (and not a "SHOULD") on the assumption that a server advertising bundle uris is more likely than not to be serving up a relatively large repository, and to be pointing to URIs that have a good chance of being in working order. A client MAY e.g. look at the payload size of the bundles as a heuristic to see if an early disconnect is worth it, should falling back on a full "fetch" dialog be necessary.

WHEN ADVERTISED BUNDLE(S) REQUIRE FURTHER NEGOTIATION

A client SHOULD commence a negotiation of a PACK from the server via the "fetch" command using the OID tips found in advertised bundles, even if’s still in the process of downloading those bundle(s). This allows for aggressive early disconnects from any interactive server dialog. The client blindly trusts that the advertised OID tips are relevant, and issues them as have lines, it then requests any tips it would like (usually from the "ls-refs" advertisement) via want lines. The server will then compute a (hopefully small) PACK with the expected difference between the tips from the bundle(s) and the data requested.

The only connection the client then needs to keep active is to the concurrently downloading static bundle(s), when those and the incremental PACK are retrieved they should be inflated and validated. Any errors at this point should be gracefully recovered from, see above.

bundle-uri PROTOCOL FEATURES

The client constructs a bundle list from the <key>=<value> pairs provided by the server. These pairs are part of the bundle.* namespace as documented in git-config(1). In this section, we discuss some of these keys and describe the actions the client will do in response to this information.

In particular, the bundle.version key specifies an integer value. The only accepted value at the moment is 1, but if the client sees an unexpected value here then the client MUST ignore the bundle list.

As long as bundle.version is understood, all other unknown keys MAY be ignored by the client. The server will guarantee compatibility with older clients, though newer clients may be better able to use the extra keys to minimize downloads.

Any backwards-incompatible addition of pre-URI key-value will be guarded by a new bundle.version value or values in bundle-uri capability advertisement itself, and/or by new future bundle-uri request arguments.

Some example key-value pairs that are not currently implemented but could be implemented in the future include:

•Add a "hash=<val>" or "size=<bytes>" advertise the expected hash or size of the bundle file.

•Advertise that one or more bundle files are the same (to e.g. have clients round-robin or otherwise choose one of N possible files).

•A "oid=<OID>" shortcut and "prerequisite=<OID>" shortcut. For expressing the common case of a bundle with one tip and no prerequisites, or one tip and one prerequisite. This would allow for optimizing the common case of servers who’d like to provide one "big bundle" containing only their "main" branch, and/or incremental updates thereof.

A client receiving such a response MAY assume that they can skip retrieving the header from a bundle at the indicated URI, and thus save themselves and the server(s) the request(s) needed to inspect the headers of that bundle or bundles.

### promisor-remote=<pr-infos>
The server may advertise some promisor remotes it is using or knows about to a client which may want to use them as its promisor remotes, instead of this repository. In this case <pr-infos> should be of the form:

```
pr-infos = pr-info | pr-infos ";" pr-info
```

```
pr-info = "name=" pr-name | "name=" pr-name "," "url=" pr-url
```

where pr-name is the urlencoded name of a promisor remote, and pr-url the urlencoded URL of that promisor remote.

In this case, if the client decides to use one or more promisor remotes the server advertised, it can reply with "promisor-remote=<pr-names>" where <pr-names> should be of the form:

```
pr-names = pr-name | pr-names ";" pr-name
```

where pr-name is the urlencoded name of a promisor remote the server advertised and the client accepts.

Note that, everywhere in this document, pr-name MUST be a valid remote name, and the ; and , characters MUST be encoded if they appear in pr-name or pr-url.

If the server doesn’t know any promisor remote that could be good for a client to use, or prefers a client not to use any promisor remote it uses or knows about, it shouldn’t advertise the "promisor-remote" capability at all.

In this case, or if the client doesn’t want to use any promisor remote the server advertised, the client shouldn’t advertise the "promisor-remote" capability at all in its reply.

The "promisor.advertise" and "promisor.acceptFromServer" configuration options can be used on the server and client side to control what they advertise or accept respectively. See the documentation of these configuration options for more information.

Note that in the future it would be nice if the "promisor-remote" protocol capability could be used by the server, when responding to git fetch or git clone, to advertise better-connected remotes that the client can use as promisor remotes, instead of this repository, so that the client can lazily fetch objects from these other better-connected remotes. This would require the server to omit in its response the objects available on the better-connected remotes that the client has accepted. This hasn’t been implemented yet though. So for now this "promisor-remote" capability is useful only when the server advertises some promisor remotes it already uses to borrow objects from.

## GIT
Part of the git(1) suite

## NOTES
1.

api-trace2

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


gitrepository-layout

package: git-core

title: gitrepository-layout(5)

summary: Git Repository Layout

text:
# gitrepository-layout(5)

## NAME
gitrepository-layout - Git Repository Layout

## SYNOPSIS
$GIT_DIR/*

## DESCRIPTION
A Git repository comes in two different flavours:

•a .git directory at the root of the working tree;

•a <project>.git directory that is a bare repository (i.e. without its own working tree), that is typically used for exchanging histories with others by pushing into it and fetching from it.

Note: Also you can have a plain text file .git at the root of your working tree, containing gitdir: <path> to point at the real directory that has the repository. This mechanism is called a gitfile and is usually managed via the git submodule and git worktree commands. It is often used for a working tree of a submodule checkout, to allow you in the containing superproject to git checkout a branch that does not have the submodule. The checkout has to remove the entire submodule working tree, without losing the submodule repository.

These things may exist in a Git repository.

objects

Object store associated with this repository. Usually an object store is self sufficient (i.e. all the objects that are referred to by an object found in it are also found in it), but there are a few ways to violate it.

1.You could have an incomplete but locally usable repository by creating a shallow clone. See git-clone(1).

2.You could be using the objects/info/alternates or $GIT_ALTERNATE_OBJECT_DIRECTORIES mechanisms to borrow objects from other object stores. A repository with this kind of incomplete object store is not suitable to be published for use with dumb transports but otherwise is OK as long as objects/info/alternates points at the object stores it borrows from. This directory is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/objects" will be used instead.

objects/[0-9a-f][0-9a-f]

A newly created object is stored in its own file. The objects are splayed over 256 subdirectories using the first two characters of the sha1 object name to keep the number of directory entries in objects itself to a manageable number. Objects found here are often called unpacked (or loose) objects.

objects/pack

Packs (files that store many objects in compressed form, along with index files to allow them to be randomly accessed) are found in this directory.

objects/info

Additional information about the object store is recorded in this directory.

objects/info/packs

This file is to help dumb transports discover what packs are available in this object store. Whenever a pack is added or removed, git update-server-info should be run to keep this file up to date if the repository is published for dumb transports. git repack does this by default.

objects/info/alternates

This file records paths to alternate object stores that this object store borrows objects from, one pathname per line. Note that not only native Git tools use it locally, but the HTTP fetcher also tries to use it remotely; this will usually work if you have relative paths (relative to the object database, not to the repository!) in your alternates file, but it will not work if you use absolute paths unless the absolute path in filesystem and web URL is the same. See also objects/info/http-alternates.

objects/info/http-alternates

This file records URLs to alternate object stores that this object store borrows objects from, to be used when the repository is fetched over HTTP.

refs

References are stored in subdirectories of this directory. The git prune command knows to preserve objects reachable from refs found in this directory and its subdirectories. This directory is ignored (except refs/bisect, refs/rewritten and refs/worktree) if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/refs" will be used instead.

refs/heads/name

records tip-of-the-tree commit objects of branch name

refs/tags/name

records any object name (not necessarily a commit object, or a tag object that points at a commit object).

refs/remotes/name

records tip-of-the-tree commit objects of branches copied from a remote repository.

refs/replace/<obj-sha1>

records the SHA-1 of the object that replaces <obj-sha1>. This is similar to info/grafts and is internally used and maintained by git-replace(1). Such refs can be exchanged between repositories while grafts are not.

packed-refs

records the same information as refs/heads/, refs/tags/, and friends record in a more efficient way. See git-pack-refs(1). This file is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/packed-refs" will be used instead.

HEAD

A symref (see glossary) to the refs/heads/ namespace describing the currently active branch. It does not mean much if the repository is not associated with any working tree (i.e. a bare repository), but a valid Git repository must have the HEAD file; some porcelains may use it to guess the designated "default" branch of the repository (usually master). It is legal if the named branch name does not (yet) exist. In some legacy setups, it is a symbolic link instead of a symref that points at the current branch. HEAD can also record a specific commit directly, instead of being a symref to point at the current branch. Such a state is often called detached HEAD. See git-checkout(1) for details.

config

Repository specific configuration file. This file is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be used instead.

config.worktree

Working directory specific configuration file for the main working directory in multiple working directory setup (see git-worktree(1)).

branches

A deprecated way to store shorthands to be used to specify a URL to git fetch, git pull and git push. A file can be stored as branches/<name> and then name can be given to these commands in place of repository argument. See the REMOTES section in git-fetch(1) for details. This mechanism is legacy and not likely to be found in modern repositories. This directory is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/branches" will be used instead. Git will stop reading remotes from this directory in Git 3.0.

hooks

Hooks are customization scripts used by various Git commands. A handful of sample hooks are installed when git init is run, but all of them are disabled by default. To enable, the .sample suffix has to be removed from the filename by renaming. Read githooks(5) for more details about each hook. This directory is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/hooks" will be used instead.

common

When multiple working trees are used, most of files in $GIT_DIR are per-worktree with a few known exceptions. All files under common however will be shared between all working trees.

index

The current index file for the repository. It is usually not found in a bare repository.

sharedindex.<SHA-1>

The shared index part, to be referenced by $GIT_DIR/index and other temporary index files. Only valid in split index mode.

info

Additional information about the repository is recorded in this directory. This directory is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/info" will be used instead.

info/refs

This file helps dumb transports discover what refs are available in this repository. If the repository is published for dumb transports, this file should be regenerated by git update-server-info every time a tag or branch is created or modified. This is normally done from the hooks/update hook, which is run by the git-receive-pack command when you git push into the repository.

info/grafts

This file records fake commit ancestry information, to pretend the set of parents a commit has is different from how the commit was actually created. One record per line describes a commit and its fake parents by listing their 40-byte hexadecimal object names separated by a space and terminated by a newline. Note that the grafts mechanism is outdated and can lead to problems transferring objects between repositories; see git-replace(1) for a more flexible and robust system to do the same thing.

info/exclude

This file, by convention among Porcelains, stores the exclude pattern list. .gitignore is the per-directory ignore file. git status, git add, git rm and git clean look at it but the core Git commands do not look at it. See also: gitignore(5).

info/attributes

Defines which attributes to assign to a path, similar to per-directory .gitattributes files. See also: gitattributes(5).

info/sparse-checkout

This file stores sparse checkout patterns. See also: git-read-tree(1).

remotes

Stores shorthands for URL and default refnames for use when interacting with remote repositories via git fetch, git pull and git push commands. See the REMOTES section in git-fetch(1) for details. This mechanism is legacy and not likely to be found in modern repositories. This directory is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/remotes" will be used instead. Git will stop reading remotes from this directory in Git 3.0.

logs

Records of changes made to refs are stored in this directory. See git-update-ref(1) for more information. This directory is ignored (except logs/HEAD) if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/logs" will be used instead.

logs/refs/heads/name

Records all changes made to the branch tip named name.

logs/refs/tags/name

Records all changes made to the tag named name.

shallow

This is similar to info/grafts but is internally used and maintained by shallow clone mechanism. See --depth option to git-clone(1) and git-fetch(1). This file is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/shallow" will be used instead.

commondir

If this file exists, $GIT_COMMON_DIR (see git(1)) will be set to the path specified in this file if it is not explicitly set. If the specified path is relative, it is relative to $GIT_DIR. The repository with commondir is incomplete without the repository pointed by "commondir".

modules

Contains the git-repositories of the submodules.

worktrees

Contains administrative data for linked working trees. Each subdirectory contains the working tree-related part of a linked working tree. This directory is ignored if $GIT_COMMON_DIR is set, in which case "$GIT_COMMON_DIR/worktrees" will be used instead.

worktrees/<id>/gitdir

A text file containing the absolute path back to the .git file that points to here. This is used to check if the linked repository has been manually removed and there is no need to keep this directory any more. The mtime of this file should be updated every time the linked repository is accessed.

worktrees/<id>/locked

If this file exists, the linked working tree may be on a portable device and not available. The presence of this file prevents worktrees/<id> from being pruned either automatically or manually by git worktree prune. The file may contain a string explaining why the repository is locked.

worktrees/<id>/config.worktree

Working directory specific configuration file.

## GIT REPOSITORY FORMAT VERSIONS
Every git repository is marked with a numeric version in the core.repositoryformatversion key of its config file. This version specifies the rules for operating on the on-disk repository data. An implementation of git which does not understand a particular version advertised by an on-disk repository MUST NOT operate on that repository; doing so risks not only producing wrong results, but actually losing data.

Because of this rule, version bumps should be kept to an absolute minimum. Instead, we generally prefer these strategies:

•bumping format version numbers of individual data files (e.g., index, packfiles, etc). This restricts the incompatibilities only to those files.

•introducing new data that gracefully degrades when used by older clients (e.g., pack bitmap files are ignored by older clients, which simply do not take advantage of the optimization they provide).

A whole-repository format version bump should only be part of a change that cannot be independently versioned. For instance, if one were to change the reachability rules for objects, or the rules for locking refs, that would require a bump of the repository format version.

Note that this applies only to accessing the repository’s disk contents directly. An older client which understands only format 0 may still connect via git:// to a repository using format 1, as long as the server process understands format 1.

The preferred strategy for rolling out a version bump (whether whole repository or for a single file) is to teach git to read the new format, and allow writing the new format with a config switch or command line option (for experimentation or for those who do not care about backwards compatibility with older gits). Then after a long period to allow the reading capability to become common, we may switch to writing the new format by default.

The currently defined format versions are:

### Version 0
This is the format defined by the initial version of git, including but not limited to the format of the repository directory, the repository configuration file, and the object and ref storage. Specifying the complete behavior of git is beyond the scope of this document.

### Version 1
This format is identical to version 0, with the following exceptions:

1.When reading the core.repositoryformatversion variable, a git implementation which supports version 1 MUST also read any configuration keys found in the extensions section of the configuration file.

2.If a version-1 repository specifies any extensions.* keys that the running git has not implemented, the operation MUST NOT proceed. Similarly, if the value of any known key is not understood by the implementation, the operation MUST NOT proceed.

Note that if no extensions are specified in the config file, then core.repositoryformatversion SHOULD be set to 0 (setting it to 1 provides no benefit, and makes the repository incompatible with older implementations of git).

The defined extensions are given in the extensions.* section of git-config(1). Any implementation wishing to define a new extension should make a note of it there, in order to claim the name.

## SEE ALSO
git-init(1), git-clone(1), git-config(1), git-fetch(1), git-pack-refs(1), git-gc(1), git-checkout(1), gitglossary(7), The Git User’s Manual[1]

## GIT
Part of the git(1) suite

## NOTES
1.

The Git User’s Manual

file:///usr/share/doc/git/user-manual.html


gitweb.conf

package: gitweb

title: gitweb.conf(5)

text:
# gitweb.conf(5)

## NAME
gitweb.conf - Gitweb (Git web interface) configuration file

## SYNOPSIS
/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl

## DESCRIPTION
The gitweb CGI script for viewing Git repositories over the web uses a perl script fragment as its configuration file. You can set variables using "our $variable = value"; text from a "#" character until the end of a line is ignored. See perlsyn(1) for details.

An example:

```
# gitweb configuration file for http://git.example.org
#
our $projectroot = "/srv/git"; # FHS recommendation
our $site_name = 'Example.org >> Repos';
```

The configuration file is used to override the default settings that were built into gitweb at the time the gitweb.cgi script was generated.

While one could just alter the configuration settings in the gitweb CGI itself, those changes would be lost upon upgrade. Configuration settings might also be placed into a file in the same directory as the CGI script with the default name gitweb_config.perl — allowing one to have multiple gitweb instances with different configurations by the use of symlinks.

Note that some configuration can be controlled on per-repository rather than gitweb-wide basis: see "Per-repository gitweb configuration" subsection on gitweb(1) manpage.

## DISCUSSION
Gitweb reads configuration data from the following sources in the following order:

•built-in values (some set during build stage),

•common system-wide configuration file (defaults to /etc/gitweb-common.conf),

•either per-instance configuration file (defaults to gitweb_config.perl in the same directory as the installed gitweb), or if it does not exist then fallback system-wide configuration file (defaults to /etc/gitweb.conf).

Values obtained in later configuration files override values obtained earlier in the above sequence.

Locations of the common system-wide configuration file, the fallback system-wide configuration file and the per-instance configuration file are defined at compile time using build-time Makefile configuration variables, respectively GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and GITWEB_CONFIG.

You can also override locations of gitweb configuration files during runtime by setting the following environment variables: GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and GITWEB_CONFIG to a non-empty value.

The syntax of the configuration files is that of Perl, since these files are handled by sourcing them as fragments of Perl code (the language that gitweb itself is written in). Variables are typically set using the our qualifier (as in "our $variable = <value>;") to avoid syntax errors if a new version of gitweb no longer uses a variable and therefore stops declaring it.

You can include other configuration file using read_config_file() subroutine. For example, one might want to put gitweb configuration related to access control for viewing repositories via Gitolite (one of Git repository management tools) in a separate file, e.g. in /etc/gitweb-gitolite.conf. To include it, put

```
read_config_file("/etc/gitweb-gitolite.conf");
```

somewhere in gitweb configuration file used, e.g. in per-installation gitweb configuration file. Note that read_config_file() checks itself that the file it reads exists, and does nothing if it is not found. It also handles errors in included file.

The default configuration with no configuration file at all may work perfectly well for some installations. Still, a configuration file is useful for customizing or tweaking the behavior of gitweb in many ways, and some optional features will not be present unless explicitly enabled using the configurable %features variable (see also "Configuring gitweb features" section below).

## CONFIGURATION VARIABLES
Some configuration variables have their default values (embedded in the CGI script) set during building gitweb — if that is the case, this fact is put in their description. See gitweb’s INSTALL file for instructions on building and installing gitweb.

### Location of repositories
The configuration variables described below control how gitweb finds Git repositories, and how repositories are displayed and accessed.

See also "Repositories" and later subsections in gitweb(1) manpage.

$projectroot

Absolute filesystem path which will be prepended to project path; the path to repository is $projectroot/$project. Set to $GITWEB_PROJECTROOT during installation. This variable has to be set correctly for gitweb to find repositories. For example, if $projectroot is set to "/srv/git" by putting the following in gitweb config file:

```
our $projectroot = "/srv/git";
```

then

```
http://git.example.com/gitweb.cgi?p=foo/bar.git
```

and its path_info based equivalent

```
http://git.example.com/gitweb.cgi/foo/bar.git
```

will map to the path /srv/git/foo/bar.git on the filesystem.

$projects_list

Name of a plain text file listing projects, or a name of directory to be scanned for projects. Project list files should list one project per line, with each line having the following format

```
<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
```

The default value of this variable is determined by the GITWEB_LIST makefile variable at installation time. If this variable is empty, gitweb will fall back to scanning the $projectroot directory for repositories.

$project_maxdepth

If $projects_list variable is unset, gitweb will recursively scan filesystem for Git repositories. The $project_maxdepth is used to limit traversing depth, relative to $projectroot (starting point); it means that directories which are further from $projectroot than $project_maxdepth will be skipped. It is purely performance optimization, originally intended for MacOS X, where recursive directory traversal is slow. Gitweb follows symbolic links, but it detects cycles, ignoring any duplicate files and directories.

The default value of this variable is determined by the build-time configuration variable GITWEB_PROJECT_MAXDEPTH, which defaults to 2007.

$export_ok

Show repository only if this file exists (in repository). Only effective if this variable evaluates to true. Can be set when building gitweb by setting GITWEB_EXPORT_OK. This path is relative to GIT_DIR. git-daemon[1] uses git-daemon-export-ok, unless started with --export-all. By default this variable is not set, which means that this feature is turned off.

$export_auth_hook

Function used to determine which repositories should be shown. This subroutine should take one parameter, the full path to a project, and if it returns true, that project will be included in the projects list and can be accessed through gitweb as long as it fulfills the other requirements described by $export_ok, $projects_list, and $projects_maxdepth. Example:

```
our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
```

though the above might be done by using $export_ok instead

```
our $export_ok = "git-daemon-export-ok";
```

If not set (default), it means that this feature is disabled.

See also more involved example in "Controlling access to Git repositories" subsection on gitweb(1) manpage.

$strict_export

Only allow viewing of repositories also shown on the overview page. This for example makes $export_ok file decide if repository is available and not only if it is shown. If $projects_list points to file with list of project, only those repositories listed would be available for gitweb. Can be set during building gitweb via GITWEB_STRICT_EXPORT. By default this variable is not set, which means that you can directly access those repositories that are hidden from projects list page (e.g. the are not listed in the $projects_list file).

### Finding files
The following configuration variables tell gitweb where to find files. The values of these variables are paths on the filesystem.

$GIT

Core git executable to use. By default set to $GIT_BINDIR/git, which in turn is by default set to $(bindir)/git. If you use Git installed from a binary package, you should usually set this to "/usr/bin/git". This can just be "git" if your web server has a sensible PATH; from security point of view it is better to use absolute path to git binary. If you have multiple Git versions installed it can be used to choose which one to use. Must be (correctly) set for gitweb to be able to work.

$mimetypes_file

File to use for (filename extension based) guessing of MIME types before trying /etc/mime.types. NOTE that this path, if relative, is taken as relative to the current Git repository, not to CGI script. If unset, only /etc/mime.types is used (if present on filesystem). If no mimetypes file is found, mimetype guessing based on extension of file is disabled. Unset by default.

$highlight_bin

Path to the highlight executable to use (it must be the one from http://andre-simon.de/zip/download.php due to assumptions about parameters and output). By default set to highlight; set it to full path to highlight executable if it is not installed on your web server’s PATH. Note that highlight feature must be set for gitweb to actually use syntax highlighting. NOTE: for a file to be highlighted, its syntax type must be detected and that syntax must be supported by "highlight". The default syntax detection is minimal, and there are many supported syntax types with no detection by default. There are three options for adding syntax detection. The first and second priority are %highlight_basename and %highlight_ext, which detect based on basename (the full filename, for example "Makefile") and extension (for example "sh"). The keys of these hashes are the basename and extension, respectively, and the value for a given key is the name of the syntax to be passed via --syntax <syntax> to "highlight". The last priority is the "highlight" configuration of Shebang regular expressions to detect the language based on the first line in the file, (for example, matching the line "#!/bin/bash"). See the highlight documentation and the default config at /etc/highlight/filetypes.conf for more details.

For example if repositories you are hosting use "phtml" extension for PHP files, and you want to have correct syntax-highlighting for those files, you can add the following to gitweb configuration:

```
our %highlight_ext;
$highlight_ext{'phtml'} = 'php';
```

### Links and their targets
The configuration variables described below configure some of gitweb links: their target and their look (text or image), and where to find page prerequisites (stylesheet, favicon, images, scripts). Usually they are left at their default values, with the possible exception of @stylesheets variable.

@stylesheets

List of URIs of stylesheets (relative to the base URI of a page). You might specify more than one stylesheet, for example to use "gitweb.css" as base with site specific modifications in a separate stylesheet to make it easier to upgrade gitweb. For example, you can add a site stylesheet by putting

```
push @stylesheets, "gitweb-site.css";
```

in the gitweb config file. Those values that are relative paths are relative to base URI of gitweb.

This list should contain the URI of gitweb’s standard stylesheet. The default URI of gitweb stylesheet can be set at build time using the GITWEB_CSS makefile variable. Its default value is static/gitweb.css (or static/gitweb.min.css if the CSSMIN variable is defined, i.e. if CSS minifier is used during build).

Note: there is also a legacy $stylesheet configuration variable, which was used by older gitweb. If $stylesheet variable is defined, only CSS stylesheet given by this variable is used by gitweb.

$logo

Points to the location where you put git-logo.png on your web server, or to be more the generic URI of logo, 72x27 size). This image is displayed in the top right corner of each gitweb page and used as a logo for the Atom feed. Relative to the base URI of gitweb (as a path). Can be adjusted when building gitweb using GITWEB_LOGO variable By default set to static/git-logo.png.

$favicon

Points to the location where you put git-favicon.png on your web server, or to be more the generic URI of favicon, which will be served as "image/png" type. Web browsers that support favicons (website icons) may display them in the browser’s URL bar and next to the site name in bookmarks. Relative to the base URI of gitweb. Can be adjusted at build time using GITWEB_FAVICON variable. By default set to static/git-favicon.png.

$javascript

Points to the location where you put gitweb.js on your web server, or to be more generic the URI of JavaScript code used by gitweb. Relative to the base URI of gitweb. Can be set at build time using the GITWEB_JS build-time configuration variable. The default value is either static/gitweb.js, or static/gitweb.min.js if the JSMIN build variable was defined, i.e. if JavaScript minifier was used at build time. Note that this single file is generated from multiple individual JavaScript "modules".

$home_link

Target of the home link on the top of all pages (the first part of view "breadcrumbs"). By default it is set to the absolute URI of a current page (to the value of $my_uri variable, or to "/" if $my_uri is undefined or is an empty string).

$home_link_str

Label for the "home link" at the top of all pages, leading to $home_link (usually the main gitweb page, which contains the projects list). It is used as the first component of gitweb’s "breadcrumb trail": <home-link> / <project> / <action>. Can be set at build time using the GITWEB_HOME_LINK_STR variable. By default it is set to "projects", as this link leads to the list of projects. Another popular choice is to set it to the name of site. Note that it is treated as raw HTML so it should not be set from untrusted sources.

@extra_breadcrumbs

Additional links to be added to the start of the breadcrumb trail before the home link, to pages that are logically "above" the gitweb projects list, such as the organization and department which host the gitweb server. Each element of the list is a reference to an array, in which element 0 is the link text (equivalent to $home_link_str) and element 1 is the target URL (equivalent to $home_link). For example, the following setting produces a breadcrumb trail like "home / dev / projects / ..." where "projects" is the home link.

```
    our @extra_breadcrumbs = (

      [ 'home' => 'https://www.example.org/' ],

      [ 'dev'  => 'https://dev.example.org/' ],

    );
```

$logo_url, $logo_label

URI and label (title) for the Git logo link (or your site logo, if you chose to use different logo image). By default, these both refer to Git homepage, https://git-scm.com; in the past, they pointed to Git documentation at https://www.kernel.org.

### Changing gitweb’s look
You can adjust how pages generated by gitweb look using the variables described below. You can change the site name, add common headers and footers for all pages, and add a description of this gitweb installation on its main page (which is the projects list page), etc.

$site_name

Name of your site or organization, to appear in page titles. Set it to something descriptive for clearer bookmarks etc. If this variable is not set or is, then gitweb uses the value of the SERVER_NAME CGI environment variable, setting site name to "$SERVER_NAME Git", or "Untitled Git" if this variable is not set (e.g. if running gitweb as standalone script). Can be set using the GITWEB_SITENAME at build time. Unset by default.

$site_html_head_string

HTML snippet to be included in the <head> section of each page. Can be set using GITWEB_SITE_HTML_HEAD_STRING at build time. No default value.

$site_header

Name of a file with HTML to be included at the top of each page. Relative to the directory containing the gitweb.cgi script. Can be set using GITWEB_SITE_HEADER at build time. No default value.

$site_footer

Name of a file with HTML to be included at the bottom of each page. Relative to the directory containing the gitweb.cgi script. Can be set using GITWEB_SITE_FOOTER at build time. No default value.

$home_text

Name of a HTML file which, if it exists, is included on the gitweb projects overview page ("projects_list" view). Relative to the directory containing the gitweb.cgi script. Default value can be adjusted during build time using GITWEB_HOMETEXT variable. By default set to indextext.html.

$projects_list_description_width

The width (in characters) of the "Description" column of the projects list. Longer descriptions will be truncated (trying to cut at word boundary); the full description is available in the title attribute (usually shown on mouseover). The default is 25, which might be too small if you use long project descriptions.

$default_projects_order

Default value of ordering of projects on projects list page, which means the ordering used if you don’t explicitly sort projects list (if there is no "o" CGI query parameter in the URL). Valid values are "none" (unsorted), "project" (projects are by project name, i.e. path to repository relative to $projectroot), "descr" (project description), "owner", and "age" (by date of most current commit). Default value is "project". Unknown value means unsorted.

### Changing gitweb’s behavior
These configuration variables control internal gitweb behavior.

$default_blob_plain_mimetype

Default mimetype for the blob_plain (raw) view, if mimetype checking doesn’t result in some other type; by default "text/plain". Gitweb guesses mimetype of a file to display based on extension of its filename, using $mimetypes_file (if set and file exists) and /etc/mime.types files (see mime.types(5) manpage; only filename extension rules are supported by gitweb).

$default_text_plain_charset

Default charset for text files. If this is not set, the web server configuration will be used. Unset by default.

$fallback_encoding

Gitweb assumes this charset when a line contains non-UTF-8 characters. The fallback decoding is used without error checking, so it can be even "utf-8". The value must be a valid encoding; see the Encoding::Supported(3pm) man page for a list. The default is "latin1", aka. "iso-8859-1".

@diff_opts

Rename detection options for git-diff and git-diff-tree. The default is ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or set it to () i.e. empty list if you don’t want to have renames detection. Note that rename and especially copy detection can be quite CPU-intensive. Note also that non Git tools can have problems with patches generated with options mentioned above, especially when they involve file copies ('-C') or criss-cross renames ('-B').

### Some optional features and policies
Most of features are configured via %feature hash; however some of extra gitweb features can be turned on and configured using variables described below. This list beside configuration variables that control how gitweb looks does contain variables configuring administrative side of gitweb (e.g. cross-site scripting prevention; admittedly this as side effect affects how "summary" pages look like, or load limiting).

@git_base_url_list

List of Git base URLs. These URLs are used to generate URLs describing from where to fetch a project, which are shown on project summary page. The full fetch URL is "$git_base_url/$project", for each element of this list. You can set up multiple base URLs (for example one for git:// protocol, and one for http:// protocol). Note that per repository configuration can be set in $GIT_DIR/cloneurl file, or as values of multi-value gitweb.url configuration variable in project config. Per-repository configuration takes precedence over value composed from @git_base_url_list elements and project name.

You can setup one single value (single entry/item in this list) at build time by setting the GITWEB_BASE_URL build-time configuration variable. By default it is set to (), i.e. an empty list. This means that gitweb would not try to create project URL (to fetch) from project name.

$projects_list_group_categories

Whether to enable the grouping of projects by category on the project list page. The category of a project is determined by the $GIT_DIR/category file or the gitweb.category variable in each repository’s configuration. Disabled by default (set to 0).

$project_list_default_category

Default category for projects for which none is specified. If this is set to the empty string, such projects will remain uncategorized and listed at the top, above categorized projects. Used only if project categories are enabled, which means if $projects_list_group_categories is true. By default set to "" (empty string).

$prevent_xss

If true, some gitweb features are disabled to prevent content in repositories from launching cross-site scripting (XSS) attacks. Set this to true if you don’t trust the content of your repositories. False by default (set to 0).

$maxload

Used to set the maximum load that we will still respond to gitweb queries. If the server load exceeds this value then gitweb will return "503 Service Unavailable" error. The server load is taken to be 0 if gitweb cannot determine its value. Currently it works only on Linux, where it uses /proc/loadavg; the load there is the number of active tasks on the system — processes that are actually running — averaged over the last minute. Set $maxload to undefined value (undef) to turn this feature off. The default value is 300.

$omit_age_column

If true, omit the column with date of the most current commit on the projects list page. It can save a bit of I/O and a fork per repository.

$omit_owner

If true prevents displaying information about repository owner.

$per_request_config

If this is set to code reference, it will be run once for each request. You can set parts of configuration that change per session this way. For example, one might use the following code in a gitweb configuration file

```
our $per_request_config = sub {

        $ENV{GL_USER} = $cgi->remote_user || "gitweb";
};
```

If $per_request_config is not a code reference, it is interpreted as boolean value. If it is true gitweb will process config files once per request, and if it is false gitweb will process config files only once, each time it is executed. True by default (set to 1).

NOTE: $my_url, $my_uri, and $base_url are overwritten with their default values before every request, so if you want to change them, be sure to set this variable to true or a code reference effecting the desired changes.

This variable matters only when using persistent web environments that serve multiple requests using single gitweb instance, like mod_perl, FastCGI or Plackup.

### Other variables
Usually you should not need to change (adjust) any of configuration variables described below; they should be automatically set by gitweb to correct value.

$version

Gitweb version, set automatically when creating gitweb.cgi from gitweb.perl. You might want to modify it if you are running modified gitweb, for example

```
our $version .= " with caching";
```

if you run modified version of gitweb with caching support. This variable is purely informational, used e.g. in the "generator" meta header in HTML header.

$my_url, $my_uri

Full URL and absolute URL of the gitweb script; in earlier versions of gitweb you might have need to set those variables, but now there should be no need to do it. See $per_request_config if you need to set them still.

$base_url

Base URL for relative URLs in pages generated by gitweb, (e.g. $logo, $favicon, @stylesheets if they are relative URLs), needed and used <base href="$base_url"> only for URLs with nonempty PATH_INFO. Usually gitweb sets its value correctly, and there is no need to set this variable, e.g. to $my_uri or "/". See $per_request_config if you need to override it anyway.

## CONFIGURING GITWEB FEATURES
Many gitweb features can be enabled (or disabled) and configured using the %feature hash. Names of gitweb features are keys of this hash.

Each %feature hash element is a hash reference and has the following structure:

```
"<feature-name>" => {

        "sub" => <feature-sub-(subroutine)>,

        "override" => <allow-override-(boolean)>,

        "default" => [ <options>... ]
},
```

Some features cannot be overridden per project. For those features the structure of appropriate %feature hash element has a simpler form:

```
"<feature-name>" => {

        "override" => 0,

        "default" => [ <options>... ]
},
```

As one can see it lacks the 'sub' element.

The meaning of each part of feature configuration is described below:

default

List (array reference) of feature parameters (if there are any), used also to toggle (enable or disable) given feature. Note that it is currently always an array reference, even if feature doesn’t accept any configuration parameters, and 'default' is used only to turn it on or off. In such case you turn feature on by setting this element to [1], and torn it off by setting it to [0]. See also the passage about the "blame" feature in the "Examples" section.

To disable features that accept parameters (are configurable), you need to set this element to empty list i.e. [].

override

If this field has a true value then the given feature is overridable, which means that it can be configured (or enabled/disabled) on a per-repository basis. Usually given "<feature>" is configurable via the gitweb.<feature> config variable in the per-repository Git configuration file.

Note that no feature is overridable by default.

sub

Internal detail of implementation. What is important is that if this field is not present then per-repository override for given feature is not supported. You wouldn’t need to ever change it in gitweb config file.

### Features in %feature
The gitweb features that are configurable via %feature hash are listed below. This should be a complete list, but ultimately the authoritative and complete list is in gitweb.cgi source code, with features described in the comments.

blame

Enable the "blame" and "blame_incremental" blob views, showing for each line the last commit that modified it; see git-blame(1). This can be very CPU-intensive and is therefore disabled by default. This feature can be configured on a per-repository basis via repository’s gitweb.blame configuration variable (boolean).

snapshot

Enable and configure the "snapshot" action, which allows user to download a compressed archive of any tree or commit, as produced by git-archive(1) and possibly additionally compressed. This can potentially generate high traffic if you have large project. The value of 'default' is a list of names of snapshot formats, defined in %known_snapshot_formats hash, that you wish to offer. Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz compressed tar archive) and "zip"; please consult gitweb sources for a definitive list. By default only "tgz" is offered.

This feature can be configured on a per-repository basis via repository’s gitweb.snapshot configuration variable, which contains a comma separated list of formats or "none" to disable snapshots. Unknown values are ignored.

grep

Enable grep search, which lists the files in currently selected tree (directory) containing the given string; see git-grep(1). This can be potentially CPU-intensive, of course. Enabled by default. This feature can be configured on a per-repository basis via repository’s gitweb.grep configuration variable (boolean).

pickaxe

Enable the so called pickaxe search, which will list the commits that introduced or removed a given string in a file. This can be practical and quite faster alternative to "blame" action, but it is still potentially CPU-intensive. Enabled by default. The pickaxe search is described in git-log(1) (the description of -S<string> option, which refers to pickaxe entry in gitdiffcore(7) for more details).

This feature can be configured on a per-repository basis by setting repository’s gitweb.pickaxe configuration variable (boolean).

show-sizes

Enable showing size of blobs (ordinary files) in a "tree" view, in a separate column, similar to what ls -l does; see description of -l option in git-ls-tree(1) manpage. This costs a bit of I/O. Enabled by default. This feature can be configured on a per-repository basis via repository’s gitweb.showSizes configuration variable (boolean).

patches

Enable and configure "patches" view, which displays list of commits in email (plain text) output format; see also git-format-patch(1). The value is the maximum number of patches in a patchset generated in "patches" view. Set the default field to a list containing single item of or to an empty list to disable patch view, or to a list containing a single negative number to remove any limit. Default value is 16. This feature can be configured on a per-repository basis via repository’s gitweb.patches configuration variable (integer).

avatar

Avatar support. When this feature is enabled, views such as "shortlog" or "commit" will display an avatar associated with the email of each committer and author. Currently available providers are "gravatar" and "picon". Only one provider at a time can be selected (default is one element list). If an unknown provider is specified, the feature is disabled. Note that some providers might require extra Perl packages to be installed; see gitweb/INSTALL for more details.

This feature can be configured on a per-repository basis via repository’s gitweb.avatar configuration variable.

See also %avatar_size with pixel sizes for icons and avatars ("default" is used for one-line like "log" and "shortlog", "double" is used for two-line like "commit", "commitdiff" or "tag"). If the default font sizes or lineheights are changed (e.g. via adding extra CSS stylesheet in @stylesheets), it may be appropriate to change these values.

email-privacy

Redact e-mail addresses from the generated HTML, etc. content. This obscures e-mail addresses retrieved from the author/committer and comment sections of the Git log. It is meant to hinder web crawlers that harvest and abuse addresses. Such crawlers may not respect robots.txt. Note that users and user tools also see the addresses as redacted. If Gitweb is not the final step in a workflow then subsequent steps may misbehave because of the redacted information they receive. Disabled by default.

highlight

Server-side syntax highlight support in "blob" view. It requires $highlight_bin program to be available (see the description of this variable in the "Configuration variables" section above), and therefore is disabled by default. This feature can be configured on a per-repository basis via repository’s gitweb.highlight configuration variable (boolean).

remote_heads

Enable displaying remote heads (remote-tracking branches) in the "heads" list. In most cases the list of remote-tracking branches is an unnecessary internal private detail, and this feature is therefore disabled by default. git-instaweb(1), which is usually used to browse local repositories, enables and uses this feature. This feature can be configured on a per-repository basis via repository’s gitweb.remote_heads configuration variable (boolean).

The remaining features cannot be overridden on a per project basis.

search

Enable text search, which will list the commits which match author, committer or commit text to a given string; see the description of --author, --committer and --grep options in git-log(1) manpage. Enabled by default. Project specific override is not supported.

forks

If this feature is enabled, gitweb considers projects in subdirectories of project root (basename) to be forks of existing projects. For each project $projname.git, projects in the $projname/ directory and its subdirectories will not be shown in the main projects list. Instead, a '+' mark is shown next to $projname, which links to a "forks" view that lists all the forks (all projects in $projname/ subdirectory). Additionally a "forks" view for a project is linked from project summary page. If the project list is taken from a file ($projects_list points to a file), forks are only recognized if they are listed after the main project in that file.

Project specific override is not supported.

actions

Insert custom links to the action bar of all project pages. This allows you to link to third-party scripts integrating into gitweb. The "default" value consists of a list of triplets in the form ‘("<label>", "<link>", "<position>")` where "position" is the label after which to insert the link, "link" is a format string where %n expands to the project name, %f to the project path within the filesystem (i.e. "$projectroot/$project"), %h to the current hash ('h’ gitweb parameter) and ‘%b` to the current hash base ('hb’ gitweb parameter); ‘%%` expands to '%’.

For example, at the time this page was written, the https://repo.or.cz Git hosting site set it to the following to enable graphical log (using the third party tool git-browser):

```
$feature{'actions'}{'default'} =

        [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
```

This adds a link titled "graphiclog" after the "summary" link, leading to git-browser script, passing r=<project> as a query parameter.

Project specific override is not supported.

timed

Enable displaying how much time and how many Git commands it took to generate and display each page in the page footer (at the bottom of page). For example the footer might contain: "This page took 6.53325 seconds and 13 Git commands to generate." Disabled by default. Project specific override is not supported.

javascript-timezone

Enable and configure the ability to change a common time zone for dates in gitweb output via JavaScript. Dates in gitweb output include authordate and committerdate in "commit", "commitdiff" and "log" views, and taggerdate in "tag" view. Enabled by default. The value is a list of three values: a default time zone (for if the client hasn’t selected some other time zone and saved it in a cookie), a name of cookie where to store selected time zone, and a CSS class used to mark up dates for manipulation. If you want to turn this feature off, set "default" to empty list: [].

Typical gitweb config files will only change starting (default) time zone, and leave other elements at their default values:

```
$feature{'javascript-timezone'}{'default'}[0] = "utc";
```

The example configuration presented here is guaranteed to be backwards and forward compatible.

Time zone values can be "local" (for local time zone that browser uses), "utc" (what gitweb uses when JavaScript or this feature is disabled), or numerical time zones in the form of "+/-HHMM", such as "+0200".

Project specific override is not supported.

extra-branch-refs

List of additional directories under "refs" which are going to be used as branch refs. For example if you have a gerrit setup where all branches under refs/heads/ are official, push-after-review ones and branches under refs/sandbox/, refs/wip and refs/other are user ones where permissions are much wider, then you might want to set this variable as follows:

```
$feature{'extra-branch-refs'}{'default'} =

        ['sandbox', 'wip', 'other'];
```

This feature can be configured on per-repository basis after setting $feature{extra-branch-refs}{override} to true, via repository’s gitweb.extraBranchRefs configuration variable, which contains a space separated list of refs. An example:

```
[gitweb]

        extraBranchRefs = sandbox wip other
```

The gitweb.extraBranchRefs is actually a multi-valued configuration variable, so following example is also correct and the result is the same as of the snippet above:

```
[gitweb]

        extraBranchRefs = sandbox

        extraBranchRefs = wip other
```

It is an error to specify a ref that does not pass "git check-ref-format" scrutiny. Duplicated values are filtered.

## EXAMPLES
To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and "zip" snapshots), while allowing individual projects to turn them off, put the following in your GITWEB_CONFIG file:

```
$feature{'blame'}{'default'} = [1];
$feature{'blame'}{'override'} = 1;
$feature{'pickaxe'}{'default'} = [1];
$feature{'pickaxe'}{'override'} = 1;
$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
$feature{'snapshot'}{'override'} = 1;
```

If you allow overriding for the snapshot feature, you can specify which snapshot formats are globally disabled. You can also add any command-line options you want (such as setting the compression level). For instance, you can disable Zip compressed snapshots and set gzip(1) to run at level 6 by adding the following lines to your gitweb configuration file:

```
$known_snapshot_formats{'zip'}{'disabled'} = 1;
$known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
```

## BUGS
Debugging would be easier if the fallback configuration file (/etc/gitweb.conf) and environment variable to override its location (GITWEB_CONFIG_SYSTEM) had names reflecting their "fallback" role. The current names are kept to avoid breaking working setups.

## ENVIRONMENT
The location of per-instance and system-wide configuration files can be overridden using the following environment variables:

GITWEB_CONFIG

Sets location of per-instance configuration file.

GITWEB_CONFIG_SYSTEM

Sets location of fallback system-wide configuration file. This file is read only if per-instance one does not exist.

GITWEB_CONFIG_COMMON

Sets location of common system-wide configuration file.

## FILES
gitweb_config.perl

This is default name of per-instance configuration file. The format of this file is described above.

/etc/gitweb.conf

This is default name of fallback system-wide configuration file. This file is used only if per-instance configuration variable is not found.

/etc/gitweb-common.conf

This is default name of common system-wide configuration file.

## SEE ALSO
gitweb(1), git-instaweb(1)

gitweb/README, gitweb/INSTALL

## GIT
Part of the git(1) suite


gtags.conf

package: global

title: gtags.conf(5)

summary: configuration data for GNU Global

text:
# gtags.conf(5)

## NAME
gtags.conf - configuration data for GNU Global

## SYNOPSIS
´gtags.conf´

´~/.globalrc´

## DESCRIPTION
´gtags.conf´ has configuration data for global(1), gozilla(1), gtags(1) and htags(1). They look for the following files in this order, and read from the first one that exists and is readable.

(1) --gtagsconf file

(2) $GTAGSCONF

(3) [project root]/gtags.conf

(4) [project root]/[objdir]/gtags.conf

(5) $HOME/.globalrc

(6) /etc/gtags.conf

(7) [sysconfdir]/gtags.conf

[sysconfdir] is ´/usr/local/etc´ by default; you can change it by the --sysconfdir option of the configure script. [objdir] is ´obj´ by default; you can change it by GTAGSOBJDIR or MAKEOBJDIR.

Its syntax is similar to termcap(5) except for some extensions described later. A file includes one or more records. You should select a record using a label. Default label is ´default´. If GTAGSLABEL is set, its value is used. Please be aware the meaning of ´default´ is different from that of termcap(5).

Lines starting with ´#´ are ignored. A record consists of one or more fields separated by ´:´ and ends with a newline. The first field must have a label name. Each field of the rest has a variable definition. There are three types in those variables.

Boolean: This type has no value; existence of variable means true else false.

Number: This type has a number value after ´#´.

String: This type has a string value after ´=´.

Most variables are relevant to string type.

If data includes ´:´ or newline, you need to quote it by ´\'. An empty field is permitted, but it doesn't make sense.

When there is more than one definition, the previous one is adopted. Exceptionally, all values of skip, langmap and gtags_parser are adopted and connected respectively.

## Variable substitution
Variable substitution similar to sh(1) is available. You can refer to any string variable using ´$´ prefix. For example, the following b has a value ´XYZ´.

```
:a=Y:b=X${a}Z:
```

## Including another record
Tc is a special variable; it reads in definitions in another record. It is similar to the tc of termcap(5). Its syntax is as follows:

tc=label[@file]

If only a label is given, tc is read from a record specified by the label in the same file. If @file is also given, tc is read from a record specified by the label in the specified file. File should be an absolute path, and should not include variables. Different from termcap(5), you can use tc anytime anywhere.

## CONFIGURATION
About variables for each command, please see each manual.

You can use the following environment variables as a string variable. If these variables are set then environment variables of the same name are set before command execution.

GREP_COLOR

GREP_COLORS

GTAGSBLANKENCODE

GTAGSCACHE

GTAGSFORCECPP

GTAGSGLOBAL

GTAGSGTAGS

GTAGSLIBPATH

GTAGSLOGGING

GTAGSTHROUGH

GTAGS_OPTIONS

HTAGS_OPTIONS

MAKEOBJDIR

MAKEOBJDIRPREFIX

TMPDIR

The following variables are also available as a string variable. By default, each of them has a directory path given by the configure script.

bindir

datadir

libdir

localstatedir

sysconfdir

## ENVIRONMENT
The following environment variables affect the execution of the commands.

GTAGSCONF

If this variable is set, the value is used as a configuration file.

GTAGSLABEL

If this variable is set, the value is used as a label of the configuration file. The default is default.

## SEE ALSO
global(1), gozilla(1), gtags(1), htags(1).

GNU Global source code tag system

(http://www.gnu.org/software/global/).

## HISTORY
The gtags.conf file appeared in Global-3.0 (1998).