| gitprotocol-capabilities(5) | |
| =========================== | |
| NAME | |
| ---- | |
| gitprotocol-capabilities - Protocol v0 and v1 capabilities | |
| SYNOPSIS | |
| -------- | |
| [verse] | |
| <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 linkgit: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 linkgit: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 linkgit: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 linkgit: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 | |
| link:technical/api-trace2.html[api-trace2] for details), but this may change | |
| and users of the session ID should not rely on this fact. | |
| GIT | |
| --- | |
| Part of the linkgit:git[1] suite |