]>
Commit | Line | Data |
---|---|---|
b31222cf SC |
1 | Git Protocol Capabilities |
2 | ========================= | |
3 | ||
4 | Servers SHOULD support all capabilities defined in this document. | |
5 | ||
6 | On the very first line of the initial server response of either | |
7 | receive-pack and upload-pack the first reference is followed by | |
8 | a NUL byte and then a list of space delimited server capabilities. | |
9 | These allow the server to declare what it can and cannot support | |
10 | to the client. | |
11 | ||
12 | Client will then send a space separated list of capabilities it wants | |
13 | to be in effect. The client MUST NOT ask for capabilities the server | |
14 | did not say it supports. | |
15 | ||
16 | Server MUST diagnose and abort if capabilities it does not understand | |
17 | was sent. Server MUST NOT ignore capabilities that client requested | |
18 | and server advertised. As a consequence of these rules, server MUST | |
19 | NOT advertise capabilities it does not understand. | |
20 | ||
21 | The 'report-status' and 'delete-refs' capabilities are sent and | |
22 | recognized by the receive-pack (push to server) process. | |
23 | ||
24 | The 'ofs-delta' capability is sent and recognized by both upload-pack | |
25 | and receive-pack protocols. | |
26 | ||
27 | All other capabilities are only recognized by the upload-pack (fetch | |
28 | from server) process. | |
29 | ||
30 | multi_ack | |
31 | --------- | |
32 | ||
33 | The 'multi_ack' capability allows the server to return "ACK obj-id | |
34 | continue" as soon as it finds a commit that it can use as a common | |
35 | base, between the client's wants and the client's have set. | |
36 | ||
37 | By sending this early, the server can potentially head off the client | |
38 | from walking any further down that particular branch of the client's | |
39 | repository history. The client may still need to walk down other | |
40 | branches, sending have lines for those, until the server has a | |
41 | complete cut across the DAG, or the client has said "done". | |
42 | ||
43 | Without multi_ack, a client sends have lines in --date-order until | |
44 | the server has found a common base. That means the client will send | |
45 | have lines that are already known by the server to be common, because | |
46 | they overlap in time with another branch that the server hasn't found | |
47 | a common base on yet. | |
48 | ||
49 | For example suppose the client has commits in caps that the server | |
50 | doesn't and the server has commits in lower case that the client | |
51 | doesn't, as in the following diagram: | |
52 | ||
53 | +---- u ---------------------- x | |
54 | / +----- y | |
55 | / / | |
56 | a -- b -- c -- d -- E -- F | |
57 | \ | |
58 | +--- Q -- R -- S | |
59 | ||
60 | If the client wants x,y and starts out by saying have F,S, the server | |
61 | doesn't know what F,S is. Eventually the client says "have d" and | |
62 | the server sends "ACK d continue" to let the client know to stop | |
6a5d0b0a | 63 | walking down that line (so don't send c-b-a), but it's not done yet, |
b31222cf SC |
64 | it needs a base for x. The client keeps going with S-R-Q, until a |
65 | gets reached, at which point the server has a clear base and it all | |
66 | ends. | |
67 | ||
68 | Without multi_ack the client would have sent that c-b-a chain anyway, | |
69 | interleaved with S-R-Q. | |
70 | ||
71 | thin-pack | |
72 | --------- | |
73 | ||
74 | This capability means that the server can send a 'thin' pack, a pack | |
75 | which does not contain base objects; if those base objects are available | |
76 | on client side. Client requests 'thin-pack' capability when it | |
77 | understands how to "thicken" it by adding required delta bases making | |
78 | it self-contained. | |
79 | ||
80 | Client MUST NOT request 'thin-pack' capability if it cannot turn a thin | |
81 | pack into a self-contained pack. | |
82 | ||
83 | ||
84 | side-band, side-band-64k | |
85 | ------------------------ | |
86 | ||
87 | This capability means that server can send, and client understand multiplexed | |
88 | progress reports and error info interleaved with the packfile itself. | |
89 | ||
90 | These two options are mutually exclusive. A modern client always | |
91 | favors 'side-band-64k'. | |
92 | ||
93 | Either mode indicates that the packfile data will be streamed broken | |
94 | up into packets of up to either 1000 bytes in the case of 'side_band', | |
95 | or 65520 bytes in the case of 'side_band_64k'. Each packet is made up | |
96 | of a leading 4-byte pkt-line length of how much data is in the packet, | |
97 | followed by a 1-byte stream code, followed by the actual data. | |
98 | ||
99 | The stream code can be one of: | |
100 | ||
101 | 1 - pack data | |
102 | 2 - progress messages | |
103 | 3 - fatal error message just before stream aborts | |
104 | ||
105 | The "side-band-64k" capability came about as a way for newer clients | |
106 | that can handle much larger packets to request packets that are | |
107 | actually crammed nearly full, while maintaining backward compatibility | |
108 | for the older clients. | |
109 | ||
110 | Further, with side-band and its up to 1000-byte messages, it's actually | |
111 | 999 bytes of payload and 1 byte for the stream code. With side-band-64k, | |
112 | same deal, you have up to 65519 bytes of data and 1 byte for the stream | |
113 | code. | |
114 | ||
115 | The client MUST send only maximum of one of "side-band" and "side- | |
116 | band-64k". Server MUST diagnose it as an error if client requests | |
117 | both. | |
118 | ||
119 | ofs-delta | |
120 | --------- | |
121 | ||
122 | Server can send, and client understand PACKv2 with delta refering to | |
123 | its base by position in pack rather than by an obj-id. That is, they can | |
124 | send/read OBJ_OFS_DELTA (aka type 6) in a packfile. | |
125 | ||
126 | shallow | |
127 | ------- | |
128 | ||
129 | This capability adds "deepen", "shallow" and "unshallow" commands to | |
130 | the fetch-pack/upload-pack protocol so clients can request shallow | |
131 | clones. | |
132 | ||
133 | no-progress | |
134 | ----------- | |
135 | ||
136 | The client was started with "git clone -q" or something, and doesn't | |
137 | want that side band 2. Basically the client just says "I do not | |
138 | wish to receive stream 2 on sideband, so do not send it to me, and if | |
139 | you did, I will drop it on the floor anyway". However, the sideband | |
140 | channel 3 is still used for error responses. | |
141 | ||
142 | include-tag | |
143 | ----------- | |
144 | ||
145 | The 'include-tag' capability is about sending annotated tags if we are | |
146 | sending objects they point to. If we pack an object to the client, and | |
147 | a tag object points exactly at that object, we pack the tag object too. | |
148 | In general this allows a client to get all new annotated tags when it | |
149 | fetches a branch, in a single network connection. | |
150 | ||
151 | Clients MAY always send include-tag, hardcoding it into a request when | |
152 | the server advertises this capability. The decision for a client to | |
153 | request include-tag only has to do with the client's desires for tag | |
154 | data, whether or not a server had advertised objects in the | |
155 | refs/tags/* namespace. | |
156 | ||
157 | Servers MUST pack the tags if their referrant is packed and the client | |
158 | has requested include-tags. | |
159 | ||
160 | Clients MUST be prepared for the case where a server has ignored | |
161 | include-tag and has not actually sent tags in the pack. In such | |
162 | cases the client SHOULD issue a subsequent fetch to acquire the tags | |
163 | that include-tag would have otherwise given the client. | |
164 | ||
165 | The server SHOULD send include-tag, if it supports it, regardless | |
166 | of whether or not there are tags available. | |
167 | ||
168 | report-status | |
169 | ------------- | |
170 | ||
171 | The upload-pack process can receive a 'report-status' capability, | |
172 | which tells it that the client wants a report of what happened after | |
173 | a packfile upload and reference update. If the pushing client requests | |
174 | this capability, after unpacking and updating references the server | |
175 | will respond with whether the packfile unpacked successfully and if | |
176 | each reference was updated successfully. If any of those were not | |
177 | successful, it will send back an error message. See pack-protocol.txt | |
178 | for example messages. | |
179 | ||
180 | delete-refs | |
181 | ----------- | |
182 | ||
183 | If the server sends back the 'delete-refs' capability, it means that | |
6a5d0b0a | 184 | it is capable of accepting a zero-id value as the target |
b31222cf SC |
185 | value of a reference update. It is not sent back by the client, it |
186 | simply informs the client that it can be sent zero-id values | |
187 | to delete references. |