diff options
Diffstat (limited to 'Documentation/technical/pack-protocol.txt')
| -rw-r--r-- | Documentation/technical/pack-protocol.txt | 78 |
1 files changed, 44 insertions, 34 deletions
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 462e20645f..c59ac9936a 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -1,11 +1,11 @@ Packfile transfer protocols =========================== -Git supports transferring data in packfiles over the ssh://, git:// and +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. All three transports (ssh, git, file) use the same -protocol to transfer data. +server to a client. The three transports (ssh, git, file) use the same +protocol to transfer data. http is documented in http-protocol.txt. 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; @@ -14,6 +14,14 @@ 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 +protocol-common.txt. When the grammar indicate `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. + Transports ---------- There are three transports over which the packfile protocol is @@ -143,9 +151,6 @@ with the object name that each reference currently points to. 003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{} 0000 -Server SHOULD terminate each non-flush line using LF ("\n") terminator; -client MUST NOT complain if there is no terminator. - 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. @@ -165,15 +170,15 @@ MUST peel the ref if it's an annotated tag. flush-pkt no-refs = PKT-LINE(zero-id SP "capabilities^{}" - NUL capability-list LF) + NUL capability-list) list-of-refs = first-ref *other-ref first-ref = PKT-LINE(obj-id SP refname - NUL capability-list LF) + NUL capability-list) other-ref = PKT-LINE(other-tip / other-peeled) - other-tip = obj-id SP refname LF - other-peeled = obj-id SP refname "^{}" LF + other-tip = obj-id SP refname + other-peeled = obj-id SP refname "^{}" shallow = PKT-LINE("shallow" SP obj-id) @@ -214,10 +219,12 @@ out of what the server said it could do with the first 'want' line. shallow-line = PKT-LINE("shallow" SP obj-id) - depth-request = PKT-LINE("deepen" SP depth) + 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 LF) - additional-want = PKT-LINE("want" SP obj-id LF) + first-want = PKT-LINE("want" SP obj-id SP capability-list) + additional-want = PKT-LINE("want" SP obj-id) depth = 1*DIGIT ---- @@ -284,7 +291,7 @@ so that there is always a block of 32 "in-flight on the wire" at a time. compute-end have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) + have-line = PKT-LINE("have" SP obj-id) compute-end = flush-pkt / PKT-LINE("done") ---- @@ -302,7 +309,7 @@ In multi_ack mode: ready to make a packfile, it will blindly ACK all 'have' obj-ids back to the client. - * the server will then send a 'NACK' and then wait for another response + * 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: @@ -348,10 +355,10 @@ 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 LF) + ack_multi = PKT-LINE("ACK" SP obj-id ack_status) ack_status = "continue" / "common" / "ready" - ack = PKT-LINE("ACK SP obj-id LF) - nak = PKT-LINE("NAK" LF) + ack = PKT-LINE("ACK" SP obj-id) + nak = PKT-LINE("NAK") ---- A simple clone may look like this (with no 'have' lines): @@ -449,7 +456,8 @@ 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', 'delete-refs' and 'ofs-delta'. +possible values are 'report-status', 'delete-refs', 'ofs-delta' and +'push-options'. Reference Update Request and Packfile Transfer ---------------------------------------------- @@ -460,17 +468,18 @@ 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 and then the packfile that should -contain all the objects that the server will need to complete the new -references. +This list is followed by a flush-pkt. Then the push options are transmitted +one per packet followed by another flush-pkt. After that the packfile that +should contain all the objects that the server will need to complete the new +references will be sent. ---- - update-request = *shallow ( command-list | push-cert ) [pack-file] + update-request = *shallow ( command-list | push-cert ) [packfile] - shallow = PKT-LINE("shallow" SP obj-id LF) + shallow = PKT-LINE("shallow" SP obj-id) - command-list = PKT-LINE(command NUL capability-list LF) - *PKT-LINE(command LF) + command-list = PKT-LINE(command NUL capability-list) + *PKT-LINE(command) flush-pkt command = create / delete / update @@ -491,7 +500,7 @@ references. *PKT-LINE(gpg-signature-lines LF) PKT-LINE("push-cert-end" LF) - pack-file = "PACK" 28*(OCTET) + packfile = "PACK" 28*(OCTET) ---- If the receiving end does not support delete-refs, the sending end MUST @@ -502,11 +511,11 @@ 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 pack-file MUST NOT be sent if the only command used is 'delete'. +The packfile MUST NOT be sent if the only command used is 'delete'. -A pack-file MUST be sent if either create or update command is used, +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 pack-file. The only time 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. @@ -521,7 +530,8 @@ 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. +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: @@ -560,12 +570,12 @@ update was successful, or 'ng [refname] [error]' if the update was not. 1*(command-status) flush-pkt - unpack-status = PKT-LINE("unpack" SP unpack-result LF) + 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 LF) - command-fail = PKT-LINE("ng" SP refname SP error-msg LF) + command-ok = PKT-LINE("ok" SP refname) + command-fail = PKT-LINE("ng" SP refname SP error-msg) error-msg = 1*(OCTECT) ; where not "ok" ---- |