1GITPROTOCOL-HTTP(5)               Git Manual               GITPROTOCOL-HTTP(5)
2
3
4

NAME

6       gitprotocol-http - Git HTTP-based protocols
7

SYNOPSIS

9       <over-the-wire-protocol>
10

DESCRIPTION

12       Git supports two HTTP based transfer protocols. A "dumb" protocol which
13       requires only a standard HTTP server on the server end of the
14       connection, and a "smart" protocol which requires a Git aware CGI (or
15       server module). This document describes both protocols.
16
17       As a design feature smart clients can automatically upgrade "dumb"
18       protocol URLs to smart URLs. This permits all users to have the same
19       published URL, and the peers automatically select the most efficient
20       transport available to them.
21

URL FORMAT

23       URLs for Git repositories accessed by HTTP use the standard HTTP URL
24       syntax documented by RFC 1738, so they are of the form:
25
26           http://<host>:<port>/<path>?<searchpart>
27
28       Within this documentation the placeholder $GIT_URL will stand for the
29       http:// repository URL entered by the end-user.
30
31       Servers SHOULD handle all requests to locations matching $GIT_URL, as
32       both the "smart" and "dumb" HTTP protocols used by Git operate by
33       appending additional path components onto the end of the user supplied
34       $GIT_URL string.
35
36       An example of a dumb client requesting a loose object:
37
38           $GIT_URL:     http://example.com:8080/git/repo.git
39           URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
40
41       An example of a smart request to a catch-all gateway:
42
43           $GIT_URL:     http://example.com/daemon.cgi?svc=git&q=
44           URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack
45
46       An example of a request to a submodule:
47
48           $GIT_URL:     http://example.com/git/repo.git/path/submodule.git
49           URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs
50
51       Clients MUST strip a trailing /, if present, from the user supplied
52       $GIT_URL string to prevent empty path tokens (//) from appearing in any
53       URL sent to a server. Compatible clients MUST expand $GIT_URL/info/refs
54       as foo/info/refs and not foo//info/refs.
55

AUTHENTICATION

57       Standard HTTP authentication is used if authentication is required to
58       access a repository, and MAY be configured and enforced by the HTTP
59       server software.
60
61       Because Git repositories are accessed by standard path components
62       server administrators MAY use directory based permissions within their
63       HTTP server to control repository access.
64
65       Clients SHOULD support Basic authentication as described by RFC 2617.
66       Servers SHOULD support Basic authentication by relying upon the HTTP
67       server placed in front of the Git server software.
68
69       Servers SHOULD NOT require HTTP cookies for the purposes of
70       authentication or access control.
71
72       Clients and servers MAY support other common forms of HTTP based
73       authentication, such as Digest authentication.
74

SSL

76       Clients and servers SHOULD support SSL, particularly to protect
77       passwords when relying on Basic HTTP authentication.
78

SESSION STATE

80       The Git over HTTP protocol (much like HTTP itself) is stateless from
81       the perspective of the HTTP server side. All state MUST be retained and
82       managed by the client process. This permits simple round-robin
83       load-balancing on the server side, without needing to worry about state
84       management.
85
86       Clients MUST NOT require state management on the server side in order
87       to function correctly.
88
89       Servers MUST NOT require HTTP cookies in order to function correctly.
90       Clients MAY store and forward HTTP cookies during request processing as
91       described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any cookies
92       sent by a client.
93

GENERAL REQUEST PROCESSING

95       Except where noted, all standard HTTP behavior SHOULD be assumed by
96       both client and server. This includes (but is not necessarily limited
97       to):
98
99       If there is no repository at $GIT_URL, or the resource pointed to by a
100       location matching $GIT_URL does not exist, the server MUST NOT respond
101       with 200 OK response. A server SHOULD respond with 404 Not Found, 410
102       Gone, or any other suitable HTTP status code which does not imply the
103       resource exists as requested.
104
105       If there is a repository at $GIT_URL, but access is not currently
106       permitted, the server MUST respond with the 403 Forbidden HTTP status
107       code.
108
109       Servers SHOULD support both HTTP 1.0 and HTTP 1.1. Servers SHOULD
110       support chunked encoding for both request and response bodies.
111
112       Clients SHOULD support both HTTP 1.0 and HTTP 1.1. Clients SHOULD
113       support chunked encoding for both request and response bodies.
114
115       Servers MAY return ETag and/or Last-Modified headers.
116
117       Clients MAY revalidate cached entities by including If-Modified-Since
118       and/or If-None-Match request headers.
119
120       Servers MAY return 304 Not Modified if the relevant headers appear in
121       the request and the entity has not changed. Clients MUST treat 304 Not
122       Modified identical to 200 OK by reusing the cached entity.
123
124       Clients MAY reuse a cached entity without revalidation if the
125       Cache-Control and/or Expires header permits caching. Clients and
126       servers MUST follow RFC 2616 for cache controls.
127

DISCOVERING REFERENCES

129       All HTTP clients MUST begin either a fetch or a push exchange by
130       discovering the references available on the remote repository.
131
132   Dumb Clients
133       HTTP clients that only support the "dumb" protocol MUST discover
134       references by making a request for the special info/refs file of the
135       repository.
136
137       Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,
138       without any search/query parameters.
139
140           C: GET $GIT_URL/info/refs HTTP/1.0
141
142           S: 200 OK
143           S:
144           S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
145           S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
146           S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
147           S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
148
149       The Content-Type of the returned info/refs entity SHOULD be text/plain;
150       charset=utf-8, but MAY be any content type. Clients MUST NOT attempt to
151       validate the returned Content-Type. Dumb servers MUST NOT return a
152       return type starting with application/x-git-.
153
154       Cache-Control headers MAY be returned to disable caching of the
155       returned entity.
156
157       When examining the response clients SHOULD only examine the HTTP status
158       code. Valid responses are 200 OK, or 304 Not Modified.
159
160       The returned content is a UNIX formatted text file describing each ref
161       and its known value. The file SHOULD be sorted by name according to the
162       C locale ordering. The file SHOULD NOT include the default ref named
163       HEAD.
164
165           info_refs   =  *( ref_record )
166           ref_record  =  any_ref / peeled_ref
167
168           any_ref     =  obj-id HTAB refname LF
169           peeled_ref  =  obj-id HTAB refname LF
170            obj-id HTAB refname "^{}" LF
171
172   Smart Clients
173       HTTP clients that support the "smart" protocol (or both the "smart" and
174       "dumb" protocols) MUST discover references by making a parameterized
175       request for the info/refs file of the repository.
176
177       The request MUST contain exactly one query parameter,
178       service=$servicename, where $servicename MUST be the service name the
179       client wishes to contact to complete the operation. The request MUST
180       NOT contain additional query parameters.
181
182           C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
183
184       dumb server reply:
185
186           S: 200 OK
187           S:
188           S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
189           S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
190           S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
191           S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
192
193       smart server reply:
194
195           S: 200 OK
196           S: Content-Type: application/x-git-upload-pack-advertisement
197           S: Cache-Control: no-cache
198           S:
199           S: 001e# service=git-upload-pack\n
200           S: 0000
201           S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
202           S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
203           S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
204           S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
205           S: 0000
206
207       The client may send Extra Parameters (see gitprotocol-pack(5)) as a
208       colon-separated string in the Git-Protocol HTTP header.
209
210       Uses the --http-backend-info-refs option to git-upload-pack(1).
211
212       Dumb Server Response
213           Dumb servers MUST respond with the dumb server reply format.
214
215           See the prior section under dumb clients for a more detailed
216           description of the dumb server response.
217
218       Smart Server Response
219           If the server does not recognize the requested service name, or the
220           requested service name has been disabled by the server
221           administrator, the server MUST respond with the 403 Forbidden HTTP
222           status code.
223
224           Otherwise, smart servers MUST respond with the smart server reply
225           format for the requested service name.
226
227           Cache-Control headers SHOULD be used to disable caching of the
228           returned entity.
229
230           The Content-Type MUST be application/x-$servicename-advertisement.
231           Clients SHOULD fall back to the dumb protocol if another content
232           type is returned. When falling back to the dumb protocol clients
233           SHOULD NOT make an additional request to $GIT_URL/info/refs, but
234           instead SHOULD use the response already in hand. Clients MUST NOT
235           continue if they do not support the dumb protocol.
236
237           Clients MUST validate the status code is either 200 OK or 304 Not
238           Modified.
239
240           Clients MUST validate the first five bytes of the response entity
241           matches the regex ^[0-9a-f]{4}#. If this test fails, clients MUST
242           NOT continue.
243
244           Clients MUST parse the entire response as a sequence of pkt-line
245           records.
246
247           Clients MUST verify the first pkt-line is # service=$servicename.
248           Servers MUST set $servicename to be the request parameter value.
249           Servers SHOULD include an LF at the end of this line. Clients MUST
250           ignore an LF at the end of the line.
251
252           Servers MUST terminate the response with the magic 0000 end
253           pkt-line marker.
254
255           The returned response is a pkt-line stream describing each ref and
256           its known value. The stream SHOULD be sorted by name according to
257           the C locale ordering. The stream SHOULD include the default ref
258           named HEAD as the first ref. The stream MUST include capability
259           declarations behind a NUL on the first ref.
260
261           The returned response contains "version 1" if "version=1" was sent
262           as an Extra Parameter.
263
264               smart_reply     =  PKT-LINE("# service=$servicename" LF)
265                    "0000"
266                    *1("version 1")
267                    ref_list
268                    "0000"
269               ref_list        =  empty_list / non_empty_list
270
271               empty_list      =  PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
272
273               non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)
274                    *ref_record
275
276               cap-list        =  capability *(SP capability)
277               capability      =  1*(LC_ALPHA / DIGIT / "-" / "_")
278               LC_ALPHA        =  %x61-7A
279
280               ref_record      =  any_ref / peeled_ref
281               any_ref         =  PKT-LINE(obj-id SP name LF)
282               peeled_ref      =  PKT-LINE(obj-id SP name LF)
283                    PKT-LINE(obj-id SP name "^{}" LF
284

SMART SERVICE GIT-UPLOAD-PACK

286       This service reads from the repository pointed to by $GIT_URL.
287
288       Clients MUST first perform ref discovery with
289       $GIT_URL/info/refs?service=git-upload-pack.
290
291           C: POST $GIT_URL/git-upload-pack HTTP/1.0
292           C: Content-Type: application/x-git-upload-pack-request
293           C:
294           C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
295           C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
296           C: 0000
297
298           S: 200 OK
299           S: Content-Type: application/x-git-upload-pack-result
300           S: Cache-Control: no-cache
301           S:
302           S: ....ACK %s, continue
303           S: ....NAK
304
305       Clients MUST NOT reuse or revalidate a cached response. Servers MUST
306       include sufficient Cache-Control headers to prevent caching of the
307       response.
308
309       Servers SHOULD support all capabilities defined here.
310
311       Clients MUST send at least one "want" command in the request body.
312       Clients MUST NOT reference an id in a "want" command which did not
313       appear in the response obtained through ref discovery unless the server
314       advertises capability allow-tip-sha1-in-want or
315       allow-reachable-sha1-in-want.
316
317           compute_request   =  want_list
318                  have_list
319                  request_end
320           request_end       =  "0000" / "done"
321
322           want_list         =  PKT-LINE(want SP cap_list LF)
323                  *(want_pkt)
324           want_pkt          =  PKT-LINE(want LF)
325           want              =  "want" SP id
326           cap_list          =  capability *(SP capability)
327
328           have_list         =  *PKT-LINE("have" SP id LF)
329
330       TODO: Document this further.
331
332   The Negotiation Algorithm
333       The computation to select the minimal pack proceeds as follows (C =
334       client, S = server):
335
336       init step:
337
338       C: Use ref discovery to obtain the advertised refs.
339
340       C: Place any object seen into set advertised.
341
342       C: Build an empty set, common, to hold the objects that are later
343       determined to be on both ends.
344
345       C: Build a set, want, of the objects from advertised that the client
346       wants to fetch, based on what it saw during ref discovery.
347
348       C: Start a queue, c_pending, ordered by commit time (popping newest
349       first). Add all client refs. When a commit is popped from the queue its
350       parents SHOULD be automatically inserted back. Commits MUST only enter
351       the queue once.
352
353       one compute step:
354
355       C: Send one $GIT_URL/git-upload-pack request:
356
357           C: 0032want <want #1>...............................
358           C: 0032want <want #2>...............................
359           ....
360           C: 0032have <common #1>.............................
361           C: 0032have <common #2>.............................
362           ....
363           C: 0032have <have #1>...............................
364           C: 0032have <have #2>...............................
365           ....
366           C: 0000
367
368       The stream is organized into "commands", with each command appearing by
369       itself in a pkt-line. Within a command line, the text leading up to the
370       first space is the command name, and the remainder of the line to the
371       first LF is the value. Command lines are terminated with an LF as the
372       last byte of the pkt-line value.
373
374       Commands MUST appear in the following order, if they appear at all in
375       the request stream:
376
377       •   "want"
378
379       •   "have"
380
381       The stream is terminated by a pkt-line flush (0000).
382
383       A single "want" or "have" command MUST have one hex formatted object
384       name as its value. Multiple object names MUST be sent by sending
385       multiple commands. Object names MUST be given using the object format
386       negotiated through the object-format capability (default SHA-1).
387
388       The have list is created by popping the first 32 commits from
389       c_pending. Fewer can be supplied if c_pending empties.
390
391       If the client has sent 256 "have" commits and has not yet received one
392       of those back from s_common, or the client has emptied c_pending it
393       SHOULD include a "done" command to let the server know it won’t
394       proceed:
395
396           C: 0009done
397
398       S: Parse the git-upload-pack request:
399
400       Verify all objects in want are directly reachable from refs.
401
402       The server MAY walk backwards through history or through the reflog to
403       permit slightly stale requests.
404
405       If no "want" objects are received, send an error: TODO: Define error if
406       no "want" lines are requested.
407
408       If any "want" object is not reachable, send an error: TODO: Define
409       error if an invalid "want" is requested.
410
411       Create an empty list, s_common.
412
413       If "have" was sent:
414
415       Loop through the objects in the order supplied by the client.
416
417       For each object, if the server has the object reachable from a ref, add
418       it to s_common. If a commit is added to s_common, do not add any
419       ancestors, even if they also appear in have.
420
421       S: Send the git-upload-pack response:
422
423       If the server has found a closed set of objects to pack or the request
424       ends with "done", it replies with the pack. TODO: Document the pack
425       based response
426
427           S: PACK...
428
429       The returned stream is the side-band-64k protocol supported by the
430       git-upload-pack service, and the pack is embedded into stream 1.
431       Progress messages from the server side MAY appear in stream 2.
432
433       Here a "closed set of objects" is defined to have at least one path
434       from every "want" to at least one "common" object.
435
436       If the server needs more information, it replies with a status continue
437       response: TODO: Document the non-pack response
438
439       C: Parse the upload-pack response: TODO: Document parsing response
440
441       Do another compute step.
442

SMART SERVICE GIT-RECEIVE-PACK

444       This service reads from the repository pointed to by $GIT_URL.
445
446       Clients MUST first perform ref discovery with
447       $GIT_URL/info/refs?service=git-receive-pack.
448
449           C: POST $GIT_URL/git-receive-pack HTTP/1.0
450           C: Content-Type: application/x-git-receive-pack-request
451           C:
452           C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
453           C: 0000
454           C: PACK....
455
456           S: 200 OK
457           S: Content-Type: application/x-git-receive-pack-result
458           S: Cache-Control: no-cache
459           S:
460           S: ....
461
462       Clients MUST NOT reuse or revalidate a cached response. Servers MUST
463       include sufficient Cache-Control headers to prevent caching of the
464       response.
465
466       Servers SHOULD support all capabilities defined here.
467
468       Clients MUST send at least one command in the request body. Within the
469       command portion of the request body clients SHOULD send the id obtained
470       through ref discovery as old_id.
471
472           update_request  =  command_list
473                "PACK" <binary data>
474
475           command_list    =  PKT-LINE(command NUL cap_list LF)
476                *(command_pkt)
477           command_pkt     =  PKT-LINE(command LF)
478           cap_list        =  *(SP capability) SP
479
480           command         =  create / delete / update
481           create          =  zero-id SP new_id SP name
482           delete          =  old_id SP zero-id SP name
483           update          =  old_id SP new_id SP name
484
485       TODO: Document this further.
486

REFERENCES

488       RFC 1738: Uniform Resource Locators (URL)[1] RFC 2616: Hypertext
489       Transfer Protocol — HTTP/1.1[2]
490

SEE ALSO

492       gitprotocol-pack(5) gitprotocol-capabilities(5)
493

GIT

495       Part of the git(1) suite
496

NOTES

498        1. RFC 1738: Uniform Resource Locators (URL)
499           http://www.ietf.org/rfc/rfc1738.txt
500
501        2. RFC 2616: Hypertext Transfer Protocol — HTTP/1.1
502           http://www.ietf.org/rfc/rfc2616.txt
503
504
505
506Git 2.43.0                        11/20/2023               GITPROTOCOL-HTTP(5)
Impressum