gitmodules

title: gitmodules(5)

summary: Defining submodule properties

text:
# gitmodules(5)

## NAME
gitmodules - Defining submodule properties

## SYNOPSIS
$GIT_WORK_TREE/.gitmodules

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

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

submodule.<name>.path

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

submodule.<name>.url

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

In addition, there are a number of optional keys:

submodule.<name>.update

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

submodule.<name>.branch

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

submodule.<name>.fetchRecurseSubmodules

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

submodule.<name>.ignore

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

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

dirty

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

untracked

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

none

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

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

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

submodule.<name>.shallow

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

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

## EXAMPLES
Consider the following .gitmodules file:

```
[submodule "libfoo"]

        path = include/foo

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

        path = include/bar

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

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

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

## GIT
Part of the git(1) suite


gitprotocol-capabilities

package: git-core

title: gitprotocol-capabilities(5)

summary: Protocol v0 and v1 capabilities

text:
# gitprotocol-capabilities(5)

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

## SYNOPSIS

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

## DESCRIPTION

Note this document describes capabilities for versions 0 and 1 of the pack protocol. For version 2, please refer to the gitprotocol-v2(5) doc.

Servers SHOULD support all capabilities defined in this document.

On the very first line of the initial server response of either receive-pack and upload-pack the first reference is followed by a NUL byte and then a list of space delimited server capabilities. These allow the server to declare what it can and cannot support to the client.

Client will then send a space separated list of capabilities it wants to be in effect. The client MUST NOT ask for capabilities the server did not say it supports.

Server MUST diagnose and abort if capabilities it does not understand were sent. Server MUST NOT ignore capabilities that client requested and server advertised. As a consequence of these rules, server MUST NOT advertise capabilities it does not understand.

The atomic, report-status, report-status-v2, delete-refs, quiet, and push-cert capabilities are sent and recognized by the receive-pack (push to server) process.

The ofs-delta and side-band-64k capabilities are sent and recognized by both upload-pack and receive-pack protocols. The agent and session-id capabilities may optionally be sent in both protocols.

All other capabilities are only recognized by the upload-pack (fetch from server) process.

## MULTI_ACK
The multi_ack capability allows the server to return "ACK obj-id continue" as soon as it finds a commit that it can use as a common base, between the client’s wants and the client’s have set.

By sending this early, the server can potentially head off the client from walking any further down that particular branch of the client’s repository history. The client may still need to walk down other branches, sending have lines for those, until the server has a complete cut across the DAG, or the client has said "done".

Without multi_ack, a client sends have lines in --date-order until the server has found a common base. That means the client will send have lines that are already known by the server to be common, because they overlap in time with another branch on which the server hasn’t found a common base yet.

For example suppose the client has commits in caps that the server doesn’t and the server has commits in lower case that the client doesn’t, as in the following diagram:

```
   +---- u ---------------------- x

  /              +----- y

 /              /
a -- b -- c -- d -- E -- F

   \

    +--- Q -- R -- S
```

If the client wants x,y and starts out by saying have F,S, the server doesn’t know what F,S is. Eventually the client says "have d" and the server sends "ACK d continue" to let the client know to stop walking down that line (so don’t send c-b-a), but it’s not done yet, it needs a base for x. The client keeps going with S-R-Q, until a gets reached, at which point the server has a clear base and it all ends.

Without multi_ack the client would have sent that c-b-a chain anyway, interleaved with S-R-Q.

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

## NO-DONE
This capability should only be used with the smart HTTP protocol. If multi_ack_detailed and no-done are both present, then the sender is free to immediately send a pack following its first "ACK obj-id ready" message.

Without no-done in the smart HTTP protocol, the server session would end and the client has to make another trip to send "done" before the server can send the pack. no-done removes the last round and thus slightly reduces latency.

## THIN-PACK
A thin pack is one with deltas which reference base objects not contained within the pack (but are known to exist at the receiving end). This can reduce the network traffic significantly, but it requires the receiving end to know how to "thicken" these packs by adding the missing bases to the pack.

The upload-pack server advertises thin-pack when it can generate and send a thin pack. A client requests the thin-pack capability when it understands how to "thicken" it, notifying the server that it can receive such a pack. A client MUST NOT request the thin-pack capability if it cannot turn a thin pack into a self-contained pack.

Receive-pack, on the other hand, is assumed by default to be able to handle thin packs, but can ask the client not to use the feature by advertising the no-thin capability. A client MUST NOT send a thin pack if the server advertises the no-thin capability.

The reasons for this asymmetry are historical. The receive-pack program did not exist until after the invention of thin packs, so historically the reference implementation of receive-pack always understood thin packs. Adding no-thin later allowed receive-pack to disable the feature in a backwards-compatible manner.

## SIDE-BAND, SIDE-BAND-64K
This capability means that the server can send, and the client can understand, multiplexed progress reports and error info interleaved with the packfile itself.

These two options are mutually exclusive. A modern client always favors side-band-64k.

Either mode indicates that the packfile data will be streamed broken up into packets of up to either 1000 bytes in the case of side_band, or 65520 bytes in the case of side_band_64k. Each packet is made up of a leading 4-byte pkt-line length of how much data is in the packet, followed by a 1-byte stream code, followed by the actual data.

The stream code can be one of:

```
1 - pack data
2 - progress messages
3 - fatal error message just before stream aborts
```

The "side-band-64k" capability came about as a way for newer clients that can handle much larger packets to request packets that are actually crammed nearly full, while maintaining backward compatibility for the older clients.

Further, with side-band and its up to 1000-byte messages, it’s actually 999 bytes of payload and 1 byte for the stream code. With side-band-64k, same deal, you have up to 65519 bytes of data and 1 byte for the stream code.

The client MUST send only one of "side-band" and "side- band-64k". The server MUST diagnose it as an error if client requests both.

## OFS-DELTA
The server can send, and the client can understand, PACKv2 with delta referring to its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile.

## AGENT
The server may optionally send a capability of the form agent=X to notify the client that the server is running version X. The client may optionally return its own agent string by responding with an agent=Y capability (but it MUST NOT do so if the server did not mention the agent capability). The X and Y strings may contain any printable ASCII characters except space (i.e., the byte range 32 < x < 127), and are typically of the form "package/version" (e.g., "git/1.8.3.1"). The agent strings are purely informative for statistics and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features.

## OBJECT-FORMAT
This capability, which takes a hash algorithm as an argument, indicates that the server supports the given hash algorithms. It may be sent multiple times; if so, the first one given is the one used in the ref advertisement.

When provided by the client, this indicates that it intends to use the given hash algorithm to communicate. The algorithm provided must be one that the server supports.

If this capability is not provided, it is assumed that the only supported algorithm is SHA-1.

## SYMREF
This parameterized capability is used to inform the receiver which symbolic ref points to which ref; for example, "symref=HEAD:refs/heads/master" tells the receiver that HEAD points to master. This capability can be repeated to represent multiple symrefs.

Servers SHOULD include this capability for the HEAD symref if it is one of the refs being sent.

Clients MAY use the parameters from this capability to select the proper initial branch when cloning a repository.

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

## DEEPEN-SINCE
This capability adds "deepen-since" command to fetch-pack/upload-pack protocol so the client can request shallow clones that are cut at a specific time, instead of depth. Internally it’s equivalent of doing "rev-list --max-age=<timestamp>" on the server side. "deepen-since" cannot be used with "deepen".

## DEEPEN-NOT
This capability adds "deepen-not" command to fetch-pack/upload-pack protocol so the client can request shallow clones that are cut at a specific revision, instead of depth. Internally it’s equivalent of doing "rev-list --not <rev>" on the server side. "deepen-not" cannot be used with "deepen", but can be used with "deepen-since".

## DEEPEN-RELATIVE
If this capability is requested by the client, the semantics of "deepen" command is changed. The "depth" argument is the depth from the current shallow boundary, instead of the depth from remote refs.

## NO-PROGRESS
The client was started with "git clone -q" or something similar, and doesn’t want that side band 2. Basically the client just says "I do not wish to receive stream 2 on sideband, so do not send it to me, and if you did, I will drop it on the floor anyway". However, the sideband channel 3 is still used for error responses.

## INCLUDE-TAG
The include-tag capability is about sending annotated tags if we are sending objects they point to. If we pack an object to the client, and a tag object points exactly at that object, we pack the tag object too. In general this allows a client to get all new annotated tags when it fetches a branch, in a single network connection.

Clients MAY always send include-tag, hardcoding it into a request when the server advertises this capability. The decision for a client to request include-tag only has to do with the client’s desires for tag data, whether or not a server had advertised objects in the refs/tags/* namespace.

Servers MUST pack the tags if their referent is packed and the client has requested include-tags.

Clients MUST be prepared for the case where a server has ignored include-tag and has not actually sent tags in the pack. In such cases the client SHOULD issue a subsequent fetch to acquire the tags that include-tag would have otherwise given the client.

The server SHOULD send include-tag, if it supports it, regardless of whether or not there are tags available.

## REPORT-STATUS
The receive-pack process can receive a report-status capability, which tells it that the client wants a report of what happened after a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server will respond with whether the packfile unpacked successfully and if each reference was updated successfully. If any of those were not successful, it will send back an error message. See gitprotocol-pack(5) for example messages.

## REPORT-STATUS-V2
Capability report-status-v2 extends capability report-status by adding new "option" directives in order to support reference rewritten by the "proc-receive" hook. The "proc-receive" hook may handle a command for a pseudo-reference which may create or update a reference with different name, new-oid, and old-oid. While the capability report-status cannot report for such case. See gitprotocol-pack(5) for details.

## DELETE-REFS
If the server sends back the delete-refs capability, it means that it is capable of accepting a zero-id value as the target value of a reference update. It is not sent back by the client, it simply informs the client that it can be sent zero-id values to delete references.

## QUIET
If the receive-pack server advertises the quiet capability, it is capable of silencing human-readable progress output which otherwise may be shown when processing the received pack. A send-pack client should respond with the quiet capability to suppress server-side progress reporting if the local progress reporting is also being suppressed (e.g., via push -q, or if stderr does not go to a tty).

## ATOMIC
If the server sends the atomic capability it is capable of accepting atomic pushes. If the pushing client requests this capability, the server will update the refs in one atomic transaction. Either all refs are updated or none.

## PUSH-OPTIONS
If the server sends the push-options capability it is able to accept push options after the update commands have been sent, but before the packfile is streamed. If the pushing client requests this capability, the server will pass the options to the pre- and post- receive hooks that process this push request.

## ALLOW-TIP-SHA1-IN-WANT
If the upload-pack server advertises this capability, fetch-pack may send "want" lines with object names that exist at the server but are not advertised by upload-pack. For historical reasons, the name of this capability contains "sha1". Object names are always given using the object format negotiated through the object-format capability.

## ALLOW-REACHABLE-SHA1-IN-WANT
If the upload-pack server advertises this capability, fetch-pack may send "want" lines with object names that exist at the server but are not advertised by upload-pack. For historical reasons, the name of this capability contains "sha1". Object names are always given using the object format negotiated through the object-format capability.

## PUSH-CERT=<NONCE>
The receive-pack server that advertises this capability is willing to accept a signed push certificate, and asks the <nonce> to be included in the push certificate. A send-pack client MUST NOT send a push-cert packet unless the receive-pack server advertises this capability.

## FILTER
If the upload-pack server advertises the filter capability, fetch-pack may send "filter" commands to request a partial clone or partial fetch and request that the server omit various objects from the packfile.

## SESSION-ID=<SESSION-ID>
The server may advertise a session ID that can be used to identify this process across multiple requests. The client may advertise its own session ID back to the server as well.

Session IDs should be unique to a given process. They must fit within a packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see api-trace2[1] for details), but this may change and users of the session ID should not rely on this fact.

## GIT
Part of the git(1) suite

## NOTES
1.

api-trace2

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


gitprotocol-common

title: gitprotocol-common(5)

summary: Things common to various protocols

text:
# gitprotocol-common(5)

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

## SYNOPSIS

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

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

## ABNF NOTATION
ABNF notation as described by RFC 5234 is used within the protocol documents, except the following replacement core rules are used:

```
  HEXDIG    =  DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
```

We also define the following common rules:

```
  NUL       =  %x00

  zero-id   =  40*"0"

  obj-id    =  40*(HEXDIGIT)

  refname  =  "HEAD"

  refname /=  "refs/" <see discussion below>
```

A refname is a hierarchical octet string beginning with "refs/" and not violating the git-check-ref-format command’s validation rules. More specifically, they:

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

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

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

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

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

6.They cannot end with the sequence .lock.

7.They cannot contain a sequence @{.

8.They cannot contain a \\.

## PKT-LINE FORMAT
Much (but not all) of the payload is described around pkt-lines.

A pkt-line is a variable length binary string. The first four bytes of the line, the pkt-len, indicates the total length of the line, in hexadecimal. The pkt-len includes the 4 bytes used to contain the length’s hexadecimal representation.

A pkt-line MAY contain binary data, so implementors MUST ensure pkt-line parsing/formatting routines are 8-bit clean.

A non-binary line SHOULD BE terminated by an LF, which if present MUST be included in the total length. Receivers MUST treat pkt-lines with non-binary data the same whether or not they contain the trailing LF (stripping the LF if present, and not complaining when it is missing).

The maximum length of a pkt-line’s data component is 65516 bytes. Implementations MUST NOT send pkt-line whose length exceeds 65520 (65516 bytes of payload + 4 bytes of length data).

Implementations SHOULD NOT send an empty pkt-line ("0004").

A pkt-line with a length field of 0 ("0000"), called a flush-pkt, is a special case and MUST be handled differently than an empty pkt-line ("0004").

```
  pkt-line     =  data-pkt / flush-pkt

  data-pkt     =  pkt-len pkt-payload

  pkt-len      =  4*(HEXDIG)

  pkt-payload  =  (pkt-len - 4)*(OCTET)

  flush-pkt    = "0000"
```

Examples (as C-style strings):

```
  pkt-line          actual value

  ---------------------------------

  "0006a\n"         "a\n"

  "0005a"           "a"

  "000bfoobar\n"    "foobar\n"

  "0004"            ""
```

## GIT
Part of the git(1) suite


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

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