]>
Commit | Line | Data |
---|---|---|
5db92105 ÆAB |
1 | gitprotocol-pack(5) |
2 | =================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | gitprotocol-pack - How packs are transferred over-the-wire | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | <over-the-wire-protocol> | |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
b31222cf | 15 | |
055c7e9f | 16 | Git supports transferring data in packfiles over the ssh://, git://, http:// and |
b31222cf SC |
17 | file:// transports. There exist two sets of protocols, one for pushing |
18 | data from a client to a server and another for fetching data from a | |
055c7e9f | 19 | server to a client. The three transports (ssh, git, file) use the same |
1e232016 | 20 | protocol to transfer data. http is documented in linkgit:gitprotocol-http[5]. |
b31222cf SC |
21 | |
22 | The processes invoked in the canonical Git implementation are 'upload-pack' | |
23 | on the server side and 'fetch-pack' on the client side for fetching data; | |
24 | then 'receive-pack' on the server and 'send-pack' on the client for pushing | |
25 | data. The protocol functions to have a server tell a client what is | |
26 | currently on the server, then for the two to negotiate the smallest amount | |
27 | of data to send in order to fully update one or the other. | |
28 | ||
1c9b659d JK |
29 | pkt-line Format |
30 | --------------- | |
31 | ||
32 | The descriptions below build on the pkt-line format described in | |
5db92105 | 33 | linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless |
1c9b659d JK |
34 | otherwise noted the usual pkt-line LF rules apply: the sender SHOULD |
35 | include a LF, but the receiver MUST NOT complain if it is not present. | |
36 | ||
2d103c31 MS |
37 | An error packet is a special pkt-line that contains an error string. |
38 | ||
39 | ---- | |
40 | error-line = PKT-LINE("ERR" SP explanation-text) | |
41 | ---- | |
42 | ||
43 | Throughout the protocol, where `PKT-LINE(...)` is expected, an error packet MAY | |
44 | be sent. Once this packet is sent by a client or a server, the data transfer | |
45 | process defined in this protocol is terminated. | |
46 | ||
b31222cf SC |
47 | Transports |
48 | ---------- | |
49 | There are three transports over which the packfile protocol is | |
50 | initiated. The Git transport is a simple, unauthenticated server that | |
51 | takes the command (almost always 'upload-pack', though Git | |
52 | servers can be configured to be globally writable, in which 'receive- | |
53 | pack' initiation is also allowed) with which the client wishes to | |
54 | communicate and executes it and connects it to the requesting | |
55 | process. | |
56 | ||
57 | In the SSH transport, the client just runs the 'upload-pack' | |
58 | or 'receive-pack' process on the server over the SSH protocol and then | |
59 | communicates with that invoked process over the SSH connection. | |
60 | ||
61 | The file:// transport runs the 'upload-pack' or 'receive-pack' | |
62 | process locally and communicates with it over a pipe. | |
63 | ||
6464679d JT |
64 | Extra Parameters |
65 | ---------------- | |
66 | ||
67 | The protocol provides a mechanism in which clients can send additional | |
68 | information in its first message to the server. These are called "Extra | |
69 | Parameters", and are supported by the Git, SSH, and HTTP protocols. | |
70 | ||
71 | Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. | |
72 | ||
73 | Servers that receive any such Extra Parameters MUST ignore all | |
74 | unrecognized keys. Currently, the only Extra Parameter recognized is | |
5db92105 | 75 | "version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more |
f351b0ab | 76 | information on protocol version 2. |
6464679d | 77 | |
b31222cf SC |
78 | Git Transport |
79 | ------------- | |
80 | ||
81 | The Git transport starts off by sending the command and repository | |
82 | on the wire using the pkt-line format, followed by a NUL byte and a | |
8e50175d | 83 | hostname parameter, terminated by a NUL byte. |
b31222cf | 84 | |
6464679d JT |
85 | 0033git-upload-pack /project.git\0host=myserver.com\0 |
86 | ||
87 | The transport may send Extra Parameters by adding an additional NUL | |
88 | byte, and then adding one or more NUL-terminated strings: | |
89 | ||
90 | 003egit-upload-pack /project.git\0host=myserver.com\0\0version=1\0 | |
b31222cf SC |
91 | |
92 | -- | |
6464679d JT |
93 | git-proto-request = request-command SP pathname NUL |
94 | [ host-parameter NUL ] [ NUL extra-parameters ] | |
b31222cf SC |
95 | request-command = "git-upload-pack" / "git-receive-pack" / |
96 | "git-upload-archive" ; case sensitive | |
97 | pathname = *( %x01-ff ) ; exclude NUL | |
98 | host-parameter = "host=" hostname [ ":" port ] | |
6464679d JT |
99 | extra-parameters = 1*extra-parameter |
100 | extra-parameter = 1*( %x01-ff ) NUL | |
b31222cf SC |
101 | -- |
102 | ||
6464679d | 103 | host-parameter is used for the |
b31222cf SC |
104 | git-daemon name based virtual hosting. See --interpolated-path |
105 | option to git daemon, with the %H/%CH format characters. | |
106 | ||
107 | Basically what the Git client is doing to connect to an 'upload-pack' | |
108 | process on the server side over the Git protocol is this: | |
109 | ||
110 | $ echo -e -n \ | |
2c31a7aa | 111 | "003agit-upload-pack /schacon/gitbook.git\0host=example.com\0" | |
b31222cf SC |
112 | nc -v example.com 9418 |
113 | ||
114 | ||
115 | SSH Transport | |
116 | ------------- | |
117 | ||
118 | Initiating the upload-pack or receive-pack processes over SSH is | |
119 | executing the binary on the server via SSH remote execution. | |
120 | It is basically equivalent to running this: | |
121 | ||
122 | $ ssh git.example.com "git-upload-pack '/project.git'" | |
123 | ||
124 | For a server to support Git pushing and pulling for a given user over | |
125 | SSH, that user needs to be able to execute one or both of those | |
126 | commands via the SSH shell that they are provided on login. On some | |
127 | systems, that shell access is limited to only being able to run those | |
128 | two commands, or even just one of them. | |
129 | ||
130 | In an ssh:// format URI, it's absolute in the URI, so the '/' after | |
131 | the host name (or port number) is sent as an argument, which is then | |
132 | read by the remote git-upload-pack exactly as is, so it's effectively | |
133 | an absolute path in the remote filesystem. | |
134 | ||
135 | git clone ssh://user@example.com/project.git | |
136 | | | |
137 | v | |
138 | ssh user@example.com "git-upload-pack '/project.git'" | |
139 | ||
140 | In a "user@host:path" format URI, its relative to the user's home | |
141 | directory, because the Git client will run: | |
142 | ||
143 | git clone user@example.com:project.git | |
144 | | | |
145 | v | |
146 | ssh user@example.com "git-upload-pack 'project.git'" | |
147 | ||
148 | The exception is if a '~' is used, in which case | |
149 | we execute it without the leading '/'. | |
150 | ||
151 | ssh://user@example.com/~alice/project.git, | |
152 | | | |
153 | v | |
154 | ssh user@example.com "git-upload-pack '~alice/project.git'" | |
155 | ||
6464679d JT |
156 | Depending on the value of the `protocol.version` configuration variable, |
157 | Git may attempt to send Extra Parameters as a colon-separated string in | |
158 | the GIT_PROTOCOL environment variable. This is done only if | |
159 | the `ssh.variant` configuration variable indicates that the ssh command | |
160 | supports passing environment variables as an argument. | |
161 | ||
b31222cf SC |
162 | A few things to remember here: |
163 | ||
164 | - The "command name" is spelled with dash (e.g. git-upload-pack), but | |
165 | this can be overridden by the client; | |
166 | ||
167 | - The repository path is always quoted with single quotes. | |
168 | ||
169 | Fetching Data From a Server | |
5316c8e9 | 170 | --------------------------- |
b31222cf SC |
171 | |
172 | When one Git repository wants to get data that a second repository | |
173 | has, the first can 'fetch' from the second. This operation determines | |
174 | what data the server has that the client does not then streams that | |
175 | data down to the client in packfile format. | |
176 | ||
177 | ||
178 | Reference Discovery | |
179 | ------------------- | |
180 | ||
181 | When the client initially connects the server will immediately respond | |
6464679d JT |
182 | with a version number (if "version=1" is sent as an Extra Parameter), |
183 | and a listing of each reference it has (all branches and tags) along | |
b31222cf SC |
184 | with the object name that each reference currently points to. |
185 | ||
2c31a7aa | 186 | $ echo -e -n "0045git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" | |
b31222cf | 187 | nc -v example.com 9418 |
2c31a7aa | 188 | 000eversion 1 |
5316c8e9 TA |
189 | 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack |
190 | side-band side-band-64k ofs-delta shallow no-progress include-tag | |
b31222cf SC |
191 | 00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration |
192 | 003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master | |
193 | 003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9 | |
194 | 003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0 | |
195 | 003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{} | |
196 | 0000 | |
197 | ||
b31222cf SC |
198 | The returned response is a pkt-line stream describing each ref and |
199 | its current value. The stream MUST be sorted by name according to | |
200 | the C locale ordering. | |
201 | ||
202 | If HEAD is a valid ref, HEAD MUST appear as the first advertised | |
203 | ref. If HEAD is not a valid ref, HEAD MUST NOT appear in the | |
204 | advertisement list at all, but other refs may still appear. | |
205 | ||
206 | The stream MUST include capability declarations behind a NUL on the | |
207 | first ref. The peeled value of a ref (that is "ref^{}") MUST be | |
208 | immediately after the ref itself, if presented. A conforming server | |
6a5d0b0a | 209 | MUST peel the ref if it's an annotated tag. |
b31222cf SC |
210 | |
211 | ---- | |
6464679d JT |
212 | advertised-refs = *1("version 1") |
213 | (no-refs / list-of-refs) | |
ad491366 | 214 | *shallow |
b31222cf SC |
215 | flush-pkt |
216 | ||
217 | no-refs = PKT-LINE(zero-id SP "capabilities^{}" | |
1c9b659d | 218 | NUL capability-list) |
b31222cf SC |
219 | |
220 | list-of-refs = first-ref *other-ref | |
221 | first-ref = PKT-LINE(obj-id SP refname | |
1c9b659d | 222 | NUL capability-list) |
b31222cf SC |
223 | |
224 | other-ref = PKT-LINE(other-tip / other-peeled) | |
1c9b659d JK |
225 | other-tip = obj-id SP refname |
226 | other-peeled = obj-id SP refname "^{}" | |
b31222cf | 227 | |
ad491366 NTND |
228 | shallow = PKT-LINE("shallow" SP obj-id) |
229 | ||
b31222cf SC |
230 | capability-list = capability *(SP capability) |
231 | capability = 1*(LC_ALPHA / DIGIT / "-" / "_") | |
232 | LC_ALPHA = %x61-7A | |
233 | ---- | |
234 | ||
235 | Server and client MUST use lowercase for obj-id, both MUST treat obj-id | |
236 | as case-insensitive. | |
237 | ||
238 | See protocol-capabilities.txt for a list of allowed server capabilities | |
239 | and descriptions. | |
240 | ||
241 | Packfile Negotiation | |
242 | -------------------- | |
a1e90b23 AN |
243 | After reference and capabilities discovery, the client can decide to |
244 | terminate the connection by sending a flush-pkt, telling the server it can | |
245 | now gracefully terminate, and disconnect, when it does not need any pack | |
246 | data. This can happen with the ls-remote command, and also can happen when | |
7560f547 | 247 | the client already is up to date. |
a1e90b23 AN |
248 | |
249 | Otherwise, it enters the negotiation phase, where the client and | |
250 | server determine what the minimal packfile necessary for transport is, | |
4a1c2695 AN |
251 | by telling the server what objects it wants, its shallow objects |
252 | (if any), and the maximum commit depth it wants (if any). The client | |
253 | will also send a list of the capabilities it wants to be in effect, | |
254 | out of what the server said it could do with the first 'want' line. | |
b31222cf SC |
255 | |
256 | ---- | |
257 | upload-request = want-list | |
4a1c2695 AN |
258 | *shallow-line |
259 | *1depth-request | |
10ac85c7 | 260 | [filter-request] |
4a1c2695 | 261 | flush-pkt |
b31222cf SC |
262 | |
263 | want-list = first-want | |
264 | *additional-want | |
4a1c2695 | 265 | |
e543b3f6 | 266 | shallow-line = PKT-LINE("shallow" SP obj-id) |
4a1c2695 | 267 | |
569e554b | 268 | depth-request = PKT-LINE("deepen" SP depth) / |
269a7a83 NTND |
269 | PKT-LINE("deepen-since" SP timestamp) / |
270 | PKT-LINE("deepen-not" SP ref) | |
b31222cf | 271 | |
1c9b659d JK |
272 | first-want = PKT-LINE("want" SP obj-id SP capability-list) |
273 | additional-want = PKT-LINE("want" SP obj-id) | |
b31222cf | 274 | |
4a1c2695 | 275 | depth = 1*DIGIT |
10ac85c7 JH |
276 | |
277 | filter-request = PKT-LINE("filter" SP filter-spec) | |
b31222cf SC |
278 | ---- |
279 | ||
280 | Clients MUST send all the obj-ids it wants from the reference | |
281 | discovery phase as 'want' lines. Clients MUST send at least one | |
282 | 'want' command in the request body. Clients MUST NOT mention an | |
283 | obj-id in a 'want' command which did not appear in the response | |
284 | obtained through ref discovery. | |
285 | ||
4a1c2695 AN |
286 | The client MUST write all obj-ids which it only has shallow copies |
287 | of (meaning that it does not have the parents of a commit) as | |
288 | 'shallow' lines so that the server is aware of the limitations of | |
af04fa2a | 289 | the client's history. |
4a1c2695 AN |
290 | |
291 | The client now sends the maximum commit history depth it wants for | |
292 | this transaction, which is the number of commits it wants from the | |
293 | tip of the history, if any, as a 'deepen' line. A depth of 0 is the | |
294 | same as not making a depth request. The client does not want to receive | |
a58088ab JL |
295 | any commits beyond this depth, nor does it want objects needed only to |
296 | complete those commits. Commits whose parents are not received as a | |
297 | result are defined as shallow and marked as such in the server. This | |
298 | information is sent back to the client in the next step. | |
4a1c2695 | 299 | |
10ac85c7 JH |
300 | The client can optionally request that pack-objects omit various |
301 | objects from the packfile using one of several filtering techniques. | |
302 | These are intended for use with partial clone and partial fetch | |
a0c9016a JT |
303 | operations. An object that does not meet a filter-spec value is |
304 | omitted unless explicitly requested in a 'want' line. See `rev-list` | |
305 | for possible filter-spec values. | |
10ac85c7 | 306 | |
4a1c2695 AN |
307 | Once all the 'want's and 'shallow's (and optional 'deepen') are |
308 | transferred, clients MUST send a flush-pkt, to tell the server side | |
309 | that it is done sending the list. | |
310 | ||
311 | Otherwise, if the client sent a positive depth request, the server | |
312 | will determine which commits will and will not be shallow and | |
313 | send this information to the client. If the client did not request | |
314 | a positive depth, this step is skipped. | |
b31222cf | 315 | |
4a1c2695 AN |
316 | ---- |
317 | shallow-update = *shallow-line | |
318 | *unshallow-line | |
319 | flush-pkt | |
b31222cf | 320 | |
4a1c2695 AN |
321 | shallow-line = PKT-LINE("shallow" SP obj-id) |
322 | ||
323 | unshallow-line = PKT-LINE("unshallow" SP obj-id) | |
324 | ---- | |
325 | ||
326 | If the client has requested a positive depth, the server will compute | |
01f7d7f1 PO |
327 | the set of commits which are no deeper than the desired depth. The set |
328 | of commits start at the client's wants. | |
329 | ||
330 | The server writes 'shallow' lines for each | |
4a1c2695 AN |
331 | commit whose parents will not be sent as a result. The server writes |
332 | an 'unshallow' line for each commit which the client has indicated is | |
333 | shallow, but is no longer shallow at the currently requested depth | |
334 | (that is, its parents will now be sent). The server MUST NOT mark | |
335 | as unshallow anything which the client has not indicated was shallow. | |
b31222cf SC |
336 | |
337 | Now the client will send a list of the obj-ids it has using 'have' | |
4a1c2695 AN |
338 | lines, so the server can make a packfile that only contains the objects |
339 | that the client needs. In multi_ack mode, the canonical implementation | |
340 | will send up to 32 of these at a time, then will send a flush-pkt. The | |
341 | canonical implementation will skip ahead and send the next 32 immediately, | |
342 | so that there is always a block of 32 "in-flight on the wire" at a time. | |
343 | ||
344 | ---- | |
345 | upload-haves = have-list | |
346 | compute-end | |
347 | ||
348 | have-list = *have-line | |
1c9b659d | 349 | have-line = PKT-LINE("have" SP obj-id) |
4a1c2695 AN |
350 | compute-end = flush-pkt / PKT-LINE("done") |
351 | ---- | |
b31222cf SC |
352 | |
353 | If the server reads 'have' lines, it then will respond by ACKing any | |
354 | of the obj-ids the client said it had that the server also has. The | |
355 | server will ACK obj-ids differently depending on which ack mode is | |
356 | chosen by the client. | |
357 | ||
358 | In multi_ack mode: | |
359 | ||
360 | * the server will respond with 'ACK obj-id continue' for any common | |
361 | commits. | |
362 | ||
363 | * once the server has found an acceptable common base commit and is | |
364 | ready to make a packfile, it will blindly ACK all 'have' obj-ids | |
365 | back to the client. | |
366 | ||
280abfd4 | 367 | * the server will then send a 'NAK' and then wait for another response |
b31222cf SC |
368 | from the client - either a 'done' or another list of 'have' lines. |
369 | ||
370 | In multi_ack_detailed mode: | |
371 | ||
372 | * the server will differentiate the ACKs where it is signaling | |
373 | that it is ready to send data with 'ACK obj-id ready' lines, and | |
374 | signals the identified common commits with 'ACK obj-id common' lines. | |
375 | ||
376 | Without either multi_ack or multi_ack_detailed: | |
377 | ||
378 | * upload-pack sends "ACK obj-id" on the first common object it finds. | |
379 | After that it says nothing until the client gives it a "done". | |
380 | ||
381 | * upload-pack sends "NAK" on a flush-pkt if no common object | |
382 | has been found yet. If one has been found, and thus an ACK | |
6a5d0b0a | 383 | was already sent, it's silent on the flush-pkt. |
b31222cf SC |
384 | |
385 | After the client has gotten enough ACK responses that it can determine | |
386 | that the server has enough information to send an efficient packfile | |
387 | (in the canonical implementation, this is determined when it has received | |
388 | enough ACKs that it can color everything left in the --date-order queue | |
389 | as common with the server, or the --date-order queue is empty), or the | |
390 | client determines that it wants to give up (in the canonical implementation, | |
391 | this is determined when the client sends 256 'have' lines without getting | |
392 | any of them ACKed by the server - meaning there is nothing in common and | |
6a5d0b0a | 393 | the server should just send all of its objects), then the client will send |
b31222cf | 394 | a 'done' command. The 'done' command signals to the server that the client |
6a5d0b0a | 395 | is ready to receive its packfile data. |
b31222cf SC |
396 | |
397 | However, the 256 limit *only* turns on in the canonical client | |
398 | implementation if we have received at least one "ACK %s continue" | |
399 | during a prior round. This helps to ensure that at least one common | |
400 | ancestor is found before we give up entirely. | |
401 | ||
402 | Once the 'done' line is read from the client, the server will either | |
32752e96 NTND |
403 | send a final 'ACK obj-id' or it will send a 'NAK'. 'obj-id' is the object |
404 | name of the last commit determined to be common. The server only sends | |
b31222cf SC |
405 | ACK after 'done' if there is at least one common base and multi_ack or |
406 | multi_ack_detailed is enabled. The server always sends NAK after 'done' | |
407 | if there is no common base found. | |
408 | ||
8e2c7bef JT |
409 | Instead of 'ACK' or 'NAK', the server may send an error message (for |
410 | example, if it does not recognize an object in a 'want' line received | |
411 | from the client). | |
412 | ||
6a5d0b0a | 413 | Then the server will start sending its packfile data. |
b31222cf SC |
414 | |
415 | ---- | |
2d103c31 | 416 | server-response = *ack_multi ack / nak |
1c9b659d | 417 | ack_multi = PKT-LINE("ACK" SP obj-id ack_status) |
b31222cf | 418 | ack_status = "continue" / "common" / "ready" |
1c9b659d JK |
419 | ack = PKT-LINE("ACK" SP obj-id) |
420 | nak = PKT-LINE("NAK") | |
b31222cf SC |
421 | ---- |
422 | ||
423 | A simple clone may look like this (with no 'have' lines): | |
424 | ||
425 | ---- | |
79135e4c | 426 | C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ |
b31222cf SC |
427 | side-band-64k ofs-delta\n |
428 | C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n | |
429 | C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n | |
430 | C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n | |
431 | C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n | |
432 | C: 0000 | |
433 | C: 0009done\n | |
434 | ||
435 | S: 0008NAK\n | |
436 | S: [PACKFILE] | |
437 | ---- | |
438 | ||
439 | An incremental update (fetch) response might look like this: | |
440 | ||
441 | ---- | |
79135e4c | 442 | C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ |
b31222cf SC |
443 | side-band-64k ofs-delta\n |
444 | C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n | |
445 | C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n | |
446 | C: 0000 | |
447 | C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n | |
448 | C: [30 more have lines] | |
449 | C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n | |
450 | C: 0000 | |
451 | ||
452 | S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n | |
453 | S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n | |
454 | S: 0008NAK\n | |
455 | ||
456 | C: 0009done\n | |
457 | ||
c8a97906 | 458 | S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n |
b31222cf SC |
459 | S: [PACKFILE] |
460 | ---- | |
461 | ||
462 | ||
463 | Packfile Data | |
464 | ------------- | |
465 | ||
466 | Now that the client and server have finished negotiation about what | |
467 | the minimal amount of data that needs to be sent to the client is, the server | |
468 | will construct and send the required data in packfile format. | |
469 | ||
977c47b4 | 470 | See linkgit:gitformat-pack[5] for what the packfile itself actually looks like. |
b31222cf SC |
471 | |
472 | If 'side-band' or 'side-band-64k' capabilities have been specified by | |
473 | the client, the server will send the packfile data multiplexed. | |
474 | ||
475 | Each packet starting with the packet-line length of the amount of data | |
476 | that follows, followed by a single byte specifying the sideband the | |
477 | following data is coming in on. | |
478 | ||
479 | In 'side-band' mode, it will send up to 999 data bytes plus 1 control | |
480 | code, for a total of up to 1000 bytes in a pkt-line. In 'side-band-64k' | |
481 | mode it will send up to 65519 data bytes plus 1 control code, for a | |
482 | total of up to 65520 bytes in a pkt-line. | |
483 | ||
484 | The sideband byte will be a '1', '2' or a '3'. Sideband '1' will contain | |
485 | packfile data, sideband '2' will be used for progress information that the | |
486 | client will generally print to stderr and sideband '3' is used for error | |
487 | information. | |
488 | ||
489 | If no 'side-band' capability was specified, the server will stream the | |
490 | entire packfile without multiplexing. | |
491 | ||
492 | ||
493 | Pushing Data To a Server | |
5316c8e9 | 494 | ------------------------ |
b31222cf SC |
495 | |
496 | Pushing data to a server will invoke the 'receive-pack' process on the | |
497 | server, which will allow the client to tell it which references it should | |
498 | update and then send all the data the server will need for those new | |
499 | references to be complete. Once all the data is received and validated, | |
500 | the server will then update its references to what the client specified. | |
501 | ||
502 | Authentication | |
503 | -------------- | |
504 | ||
505 | The protocol itself contains no authentication mechanisms. That is to be | |
506 | handled by the transport, such as SSH, before the 'receive-pack' process is | |
507 | invoked. If 'receive-pack' is configured over the Git transport, those | |
508 | repositories will be writable by anyone who can access that port (9418) as | |
509 | that transport is unauthenticated. | |
510 | ||
511 | Reference Discovery | |
512 | ------------------- | |
513 | ||
514 | The reference discovery phase is done nearly the same way as it is in the | |
515 | fetching protocol. Each reference obj-id and name on the server is sent | |
516 | in packet-line format to the client, followed by a flush-pkt. The only | |
517 | real difference is that the capability listing is different - the only | |
b913075c JX |
518 | possible values are 'report-status', 'report-status-v2', 'delete-refs', |
519 | 'ofs-delta', 'atomic' and 'push-options'. | |
b31222cf SC |
520 | |
521 | Reference Update Request and Packfile Transfer | |
522 | ---------------------------------------------- | |
523 | ||
524 | Once the client knows what references the server is at, it can send a | |
525 | list of reference update requests. For each reference on the server | |
526 | that it wants to update, it sends a line listing the obj-id currently on | |
527 | the server, the obj-id the client would like to update it to and the name | |
528 | of the reference. | |
529 | ||
cbaf82cc | 530 | This list is followed by a flush-pkt. |
b31222cf SC |
531 | |
532 | ---- | |
cbaf82cc | 533 | update-requests = *shallow ( command-list | push-cert ) |
5dbd7676 | 534 | |
1c9b659d | 535 | shallow = PKT-LINE("shallow" SP obj-id) |
b31222cf | 536 | |
1c9b659d JK |
537 | command-list = PKT-LINE(command NUL capability-list) |
538 | *PKT-LINE(command) | |
b31222cf SC |
539 | flush-pkt |
540 | ||
541 | command = create / delete / update | |
542 | create = zero-id SP new-id SP name | |
543 | delete = old-id SP zero-id SP name | |
544 | update = old-id SP new-id SP name | |
545 | ||
546 | old-id = obj-id | |
547 | new-id = obj-id | |
548 | ||
4adf569d JH |
549 | push-cert = PKT-LINE("push-cert" NUL capability-list LF) |
550 | PKT-LINE("certificate version 0.1" LF) | |
551 | PKT-LINE("pusher" SP ident LF) | |
9be89160 | 552 | PKT-LINE("pushee" SP url LF) |
b89363e4 | 553 | PKT-LINE("nonce" SP nonce LF) |
cbaf82cc | 554 | *PKT-LINE("push-option" SP push-option LF) |
4adf569d JH |
555 | PKT-LINE(LF) |
556 | *PKT-LINE(command LF) | |
557 | *PKT-LINE(gpg-signature-lines LF) | |
558 | PKT-LINE("push-cert-end" LF) | |
559 | ||
cbaf82cc JT |
560 | push-option = 1*( VCHAR | SP ) |
561 | ---- | |
562 | ||
563 | If the server has advertised the 'push-options' capability and the client has | |
564 | specified 'push-options' as part of the capability list above, the client then | |
565 | sends its push options followed by a flush-pkt. | |
566 | ||
567 | ---- | |
568 | push-options = *PKT-LINE(push-option) flush-pkt | |
569 | ---- | |
570 | ||
571 | For backwards compatibility with older Git servers, if the client sends a push | |
572 | cert and push options, it MUST send its push options both embedded within the | |
573 | push cert and after the push cert. (Note that the push options within the cert | |
574 | are prefixed, but the push options after the cert are not.) Both these lists | |
575 | MUST be the same, modulo the prefix. | |
576 | ||
577 | After that the packfile that | |
578 | should contain all the objects that the server will need to complete the new | |
579 | references will be sent. | |
580 | ||
581 | ---- | |
582 | packfile = "PACK" 28*(OCTET) | |
b31222cf SC |
583 | ---- |
584 | ||
585 | If the receiving end does not support delete-refs, the sending end MUST | |
586 | NOT ask for delete command. | |
587 | ||
4adf569d JH |
588 | If the receiving end does not support push-cert, the sending end |
589 | MUST NOT send a push-cert command. When a push-cert command is | |
590 | sent, command-list MUST NOT be sent; the commands recorded in the | |
591 | push certificate is used instead. | |
592 | ||
3890dae9 | 593 | The packfile MUST NOT be sent if the only command used is 'delete'. |
b31222cf | 594 | |
3890dae9 | 595 | A packfile MUST be sent if either create or update command is used, |
b31222cf | 596 | even if the server already has all the necessary objects. In this |
3890dae9 | 597 | case the client MUST send an empty packfile. The only time this |
b31222cf SC |
598 | is likely to happen is if the client is creating |
599 | a new branch or a tag that points to an existing obj-id. | |
600 | ||
601 | The server will receive the packfile, unpack it, then validate each | |
602 | reference that is being updated that it hasn't changed while the request | |
603 | was being processed (the obj-id is still the same as the old-id), and | |
604 | it will run any update hooks to make sure that the update is acceptable. | |
605 | If all of that is fine, the server will then update the references. | |
606 | ||
4adf569d JH |
607 | Push Certificate |
608 | ---------------- | |
609 | ||
610 | A push certificate begins with a set of header lines. After the | |
611 | header and an empty line, the protocol commands follow, one per | |
832c0e5e | 612 | line. Note that the trailing LF in push-cert PKT-LINEs is _not_ |
1c9b659d | 613 | optional; it must be present. |
4adf569d JH |
614 | |
615 | Currently, the following header fields are defined: | |
616 | ||
617 | `pusher` ident:: | |
618 | Identify the GPG key in "Human Readable Name <email@address>" | |
619 | format. | |
620 | ||
9be89160 JH |
621 | `pushee` url:: |
622 | The repository URL (anonymized, if the URL contains | |
623 | authentication material) the user who ran `git push` | |
624 | intended to push into. | |
625 | ||
b89363e4 JH |
626 | `nonce` nonce:: |
627 | The 'nonce' string the receiving repository asked the | |
628 | pushing user to include in the certificate, to prevent | |
629 | replay attacks. | |
630 | ||
4adf569d JH |
631 | The GPG signature lines are a detached signature for the contents |
632 | recorded in the push certificate before the signature block begins. | |
633 | The detached signature is used to certify that the commands were | |
634 | given by the pusher, who must be the signer. | |
635 | ||
b31222cf SC |
636 | Report Status |
637 | ------------- | |
638 | ||
639 | After receiving the pack data from the sender, the receiver sends a | |
b913075c | 640 | report if 'report-status' or 'report-status-v2' capability is in effect. |
b31222cf SC |
641 | It is a short listing of what happened in that update. It will first |
642 | list the status of the packfile unpacking as either 'unpack ok' or | |
643 | 'unpack [error]'. Then it will list the status for each of the references | |
644 | that it tried to update. Each line is either 'ok [refname]' if the | |
645 | update was successful, or 'ng [refname] [error]' if the update was not. | |
646 | ||
647 | ---- | |
648 | report-status = unpack-status | |
649 | 1*(command-status) | |
650 | flush-pkt | |
651 | ||
1c9b659d | 652 | unpack-status = PKT-LINE("unpack" SP unpack-result) |
b31222cf SC |
653 | unpack-result = "ok" / error-msg |
654 | ||
655 | command-status = command-ok / command-fail | |
1c9b659d JK |
656 | command-ok = PKT-LINE("ok" SP refname) |
657 | command-fail = PKT-LINE("ng" SP refname SP error-msg) | |
b31222cf | 658 | |
031fd4b9 | 659 | error-msg = 1*(OCTET) ; where not "ok" |
b31222cf SC |
660 | ---- |
661 | ||
b913075c JX |
662 | The 'report-status-v2' capability extends the protocol by adding new option |
663 | lines in order to support reporting of reference rewritten by the | |
664 | 'proc-receive' hook. The 'proc-receive' hook may handle a command for a | |
665 | pseudo-reference which may create or update one or more references, and each | |
666 | reference may have different name, different new-oid, and different old-oid. | |
667 | ||
668 | ---- | |
669 | report-status-v2 = unpack-status | |
670 | 1*(command-status-v2) | |
671 | flush-pkt | |
672 | ||
673 | unpack-status = PKT-LINE("unpack" SP unpack-result) | |
674 | unpack-result = "ok" / error-msg | |
675 | ||
676 | command-status-v2 = command-ok-v2 / command-fail | |
677 | command-ok-v2 = command-ok | |
678 | *option-line | |
679 | ||
680 | command-ok = PKT-LINE("ok" SP refname) | |
681 | command-fail = PKT-LINE("ng" SP refname SP error-msg) | |
682 | ||
683 | error-msg = 1*(OCTET) ; where not "ok" | |
684 | ||
685 | option-line = *1(option-refname) | |
686 | *1(option-old-oid) | |
687 | *1(option-new-oid) | |
688 | *1(option-forced-update) | |
689 | ||
690 | option-refname = PKT-LINE("option" SP "refname" SP refname) | |
691 | option-old-oid = PKT-LINE("option" SP "old-oid" SP obj-id) | |
692 | option-new-oid = PKT-LINE("option" SP "new-oid" SP obj-id) | |
693 | option-force = PKT-LINE("option" SP "forced-update") | |
694 | ||
695 | ---- | |
696 | ||
b31222cf SC |
697 | Updates can be unsuccessful for a number of reasons. The reference can have |
698 | changed since the reference discovery phase was originally sent, meaning | |
699 | someone pushed in the meantime. The reference being pushed could be a | |
700 | non-fast-forward reference and the update hooks or configuration could be | |
701 | set to not allow that, etc. Also, some references can be updated while others | |
702 | can be rejected. | |
703 | ||
704 | An example client/server communication might look like this: | |
705 | ||
706 | ---- | |
74cc547b | 707 | S: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n |
b31222cf SC |
708 | S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n |
709 | S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n | |
74cc547b | 710 | S: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n |
b31222cf SC |
711 | S: 0000 |
712 | ||
74cc547b MH |
713 | C: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n |
714 | C: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n | |
b31222cf SC |
715 | C: 0000 |
716 | C: [PACKDATA] | |
717 | ||
c8a97906 TRC |
718 | S: 000eunpack ok\n |
719 | S: 0018ok refs/heads/debug\n | |
720 | S: 002ang refs/heads/master non-fast-forward\n | |
b31222cf | 721 | ---- |
5db92105 ÆAB |
722 | |
723 | GIT | |
724 | --- | |
725 | Part of the linkgit:git[1] suite |