gitprotocol-http

title: gitprotocol-http(5)

summary: Git HTTP\-based protocols

text:
# gitprotocol-http(5)

## NAME
gitprotocol-http - Git HTTP-based protocols

## SYNOPSIS

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

## DESCRIPTION
Git supports two HTTP based transfer protocols. A "dumb" protocol which requires only a standard HTTP server on the server end of the connection, and a "smart" protocol which requires a Git aware CGI (or server module). This document describes both protocols.

As a design feature smart clients can automatically upgrade "dumb" protocol URLs to smart URLs. This permits all users to have the same published URL, and the peers automatically select the most efficient transport available to them.

## URL FORMAT
URLs for Git repositories accessed by HTTP use the standard HTTP URL syntax documented by RFC 1738, so they are of the form:

```
http://<host>:<port>/<path>?<searchpart>
```

Within this documentation the placeholder $GIT_URL will stand for the http:// repository URL entered by the end-user.

Servers SHOULD handle all requests to locations matching $GIT_URL, as both the "smart" and "dumb" HTTP protocols used by Git operate by appending additional path components onto the end of the user supplied $GIT_URL string.

An example of a dumb client requesting a loose object:

```
$GIT_URL:     http://example.com:8080/git/repo.git
URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
```

An example of a smart request to a catch-all gateway:

```
$GIT_URL:     http://example.com/daemon.cgi?svc=git&q=
URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack
```

An example of a request to a submodule:

```
$GIT_URL:     http://example.com/git/repo.git/path/submodule.git
URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs
```

Clients MUST strip a trailing /, if present, from the user supplied $GIT_URL string to prevent empty path tokens (//) from appearing in any URL sent to a server. Compatible clients MUST expand $GIT_URL/info/refs as foo/info/refs and not foo//info/refs.

## AUTHENTICATION
Standard HTTP authentication is used if authentication is required to access a repository, and MAY be configured and enforced by the HTTP server software.

Because Git repositories are accessed by standard path components server administrators MAY use directory based permissions within their HTTP server to control repository access.

Clients SHOULD support Basic authentication as described by RFC 2617. Servers SHOULD support Basic authentication by relying upon the HTTP server placed in front of the Git server software.

Servers SHOULD NOT require HTTP cookies for the purposes of authentication or access control.

Clients and servers MAY support other common forms of HTTP based authentication, such as Digest authentication.

## SSL
Clients and servers SHOULD support SSL, particularly to protect passwords when relying on Basic HTTP authentication.

## SESSION STATE
The Git over HTTP protocol (much like HTTP itself) is stateless from the perspective of the HTTP server side. All state MUST be retained and managed by the client process. This permits simple round-robin load-balancing on the server side, without needing to worry about state management.

Clients MUST NOT require state management on the server side in order to function correctly.

Servers MUST NOT require HTTP cookies in order to function correctly. Clients MAY store and forward HTTP cookies during request processing as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any cookies sent by a client.

## GENERAL REQUEST PROCESSING
Except where noted, all standard HTTP behavior SHOULD be assumed by both client and server. This includes (but is not necessarily limited to):

If there is no repository at $GIT_URL, or the resource pointed to by a location matching $GIT_URL does not exist, the server MUST NOT respond with 200 OK response. A server SHOULD respond with 404 Not Found, 410 Gone, or any other suitable HTTP status code which does not imply the resource exists as requested.

If there is a repository at $GIT_URL, but access is not currently permitted, the server MUST respond with the 403 Forbidden HTTP status code.

Servers SHOULD support both HTTP 1.0 and HTTP 1.1. Servers SHOULD support chunked encoding for both request and response bodies.

Clients SHOULD support both HTTP 1.0 and HTTP 1.1. Clients SHOULD support chunked encoding for both request and response bodies.

Servers MAY return ETag and/or Last-Modified headers.

Clients MAY revalidate cached entities by including If-Modified-Since and/or If-None-Match request headers.

Servers MAY return 304 Not Modified if the relevant headers appear in the request and the entity has not changed. Clients MUST treat 304 Not Modified identical to 200 OK by reusing the cached entity.

Clients MAY reuse a cached entity without revalidation if the Cache-Control and/or Expires header permits caching. Clients and servers MUST follow RFC 2616 for cache controls.

## DISCOVERING REFERENCES
All HTTP clients MUST begin either a fetch or a push exchange by discovering the references available on the remote repository.

### Dumb Clients
HTTP clients that only support the "dumb" protocol MUST discover references by making a request for the special info/refs file of the repository.

Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs, without any search/query parameters.

```
C: GET $GIT_URL/info/refs HTTP/1.0
```

```
S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
```

The Content-Type of the returned info/refs entity SHOULD be text/plain; charset=utf-8, but MAY be any content type. Clients MUST NOT attempt to validate the returned Content-Type. Dumb servers MUST NOT return a return type starting with application/x-git-.

Cache-Control headers MAY be returned to disable caching of the returned entity.

When examining the response clients SHOULD only examine the HTTP status code. Valid responses are 200 OK, or 304 Not Modified.

The returned content is a UNIX formatted text file describing each ref and its known value. The file SHOULD be sorted by name according to the C locale ordering. The file SHOULD NOT include the default ref named HEAD.

```
info_refs   =  *( ref_record )
ref_record  =  any_ref / peeled_ref
```

```
any_ref     =  obj-id HTAB refname LF
peeled_ref  =  obj-id HTAB refname LF

               obj-id HTAB refname "^{}" LF
```

### Smart Clients
HTTP clients that support the "smart" protocol (or both the "smart" and "dumb" protocols) MUST discover references by making a parameterized request for the info/refs file of the repository.

The request MUST contain exactly one query parameter, service=$servicename, where $servicename MUST be the service name the client wishes to contact to complete the operation. The request MUST NOT contain additional query parameters.

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

dumb server reply:

```
S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
```

smart server reply:

```
S: 200 OK
S: Content-Type: application/x-git-upload-pack-advertisement
S: Cache-Control: no-cache
S:
S: 001e# service=git-upload-pack\n
S: 0000
S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
S: 0000
```

The client may send Extra Parameters (see gitprotocol-pack(5)) as a colon-separated string in the Git-Protocol HTTP header.

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

Dumb Server Response

Dumb servers MUST respond with the dumb server reply format.

See the prior section under dumb clients for a more detailed description of the dumb server response.

Smart Server Response

If the server does not recognize the requested service name, or the requested service name has been disabled by the server administrator, the server MUST respond with the 403 Forbidden HTTP status code.

Otherwise, smart servers MUST respond with the smart server reply format for the requested service name.

Cache-Control headers SHOULD be used to disable caching of the returned entity.

The Content-Type MUST be application/x-$servicename-advertisement. Clients SHOULD fall back to the dumb protocol if another content type is returned. When falling back to the dumb protocol clients SHOULD NOT make an additional request to $GIT_URL/info/refs, but instead SHOULD use the response already in hand. Clients MUST NOT continue if they do not support the dumb protocol.

Clients MUST validate the status code is either 200 OK or 304 Not Modified.

Clients MUST validate the first five bytes of the response entity matches the regex ^[0-9a-f]{4}#. If this test fails, clients MUST NOT continue.

Clients MUST parse the entire response as a sequence of pkt-line records.

Clients MUST verify the first pkt-line is # service=$servicename. Servers MUST set $servicename to be the request parameter value. Servers SHOULD include an LF at the end of this line. Clients MUST ignore an LF at the end of the line.

Servers MUST terminate the response with the magic 0000 end pkt-line marker.

The returned response is a pkt-line stream describing each ref and its known value. The stream SHOULD be sorted by name according to the C locale ordering. The stream SHOULD include the default ref named HEAD as the first ref. The stream MUST include capability declarations behind a NUL on the first ref.

The returned response contains "version 1" if "version=1" was sent as an Extra Parameter.

```
smart_reply     =  PKT-LINE("# service=$servicename" LF)

                   "0000"

                   *1("version 1")

                   ref_list

                   "0000"
ref_list        =  empty_list / non_empty_list
```

```
empty_list      =  PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
```

```
non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)

                   *ref_record
```

```
cap-list        =  capability *(SP capability)
capability      =  1*(LC_ALPHA / DIGIT / "-" / "_")
LC_ALPHA        =  %x61-7A
```

```
ref_record      =  any_ref / peeled_ref
any_ref         =  PKT-LINE(obj-id SP name LF)
peeled_ref      =  PKT-LINE(obj-id SP name LF)

                   PKT-LINE(obj-id SP name "^{}" LF
```

## SMART SERVICE GIT-UPLOAD-PACK
This service reads from the repository pointed to by $GIT_URL.

Clients MUST first perform ref discovery with $GIT_URL/info/refs?service=git-upload-pack.

```
C: POST $GIT_URL/git-upload-pack HTTP/1.0
C: Content-Type: application/x-git-upload-pack-request
C:
C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
C: 0000
```

```
S: 200 OK
S: Content-Type: application/x-git-upload-pack-result
S: Cache-Control: no-cache
S:
S: ....ACK %s, continue
S: ....NAK
```

Clients MUST NOT reuse or revalidate a cached response. Servers MUST include sufficient Cache-Control headers to prevent caching of the response.

Servers SHOULD support all capabilities defined here.

Clients MUST send at least one "want" command in the request body. Clients MUST NOT reference an id in a "want" command which did not appear in the response obtained through ref discovery unless the server advertises capability allow-tip-sha1-in-want or allow-reachable-sha1-in-want.

```
compute_request   =  want_list

                     have_list

                     request_end
request_end       =  "0000" / "done"
```

```
want_list         =  PKT-LINE(want SP cap_list LF)

                     *(want_pkt)
want_pkt          =  PKT-LINE(want LF)
want              =  "want" SP id
cap_list          =  capability *(SP capability)
```

```
have_list         =  *PKT-LINE("have" SP id LF)
```

TODO: Document this further.

### The Negotiation Algorithm
The computation to select the minimal pack proceeds as follows (C = client, S = server):

init step:

C: Use ref discovery to obtain the advertised refs.

C: Place any object seen into set advertised.

C: Build an empty set, common, to hold the objects that are later determined to be on both ends.

C: Build a set, want, of the objects from advertised that the client wants to fetch, based on what it saw during ref discovery.

C: Start a queue, c_pending, ordered by commit time (popping newest first). Add all client refs. When a commit is popped from the queue its parents SHOULD be automatically inserted back. Commits MUST only enter the queue once.

one compute step:

C: Send one $GIT_URL/git-upload-pack request:

```
C: 0032want <want-#1>...............................
C: 0032want <want-#2>...............................
....
C: 0032have <common-#1>.............................
C: 0032have <common-#2>.............................
....
C: 0032have <have-#1>...............................
C: 0032have <have-#2>...............................
....
C: 0000
```

The stream is organized into "commands", with each command appearing by itself in a pkt-line. Within a command line, the text leading up to the first space is the command name, and the remainder of the line to the first LF is the value. Command lines are terminated with an LF as the last byte of the pkt-line value.

Commands MUST appear in the following order, if they appear at all in the request stream:

•"want"

•"have"

The stream is terminated by a pkt-line flush (0000).

A single "want" or "have" command MUST have one hex formatted object name as its value. Multiple object names MUST be sent by sending multiple commands. Object names MUST be given using the object format negotiated through the object-format capability (default SHA-1).

The have list is created by popping the first 32 commits from c_pending. Fewer can be supplied if c_pending empties.

If the client has sent 256 "have" commits and has not yet received one of those back from s_common, or the client has emptied c_pending it SHOULD include a "done" command to let the server know it won’t proceed:

```
C: 0009done
```

S: Parse the git-upload-pack request:

Verify all objects in want are directly reachable from refs.

The server MAY walk backwards through history or through the reflog to permit slightly stale requests.

If no "want" objects are received, send an error: TODO: Define error if no "want" lines are requested.

If any "want" object is not reachable, send an error: TODO: Define error if an invalid "want" is requested.

Create an empty list, s_common.

If "have" was sent:

Loop through the objects in the order supplied by the client.

For each object, if the server has the object reachable from a ref, add it to s_common. If a commit is added to s_common, do not add any ancestors, even if they also appear in have.

S: Send the git-upload-pack response:

If the server has found a closed set of objects to pack or the request ends with "done", it replies with the pack. TODO: Document the pack based response

```
S: PACK...
```

The returned stream is the side-band-64k protocol supported by the git-upload-pack service, and the pack is embedded into stream 1. Progress messages from the server side MAY appear in stream 2.

Here a "closed set of objects" is defined to have at least one path from every "want" to at least one "common" object.

If the server needs more information, it replies with a status continue response: TODO: Document the non-pack response

C: Parse the upload-pack response: TODO: Document parsing response

Do another compute step.

## SMART SERVICE GIT-RECEIVE-PACK
This service reads from the repository pointed to by $GIT_URL.

Clients MUST first perform ref discovery with $GIT_URL/info/refs?service=git-receive-pack.

```
C: POST $GIT_URL/git-receive-pack HTTP/1.0
C: Content-Type: application/x-git-receive-pack-request
C:
C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
C: 0000
C: PACK....
```

```
S: 200 OK
S: Content-Type: application/x-git-receive-pack-result
S: Cache-Control: no-cache
S:
S: ....
```

Clients MUST NOT reuse or revalidate a cached response. Servers MUST include sufficient Cache-Control headers to prevent caching of the response.

Servers SHOULD support all capabilities defined here.

Clients MUST send at least one command in the request body. Within the command portion of the request body clients SHOULD send the id obtained through ref discovery as old_id.

```
update_request  =  command_list

                   "PACK" <binary-data>
```

```
command_list    =  PKT-LINE(command NUL cap_list LF)

                   *(command_pkt)
command_pkt     =  PKT-LINE(command LF)
cap_list        =  *(SP capability) SP
```

```
command         =  create / delete / update
create          =  zero-id SP new_id SP name
delete          =  old_id SP zero-id SP name
update          =  old_id SP new_id SP name
```

TODO: Document this further.

## REFERENCES
RFC 1738: Uniform Resource Locators (URL)[1] RFC 2616: Hypertext Transfer Protocol — HTTP/1.1[2]

## SEE ALSO
gitprotocol-pack(5) gitprotocol-capabilities(5)

## GIT
Part of the git(1) suite

## NOTES
1.

RFC 1738: Uniform Resource Locators (URL)

https://www.ietf.org/rfc/rfc1738.txt

2.

RFC 2616: Hypertext Transfer Protocol — HTTP/1.1

https://www.ietf.org/rfc/rfc2616.txt


gitprotocol-pack

package: git-core

title: gitprotocol-pack(5)

summary: How packs are transferred over\-the\-wire

text:
# gitprotocol-pack(5)

## NAME
gitprotocol-pack - How packs are transferred over-the-wire

## SYNOPSIS

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

## DESCRIPTION
Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a server to a client. The three transports (ssh, git, file) use the same protocol to transfer data. http is documented in gitprotocol-http(5).

The processes invoked in the canonical Git implementation are upload-pack on the server side and fetch-pack on the client side for fetching data; then receive-pack on the server and send-pack on the client for pushing data. The protocol functions to have a server tell a client what is currently on the server, then for the two to negotiate the smallest amount of data to send in order to fully update one or the other.

## PKT-LINE FORMAT
The descriptions below build on the pkt-line format described in gitprotocol-common(5). When the grammar indicates PKT-LINE(...), unless otherwise noted the usual pkt-line LF rules apply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not present.

An error packet is a special pkt-line that contains an error string.

```
  error-line     =  PKT-LINE("ERR" SP explanation-text)
```

Throughout the protocol, where PKT-LINE(...) is expected, an error packet MAY be sent. Once this packet is sent by a client or a server, the data transfer process defined in this protocol is terminated.

## TRANSPORTS
There are three transports over which the packfile protocol is initiated. The Git transport is a simple, unauthenticated server that takes the command (almost always upload-pack, though Git servers can be configured to be globally writable, in which receive- pack initiation is also allowed) with which the client wishes to communicate and executes it and connects it to the requesting process.

In the SSH transport, the client just runs the upload-pack or receive-pack process on the server over the SSH protocol and then communicates with that invoked process over the SSH connection.

The file:// transport runs the upload-pack or receive-pack process locally and communicates with it over a pipe.

## EXTRA PARAMETERS
The protocol provides a mechanism in which clients can send additional information in its first message to the server. These are called "Extra Parameters", and are supported by the Git, SSH, and HTTP protocols.

Each Extra Parameter takes the form of <key>=<value> or <key>.

Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is "version" with a value of 1 or 2. See gitprotocol-v2(5) for more information on protocol version 2.

## GIT TRANSPORT
The Git transport starts off by sending the command and repository on the wire using the pkt-line format, followed by a NUL byte and a hostname parameter, terminated by a NUL byte.

```
0033git-upload-pack /project.git\0host=myserver.com\0
```

The transport may send Extra Parameters by adding an additional NUL byte, and then adding one or more NUL-terminated strings:

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

```
git-proto-request = request-command SP pathname NUL

                    [ host-parameter NUL ] [ NUL extra-parameters ]
request-command   = "git-upload-pack" / "git-receive-pack" /

                    "git-upload-archive"   ; case sensitive
pathname          = *( %x01-ff ) ; exclude NUL
host-parameter    = "host=" hostname [ ":" port ]
extra-parameters  = 1*extra-parameter
extra-parameter   = 1*( %x01-ff ) NUL
```

host-parameter is used for the git-daemon name based virtual hosting. See --interpolated-path option to git daemon, with the %H/%CH format characters.

Basically what the Git client is doing to connect to an upload-pack process on the server side over the Git protocol is this:

```
$ echo -e -n \

  "003agit-upload-pack /schacon/gitbook.git\0host=example.com\0" |

  nc -v example.com 9418
```

## SSH TRANSPORT
Initiating the upload-pack or receive-pack processes over SSH is executing the binary on the server via SSH remote execution. It is basically equivalent to running this:

```
$ ssh git.example.com "git-upload-pack '/project.git'"
```

For a server to support Git pushing and pulling for a given user over SSH, that user needs to be able to execute one or both of those commands via the SSH shell that they are provided on login. On some systems, that shell access is limited to only being able to run those two commands, or even just one of them.

In an ssh:// format URI, it’s absolute in the URI, so the / after the host name (or port number) is sent as an argument, which is then read by the remote git-upload-pack exactly as is, so it’s effectively an absolute path in the remote filesystem.

```
   git clone ssh://user@example.com/project.git

                |

                v
ssh user@example.com "git-upload-pack '/project.git'"
```

In a "user@host:path" format URI, it’s relative to the user’s home directory, because the Git client will run:

```
   git clone user@example.com:project.git

                  |

                  v
ssh user@example.com "git-upload-pack 'project.git'"
```

The exception is if a ~ is used, in which case we execute it without the leading /.

```
   ssh://user@example.com/~alice/project.git,

                  |

                  v
ssh user@example.com "git-upload-pack '~alice/project.git'"
```

Depending on the value of the protocol.version configuration variable, Git may attempt to send Extra Parameters as a colon-separated string in the GIT_PROTOCOL environment variable. This is done only if the ssh.variant configuration variable indicates that the ssh command supports passing environment variables as an argument.

A few things to remember here:

•The "command name" is spelled with dash (e.g. git-upload-pack), but this can be overridden by the client;

•The repository path is always quoted with single quotes.

## FETCHING DATA FROM A SERVER
When one Git repository wants to get data that a second repository has, the first can fetch from the second. This operation determines what data the server has that the client does not then streams that data down to the client in packfile format.

## REFERENCE DISCOVERY
When the client initially connects the server will immediately respond with a version number (if "version=1" is sent as an Extra Parameter), and a listing of each reference it has (all branches and tags) along with the object name that each reference currently points to.

```
$ echo -e -n "0045git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" |

   nc -v example.com 9418
000eversion 1
00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack

             side-band side-band-64k ofs-delta shallow no-progress include-tag
00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0
003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
0000
```

The returned response is a pkt-line stream describing each ref and its current value. The stream MUST be sorted by name according to the C locale ordering.

If HEAD is a valid ref, HEAD MUST appear as the first advertised ref. If HEAD is not a valid ref, HEAD MUST NOT appear in the advertisement list at all, but other refs may still appear.

The stream MUST include capability declarations behind a NUL on the first ref. The peeled value of a ref (that is "ref^{}") MUST be immediately after the ref itself, if presented. A conforming server MUST peel the ref if it’s an annotated tag.

```
  advertised-refs  =  *1("version 1")

                      (no-refs / list-of-refs)

                      *shallow

                      flush-pkt

  no-refs          =  PKT-LINE(zero-id SP "capabilities^{}"

                      NUL capability-list)

  list-of-refs     =  first-ref *other-ref

  first-ref        =  PKT-LINE(obj-id SP refname

                      NUL capability-list)

  other-ref        =  PKT-LINE(other-tip / other-peeled)

  other-tip        =  obj-id SP refname

  other-peeled     =  obj-id SP refname "^{}"

  shallow          =  PKT-LINE("shallow" SP obj-id)

  capability-list  =  capability *(SP capability)

  capability       =  1*(LC_ALPHA / DIGIT / "-" / "_")

  LC_ALPHA         =  %x61-7A
```

Server and client MUST use lowercase for obj-id, both MUST treat obj-id as case-insensitive.

See protocol-capabilities.txt for a list of allowed server capabilities and descriptions.

## PACKFILE NEGOTIATION
After reference and capabilities discovery, the client can decide to terminate the connection by sending a flush-pkt, telling the server it can now gracefully terminate, and disconnect, when it does not need any pack data. This can happen with the ls-remote command, and also can happen when the client already is up to date.

Otherwise, it enters the negotiation phase, where the client and server determine what the minimal packfile necessary for transport is, by telling the server what objects it wants, its shallow objects (if any), and the maximum commit depth it wants (if any). The client will also send a list of the capabilities it wants to be in effect, out of what the server said it could do with the first want line.

```
  upload-request    =  want-list

                       *shallow-line

                       *1depth-request

                       [filter-request]

                       flush-pkt

  want-list         =  first-want

                       *additional-want

  shallow-line      =  PKT-LINE("shallow" SP obj-id)

  depth-request     =  PKT-LINE("deepen" SP depth) /

                       PKT-LINE("deepen-since" SP timestamp) /

                       PKT-LINE("deepen-not" SP ref)

  first-want        =  PKT-LINE("want" SP obj-id SP capability-list)

  additional-want   =  PKT-LINE("want" SP obj-id)

  depth             =  1*DIGIT

  filter-request    =  PKT-LINE("filter" SP filter-spec)
```

Clients MUST send all the obj-ids it wants from the reference discovery phase as want lines. Clients MUST send at least one want command in the request body. Clients MUST NOT mention an obj-id in a want command which did not appear in the response obtained through ref discovery.

The client MUST write all obj-ids which it only has shallow copies of (meaning that it does not have the parents of a commit) as shallow lines so that the server is aware of the limitations of the client’s history.

The client now sends the maximum commit history depth it wants for this transaction, which is the number of commits it wants from the tip of the history, if any, as a deepen line. A depth of 0 is the same as not making a depth request. The client does not want to receive any commits beyond this depth, nor does it want objects needed only to complete those commits. Commits whose parents are not received as a result are defined as shallow and marked as such in the server. This information is sent back to the client in the next step.

The client can optionally request that pack-objects omit various objects from the packfile using one of several filtering techniques. These are intended for use with partial clone and partial fetch operations. An object that does not meet a filter-spec value is omitted unless explicitly requested in a want line. See rev-list for possible filter-spec values.

Once all the want’s and 'shallow’s (and optional 'deepen) are transferred, clients MUST send a flush-pkt, to tell the server side that it is done sending the list.

Otherwise, if the client sent a positive depth request, the server will determine which commits will and will not be shallow and send this information to the client. If the client did not request a positive depth, this step is skipped.

```
  shallow-update   =  *shallow-line

                      *unshallow-line

                      flush-pkt

  shallow-line     =  PKT-LINE("shallow" SP obj-id)

  unshallow-line   =  PKT-LINE("unshallow" SP obj-id)
```

If the client has requested a positive depth, the server will compute the set of commits which are no deeper than the desired depth. The set of commits starts at the client’s wants.

The server writes shallow lines for each commit whose parents will not be sent as a result. The server writes an unshallow line for each commit which the client has indicated is shallow, but is no longer shallow at the currently requested depth (that is, its parents will now be sent). The server MUST NOT mark as unshallow anything which the client has not indicated was shallow.

Now the client will send a list of the obj-ids it has using have lines, so the server can make a packfile that only contains the objects that the client needs. In multi_ack mode, the canonical implementation will send up to 32 of these at a time, then will send a flush-pkt. The canonical implementation will skip ahead and send the next 32 immediately, so that there is always a block of 32 "in-flight on the wire" at a time.

```
  upload-haves      =  have-list

                       compute-end

  have-list         =  *have-line

  have-line         =  PKT-LINE("have" SP obj-id)

  compute-end       =  flush-pkt / PKT-LINE("done")
```

If the server reads have lines, it then will respond by ACKing any of the obj-ids the client said it had that the server also has. The server will ACK obj-ids differently depending on which ack mode is chosen by the client.

In multi_ack mode:

•the server will respond with ACK obj-id continue for any common commits.

•once the server has found an acceptable common base commit and is ready to make a packfile, it will blindly ACK all have obj-ids back to the client.

•the server will then send a NAK and then wait for another response from the client - either a done or another list of have lines.

In multi_ack_detailed mode:

•the server will differentiate the ACKs where it is signaling that it is ready to send data with ACK obj-id ready lines, and signals the identified common commits with ACK obj-id common lines.

Without either multi_ack or multi_ack_detailed:

•upload-pack sends "ACK obj-id" on the first common object it finds. After that it says nothing until the client gives it a "done".

•upload-pack sends "NAK" on a flush-pkt if no common object has been found yet. If one has been found, and thus an ACK was already sent, it’s silent on the flush-pkt.

After the client has gotten enough ACK responses that it can determine that the server has enough information to send an efficient packfile (in the canonical implementation, this is determined when it has received enough ACKs that it can color everything left in the --date-order queue as common with the server, or the --date-order queue is empty), or the client determines that it wants to give up (in the canonical implementation, this is determined when the client sends 256 have lines without getting any of them ACKed by the server - meaning there is nothing in common and the server should just send all of its objects), then the client will send a done command. The done command signals to the server that the client is ready to receive its packfile data.

However, the 256 limit only turns on in the canonical client implementation if we have received at least one "ACK %s continue" during a prior round. This helps to ensure that at least one common ancestor is found before we give up entirely.

Once the done line is read from the client, the server will either send a final ACK obj-id or it will send a NAK. obj-id is the object name of the last commit determined to be common. The server only sends ACK after done if there is at least one common base and multi_ack or multi_ack_detailed is enabled. The server always sends NAK after done if there is no common base found.

Instead of ACK or NAK, the server may send an error message (for example, if it does not recognize an object in a want line received from the client).

Then the server will start sending its packfile data.

```
  server-response = *ack_multi ack / nak

  ack_multi       = PKT-LINE("ACK" SP obj-id ack_status)

  ack_status      = "continue" / "common" / "ready"

  ack             = PKT-LINE("ACK" SP obj-id)

  nak             = PKT-LINE("NAK")
```

A simple clone may look like this (with no have lines):

```
   C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \

     side-band-64k ofs-delta\n

   C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n

   C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n

   C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n

   C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n

   C: 0000

   C: 0009done\n

   S: 0008NAK\n

   S: [PACKFILE]
```

An incremental update (fetch) response might look like this:

```
   C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \

     side-band-64k ofs-delta\n

   C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n

   C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n

   C: 0000

   C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n

   C: [30 more have lines]

   C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n

   C: 0000

   S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n

   S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n

   S: 0008NAK\n

   C: 0009done\n

   S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n

   S: [PACKFILE]
```

## PACKFILE DATA
Now that the client and server have finished negotiation about what the minimal amount of data that needs to be sent to the client is, the server will construct and send the required data in packfile format.

See gitformat-pack(5) for what the packfile itself actually looks like.

If side-band or side-band-64k capabilities have been specified by the client, the server will send the packfile data multiplexed.

Each packet starting with the packet-line length of the amount of data that follows, followed by a single byte specifying the sideband the following data is coming in on.

In side-band mode, it will send up to 999 data bytes plus 1 control code, for a total of up to 1000 bytes in a pkt-line. In side-band-64k mode it will send up to 65519 data bytes plus 1 control code, for a total of up to 65520 bytes in a pkt-line.

The sideband byte will be a 1, 2 or a 3. Sideband 1 will contain packfile data, sideband 2 will be used for progress information that the client will generally print to stderr and sideband 3 is used for error information.

If no side-band capability was specified, the server will stream the entire packfile without multiplexing.

## PUSHING DATA TO A SERVER
Pushing data to a server will invoke the receive-pack process on the server, which will allow the client to tell it which references it should update and then send all the data the server will need for those new references to be complete. Once all the data is received and validated, the server will then update its references to what the client specified.

## AUTHENTICATION
The protocol itself contains no authentication mechanisms. That is to be handled by the transport, such as SSH, before the receive-pack process is invoked. If receive-pack is configured over the Git transport, those repositories will be writable by anyone who can access that port (9418) as that transport is unauthenticated.

## REFERENCE DISCOVERY
The reference discovery phase is done nearly the same way as it is in the fetching protocol. Each reference obj-id and name on the server is sent in packet-line format to the client, followed by a flush-pkt. The only real difference is that the capability listing is different - the only possible values are report-status, report-status-v2, delete-refs, ofs-delta, atomic and push-options.

## REFERENCE UPDATE REQUEST AND PACKFILE TRANSFER
Once the client knows what references the server is at, it can send a list of reference update requests. For each reference on the server that it wants to update, it sends a line listing the obj-id currently on the server, the obj-id the client would like to update it to and the name of the reference.

This list is followed by a flush-pkt.

```
  update-requests   =  *shallow ( command-list | push-cert )

  shallow           =  PKT-LINE("shallow" SP obj-id)

  command-list      =  PKT-LINE(command NUL capability-list)

                       *PKT-LINE(command)

                       flush-pkt

  command           =  create / delete / update

  create            =  zero-id SP new-id  SP name

  delete            =  old-id  SP zero-id SP name

  update            =  old-id  SP new-id  SP name

  old-id            =  obj-id

  new-id            =  obj-id

  push-cert         = PKT-LINE("push-cert" NUL capability-list LF)

                      PKT-LINE("certificate version 0.1" LF)

                      PKT-LINE("pusher" SP ident LF)

                      PKT-LINE("pushee" SP url LF)

                      PKT-LINE("nonce" SP nonce LF)

                      *PKT-LINE("push-option" SP push-option LF)

                      PKT-LINE(LF)

                      *PKT-LINE(command LF)

                      *PKT-LINE(gpg-signature-lines LF)

                      PKT-LINE("push-cert-end" LF)

  push-option       =  1*( VCHAR | SP )
```

If the server has advertised the push-options capability and the client has specified push-options as part of the capability list above, the client then sends its push options followed by a flush-pkt.

```
  push-options      =  *PKT-LINE(push-option) flush-pkt
```

For backwards compatibility with older Git servers, if the client sends a push cert and push options, it MUST send its push options both embedded within the push cert and after the push cert. (Note that the push options within the cert are prefixed, but the push options after the cert are not.) Both these lists MUST be the same, modulo the prefix.

After that the packfile that should contain all the objects that the server will need to complete the new references will be sent.

```
  packfile          =  "PACK" 28*(OCTET)
```

If the receiving end does not support delete-refs, the sending end MUST NOT ask for delete command.

If the receiving end does not support push-cert, the sending end MUST NOT send a push-cert command. When a push-cert command is sent, command-list MUST NOT be sent; the commands recorded in the push certificate is used instead.

The packfile MUST NOT be sent if the only command used is delete.

A packfile MUST be sent if either create or update command is used, even if the server already has all the necessary objects. In this case the client MUST send an empty packfile. The only time this is likely to happen is if the client is creating a new branch or a tag that points to an existing obj-id.

The server will receive the packfile, unpack it, then validate each reference that is being updated that it hasn’t changed while the request was being processed (the obj-id is still the same as the old-id), and it will run any update hooks to make sure that the update is acceptable. If all of that is fine, the server will then update the references.

## PUSH CERTIFICATE
A push certificate begins with a set of header lines. After the header and an empty line, the protocol commands follow, one per line. Note that the trailing LF in push-cert PKT-LINEs is not optional; it must be present.

Currently, the following header fields are defined:

pusher ident

Identify the GPG key in "Human Readable Name <email@address[1]>" format.

pushee url

The repository URL (anonymized, if the URL contains authentication material) the user who ran git push intended to push into.

nonce nonce

The nonce string the receiving repository asked the pushing user to include in the certificate, to prevent replay attacks.

The GPG signature lines are a detached signature for the contents recorded in the push certificate before the signature block begins. The detached signature is used to certify that the commands were given by the pusher, who must be the signer.

## REPORT STATUS
After receiving the pack data from the sender, the receiver sends a report if report-status or report-status-v2 capability is in effect. It is a short listing of what happened in that update. It will first list the status of the packfile unpacking as either unpack ok or unpack [error]. Then it will list the status for each of the references that it tried to update. Each line is either ok [refname] if the update was successful, or ng [refname] [error] if the update was not.

```
  report-status     = unpack-status

                      1*(command-status)

                      flush-pkt

  unpack-status     = PKT-LINE("unpack" SP unpack-result)

  unpack-result     = "ok" / error-msg

  command-status    = command-ok / command-fail

  command-ok        = PKT-LINE("ok" SP refname)

  command-fail      = PKT-LINE("ng" SP refname SP error-msg)

  error-msg         = 1*(OCTET) ; where not "ok"
```

The report-status-v2 capability extends the protocol by adding new option lines in order to support reporting of reference rewritten by the proc-receive hook. The proc-receive hook may handle a command for a pseudo-reference which may create or update one or more references, and each reference may have different name, different new-oid, and different old-oid.

```
  report-status-v2  = unpack-status

                      1*(command-status-v2)

                      flush-pkt

  unpack-status     = PKT-LINE("unpack" SP unpack-result)

  unpack-result     = "ok" / error-msg

  command-status-v2 = command-ok-v2 / command-fail

  command-ok-v2     = command-ok

                      *option-line

  command-ok        = PKT-LINE("ok" SP refname)

  command-fail      = PKT-LINE("ng" SP refname SP error-msg)

  error-msg         = 1*(OCTET) ; where not "ok"

  option-line       = *1(option-refname)

                      *1(option-old-oid)

                      *1(option-new-oid)

                      *1(option-forced-update)

  option-refname    = PKT-LINE("option" SP "refname" SP refname)

  option-old-oid    = PKT-LINE("option" SP "old-oid" SP obj-id)

  option-new-oid    = PKT-LINE("option" SP "new-oid" SP obj-id)

  option-force      = PKT-LINE("option" SP "forced-update")
```

Updates can be unsuccessful for a number of reasons. The reference can have changed since the reference discovery phase was originally sent, meaning someone pushed in the meantime. The reference being pushed could be a non-fast-forward reference and the update hooks or configuration could be set to not allow that, etc. Also, some references can be updated while others can be rejected.

An example client/server communication might look like this:

```
   S: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n

   S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n

   S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n

   S: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n

   S: 0000

   C: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n

   C: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n

   C: 0000

   C: [PACKDATA]

   S: 000eunpack ok\n

   S: 0018ok refs/heads/debug\n

   S: 002ang refs/heads/master non-fast-forward\n
```

## GIT
Part of the git(1) suite

## NOTES
1.

email@address

mailto:email@address

branch: sisyphus


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

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