create HTML for http-protocol.txt
./Documentation/technical/http-protocol.txt was missing from TECH_DOCS in Makefile. Add it and also improve HTML formatting while still retaining good readability of the ASCII text: - Use monospace font instead of italicized or roman font for machine output and source text - Use roman font for things which should be body text - Use double quotes consistently for "want" and "have" commands - Use uppercase "C" / "S" consistently for "client" / "server"; also use "C:" / "S:" instead of "(C)" / "(S)" for consistency and to avoid having formatted "(C)" as copyright symbol in HTML - Use only spaces and not a combination of tabs and spaces for whitespace Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Ackermann committed
Jan 26, 2014 at 13:57 UTC
586aa7863141ad07fd6eb45349a3cb62fdcd28ea
2 files changed
+110
-105
Documentation/Makefile
+2
-1
@@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git
60
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
61
SP_ARTICLES += $(API_DOCS)
62
63
-TECH_DOCS = technical/index-format
63
+TECH_DOCS = technical/http-protocol
64
+TECH_DOCS += technical/index-format
65
TECH_DOCS += technical/pack-format
66
TECH_DOCS += technical/pack-heuristics
67
TECH_DOCS += technical/pack-protocol
Documentation/technical/http-protocol.txt
+108
-104
@@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the form:
20
21
http://<host>:<port>/<path>?<searchpart>
22
23
-Within this documentation the placeholder $GIT_URL will stand for
23
+Within this documentation the placeholder `$GIT_URL` will stand for
24
the http:// repository URL entered by the end-user.
25
26
-Servers SHOULD handle all requests to locations matching $GIT_URL, as
26
+Servers SHOULD handle all requests to locations matching `$GIT_URL`, as
27
both the "smart" and "dumb" HTTP protocols used by Git operate
28
by appending additional path components onto the end of the user
29
-supplied $GIT_URL string.
29
+supplied `$GIT_URL` string.
30
31
An example of a dumb client requesting for a loose object:
32
@@ -43,10 +43,10 @@ An example of a request to a submodule:
43
$GIT_URL: http://example.com/git/repo.git/path/submodule.git
44
URL request: http://example.com/git/repo.git/path/submodule.git/info/refs
45
46
-Clients MUST strip a trailing '/', if present, from the user supplied
47
-$GIT_URL string to prevent empty path tokens ('//') from appearing
46
+Clients MUST strip a trailing `/`, if present, from the user supplied
47
+`$GIT_URL` string to prevent empty path tokens (`//`) from appearing
48
in any URL sent to a server. Compatible clients MUST expand
49
-'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.
49
+`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.
50
51
52
Authentication
@@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD be assumed
103
by both client and server. This includes (but is not necessarily
104
limited to):
105
106
-If there is no repository at $GIT_URL, or the resource pointed to by a
107
-location matching $GIT_URL does not exist, the server MUST NOT respond
108
-with '200 OK' response. A server SHOULD respond with
109
-'404 Not Found', '410 Gone', or any other suitable HTTP status code
106
+If there is no repository at `$GIT_URL`, or the resource pointed to by a
107
+location matching `$GIT_URL` does not exist, the server MUST NOT respond
108
+with `200 OK` response. A server SHOULD respond with
109
+`404 Not Found`, `410 Gone`, or any other suitable HTTP status code
110
which does not imply the resource exists as requested.
111
112
-If there is a repository at $GIT_URL, but access is not currently
113
-permitted, the server MUST respond with the '403 Forbidden' HTTP
112
+If there is a repository at `$GIT_URL`, but access is not currently
113
+permitted, the server MUST respond with the `403 Forbidden` HTTP
114
status code.
115
116
Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
@@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.
126
Clients MAY revalidate cached entities by including If-Modified-Since
127
and/or If-None-Match request headers.
128
129
-Servers MAY return '304 Not Modified' if the relevant headers appear
129
+Servers MAY return `304 Not Modified` if the relevant headers appear
130
in the request and the entity has not changed. Clients MUST treat
131
-'304 Not Modified' identical to '200 OK' by reusing the cached entity.
131
+`304 Not Modified` identical to `200 OK` by reusing the cached entity.
132
133
Clients MAY reuse a cached entity without revalidation if the
134
Cache-Control and/or Expires header permits caching. Clients and
@@ -148,7 +148,7 @@ HTTP clients that only support the "dumb" protocol MUST discover
148
references by making a request for the special info/refs file of
149
the repository.
150
151
-Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,
151
+Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,
152
without any search/query parameters.
153
154
C: GET $GIT_URL/info/refs HTTP/1.0
@@ -161,21 +161,21 @@ without any search/query parameters.
161
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
162
163
The Content-Type of the returned info/refs entity SHOULD be
164
-"text/plain; charset=utf-8", but MAY be any content type.
164
+`text/plain; charset=utf-8`, but MAY be any content type.
165
Clients MUST NOT attempt to validate the returned Content-Type.
166
Dumb servers MUST NOT return a return type starting with
167
-"application/x-git-".
167
+`application/x-git-`.
168
169
Cache-Control headers MAY be returned to disable caching of the
170
returned entity.
171
172
When examining the response clients SHOULD only examine the HTTP
173
-status code. Valid responses are '200 OK', or '304 Not Modified'.
173
+status code. Valid responses are `200 OK`, or `304 Not Modified`.
174
175
The returned content is a UNIX formatted text file describing
176
each ref and its known value. The file SHOULD be sorted by name
177
according to the C locale ordering. The file SHOULD NOT include
178
-the default ref named 'HEAD'.
178
+the default ref named `HEAD`.
179
180
info_refs = *( ref_record )
181
ref_record = any_ref / peeled_ref
@@ -192,13 +192,14 @@ HTTP clients that support the "smart" protocol (or both the
192
a parameterized request for the info/refs file of the repository.
193
194
The request MUST contain exactly one query parameter,
195
-'service=$servicename', where $servicename MUST be the service
195
+`service=$servicename`, where `$servicename` MUST be the service
196
name the client wishes to contact to complete the operation.
197
The request MUST NOT contain additional query parameters.
198
199
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
200
201
- dumb server reply:
201
+dumb server reply:
202
+
203
S: 200 OK
204
S:
205
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
@@ -206,7 +207,8 @@ The request MUST NOT contain additional query parameters.
207
S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
208
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
209
209
- smart server reply:
210
+smart server reply:
211
+
212
S: 200 OK
213
S: Content-Type: application/x-git-upload-pack-advertisement
214
S: Cache-Control: no-cache
@@ -228,7 +230,7 @@ Smart Server Response
230
^^^^^^^^^^^^^^^^^^^^^
231
If the server does not recognize the requested service name, or the
232
requested service name has been disabled by the server administrator,
231
-the server MUST respond with the '403 Forbidden' HTTP status code.
233
+the server MUST respond with the `403 Forbidden` HTTP status code.
234
235
Otherwise, smart servers MUST respond with the smart server reply
236
format for the requested service name.
@@ -236,35 +238,35 @@ format for the requested service name.
238
Cache-Control headers SHOULD be used to disable caching of the
239
returned entity.
240
239
-The Content-Type MUST be 'application/x-$servicename-advertisement'.
241
+The Content-Type MUST be `application/x-$servicename-advertisement`.
242
Clients SHOULD fall back to the dumb protocol if another content
243
type is returned. When falling back to the dumb protocol clients
242
-SHOULD NOT make an additional request to $GIT_URL/info/refs, but
244
+SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but
245
instead SHOULD use the response already in hand. Clients MUST NOT
246
continue if they do not support the dumb protocol.
247
246
-Clients MUST validate the status code is either '200 OK' or
247
-'304 Not Modified'.
248
+Clients MUST validate the status code is either `200 OK` or
249
+`304 Not Modified`.
250
251
Clients MUST validate the first five bytes of the response entity
250
-matches the regex "^[0-9a-f]{4}#". If this test fails, clients
252
+matches the regex `^[0-9a-f]{4}#`. If this test fails, clients
253
MUST NOT continue.
254
255
Clients MUST parse the entire response as a sequence of pkt-line
256
records.
257
256
-Clients MUST verify the first pkt-line is "# service=$servicename".
258
+Clients MUST verify the first pkt-line is `# service=$servicename`.
259
Servers MUST set $servicename to be the request parameter value.
260
Servers SHOULD include an LF at the end of this line.
261
Clients MUST ignore an LF at the end of the line.
262
261
-Servers MUST terminate the response with the magic "0000" end
263
+Servers MUST terminate the response with the magic `0000` end
264
pkt-line marker.
265
266
The returned response is a pkt-line stream describing each ref and
267
its known value. The stream SHOULD be sorted by name according to
268
the C locale ordering. The stream SHOULD include the default ref
267
-named 'HEAD' as the first ref. The stream MUST include capability
269
+named `HEAD` as the first ref. The stream MUST include capability
270
declarations behind a NUL on the first ref.
271
272
smart_reply = PKT-LINE("# service=$servicename" LF)
@@ -286,12 +288,13 @@ declarations behind a NUL on the first ref.
288
peeled_ref = PKT-LINE(obj-id SP name LF)
289
PKT-LINE(obj-id SP name "^{}" LF
290
291
+
292
Smart Service git-upload-pack
293
------------------------------
291
-This service reads from the repository pointed to by $GIT_URL.
294
+This service reads from the repository pointed to by `$GIT_URL`.
295
296
Clients MUST first perform ref discovery with
294
-'$GIT_URL/info/refs?service=git-upload-pack'.
297
+`$GIT_URL/info/refs?service=git-upload-pack`.
298
299
C: POST $GIT_URL/git-upload-pack HTTP/1.0
300
C: Content-Type: application/x-git-upload-pack-request
@@ -313,10 +316,10 @@ to prevent caching of the response.
316
317
Servers SHOULD support all capabilities defined here.
318
316
-Clients MUST send at least one 'want' command in the request body.
317
-Clients MUST NOT reference an id in a 'want' command which did not
319
+Clients MUST send at least one "want" command in the request body.
320
+Clients MUST NOT reference an id in a "want" command which did not
321
appear in the response obtained through ref discovery unless the
319
-server advertises capability "allow-tip-sha1-in-want".
322
+server advertises capability `allow-tip-sha1-in-want`.
323
324
compute_request = want_list
325
have_list
@@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.
340
The Negotiation Algorithm
341
~~~~~~~~~~~~~~~~~~~~~~~~~
342
The computation to select the minimal pack proceeds as follows
340
-(c = client, s = server):
343
+(C = client, S = server):
344
+
345
+'init step:'
346
+
347
+C: Use ref discovery to obtain the advertised refs.
348
+
349
+C: Place any object seen into set ADVERTISED.
350
342
- init step:
343
- (c) Use ref discovery to obtain the advertised refs.
344
- (c) Place any object seen into set ADVERTISED.
351
+C: Build an empty set, COMMON, to hold the objects that are later
352
+ determined to be on both ends.
353
346
- (c) Build an empty set, COMMON, to hold the objects that are later
347
- determined to be on both ends.
348
- (c) Build a set, WANT, of the objects from ADVERTISED the client
349
- wants to fetch, based on what it saw during ref discovery.
354
+C: Build a set, WANT, of the objects from ADVERTISED the client
355
+ wants to fetch, based on what it saw during ref discovery.
356
351
- (c) Start a queue, C_PENDING, ordered by commit time (popping newest
352
- first). Add all client refs. When a commit is popped from
353
- the queue its parents SHOULD be automatically inserted back.
354
- Commits MUST only enter the queue once.
357
+C: Start a queue, C_PENDING, ordered by commit time (popping newest
358
+ first). Add all client refs. When a commit is popped from
359
+ the queue its parents SHOULD be automatically inserted back.
360
+ Commits MUST only enter the queue once.
361
356
- one compute step:
357
- (c) Send one $GIT_URL/git-upload-pack request:
362
+'one compute step:'
363
+
364
+C: Send one `$GIT_URL/git-upload-pack` request:
365
366
C: 0032want <WANT #1>...............................
367
C: 0032want <WANT #2>...............................
@@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as follows
374
....
375
C: 0000
376
370
- The stream is organized into "commands", with each command
371
- appearing by itself in a pkt-line. Within a command line
372
- the text leading up to the first space is the command name,
373
- and the remainder of the line to the first LF is the value.
374
- Command lines are terminated with an LF as the last byte of
375
- the pkt-line value.
377
+The stream is organized into "commands", with each command
378
+appearing by itself in a pkt-line. Within a command line
379
+the text leading up to the first space is the command name,
380
+and the remainder of the line to the first LF is the value.
381
+Command lines are terminated with an LF as the last byte of
382
+the pkt-line value.
383
377
- Commands MUST appear in the following order, if they appear
378
- at all in the request stream:
384
+Commands MUST appear in the following order, if they appear
385
+at all in the request stream:
386
380
- * want
381
- * have
387
+* "want"
388
+* "have"
389
383
- The stream is terminated by a pkt-line flush ("0000").
390
+The stream is terminated by a pkt-line flush (`0000`).
391
385
- A single "want" or "have" command MUST have one hex formatted
386
- SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
387
- multiple commands.
392
+A single "want" or "have" command MUST have one hex formatted
393
+SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
394
+multiple commands.
395
389
- The HAVE list is created by popping the first 32 commits
390
- from C_PENDING. Less can be supplied if C_PENDING empties.
396
+The HAVE list is created by popping the first 32 commits
397
+from C_PENDING. Less can be supplied if C_PENDING empties.
398
392
- If the client has sent 256 HAVE commits and has not yet
393
- received one of those back from S_COMMON, or the client has
394
- emptied C_PENDING it SHOULD include a "done" command to let
395
- the server know it won't proceed:
399
+If the client has sent 256 HAVE commits and has not yet
400
+received one of those back from S_COMMON, or the client has
401
+emptied C_PENDING it SHOULD include a "done" command to let
402
+the server know it won't proceed:
403
404
C: 0009done
405
399
- (s) Parse the git-upload-pack request:
400
-
401
- Verify all objects in WANT are directly reachable from refs.
402
-
403
- The server MAY walk backwards through history or through
404
- the reflog to permit slightly stale requests.
406
+S: Parse the git-upload-pack request:
407
406
- If no WANT objects are received, send an error:
408
+Verify all objects in WANT are directly reachable from refs.
409
408
-TODO: Define error if no want lines are requested.
410
+The server MAY walk backwards through history or through
411
+the reflog to permit slightly stale requests.
412
410
- If any WANT object is not reachable, send an error:
413
+If no WANT objects are received, send an error:
414
+TODO: Define error if no "want" lines are requested.
415
412
-TODO: Define error if an invalid want is requested.
416
+If any WANT object is not reachable, send an error:
417
+TODO: Define error if an invalid "want" is requested.
418
414
- Create an empty list, S_COMMON.
419
+Create an empty list, S_COMMON.
420
416
- If 'have' was sent:
421
+If "have" was sent:
422
418
- Loop through the objects in the order supplied by the client.
419
- For each object, if the server has the object reachable from
420
- a ref, add it to S_COMMON. If a commit is added to S_COMMON,
421
- do not add any ancestors, even if they also appear in HAVE.
423
+Loop through the objects in the order supplied by the client.
424
423
- (s) Send the git-upload-pack response:
425
+For each object, if the server has the object reachable from
426
+a ref, add it to S_COMMON. If a commit is added to S_COMMON,
427
+do not add any ancestors, even if they also appear in HAVE.
428
425
- If the server has found a closed set of objects to pack or the
426
- request ends with "done", it replies with the pack.
429
+S: Send the git-upload-pack response:
430
431
+If the server has found a closed set of objects to pack or the
432
+request ends with "done", it replies with the pack.
433
TODO: Document the pack based response
429
- S: PACK...
434
431
- The returned stream is the side-band-64k protocol supported
432
- by the git-upload-pack service, and the pack is embedded into
433
- stream 1. Progress messages from the server side MAY appear
434
- in stream 2.
435
+ S: PACK...
436
436
- Here a "closed set of objects" is defined to have at least
437
- one path from every WANT to at least one COMMON object.
437
+The returned stream is the side-band-64k protocol supported
438
+by the git-upload-pack service, and the pack is embedded into
439
+stream 1. Progress messages from the server side MAY appear
440
+in stream 2.
441
439
- If the server needs more information, it replies with a
440
- status continue response:
442
+Here a "closed set of objects" is defined to have at least
443
+one path from every WANT to at least one COMMON object.
444
445
+If the server needs more information, it replies with a
446
+status continue response:
447
TODO: Document the non-pack response
448
444
- (c) Parse the upload-pack response:
445
-
446
-TODO: Document parsing response
449
+C: Parse the upload-pack response:
450
+ TODO: Document parsing response
451
448
- Do another compute step.
452
+'Do another compute step.'
453
454
455
Smart Service git-receive-pack
456
------------------------------
453
-This service reads from the repository pointed to by $GIT_URL.
457
+This service reads from the repository pointed to by `$GIT_URL`.
458
459
Clients MUST first perform ref discovery with
456
-'$GIT_URL/info/refs?service=git-receive-pack'.
460
+`$GIT_URL/info/refs?service=git-receive-pack`.
461
462
C: POST $GIT_URL/git-receive-pack HTTP/1.0
463
C: Content-Type: application/x-git-receive-pack-request