* [PATCH 1/2] create HTML for http-protocol.txt
2014-01-26 12:52 [PATCH v2 0/2] create HTML for http-protocol.txt Thomas Ackermann
@ 2014-01-26 12:54 ` Thomas Ackermann
2014-01-26 13:01 ` Aw: " Thomas Ackermann
2014-01-26 12:56 ` [PATCH 2/2] http-protocol.txt: don't use uppercase for variable names in "The Negotiation Algorithm" Thomas Ackermann
2014-01-26 12:57 ` [PATCH 1/2] create HTML for http-protocol.txt Thomas Ackermann
2 siblings, 1 reply; 5+ messages in thread
From: Thomas Ackermann @ 2014-01-26 12:54 UTC (permalink / raw)
To: git; +Cc: gitster, spearce, th.acker
[PATCH 1/2] 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>
---
Documentation/Makefile | 3 +-
Documentation/technical/http-protocol.txt | 232 +++++++++++++++---------------
2 files changed, 120 insertions(+), 115 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36c58fc..b19d52a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
SP_ARTICLES += $(API_DOCS)
-TECH_DOCS = technical/index-format
+TECH_DOCS = technical/http-protocol
+TECH_DOCS += technical/index-format
TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
TECH_DOCS += technical/pack-protocol
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index d21d77d..7f0cf0b 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the form:
http://<host>:<port>/<path>?<searchpart>
-Within this documentation the placeholder $GIT_URL will stand for
+Within this documentation the placeholder `$GIT_URL` will stand for
the http:// repository URL entered by the end-user.
-Servers SHOULD handle all requests to locations matching $GIT_URL, as
+Servers SHOULD handle all requests to locations matching `$GIT_URL`, as
both the "smart" and "dumb" HTTP protocols used by Git operate
by appending additional path components onto the end of the user
-supplied $GIT_URL string.
+supplied `$GIT_URL` string.
An example of a dumb client requesting for a loose object:
@@ -43,10 +43,10 @@ An example of a request to a submodule:
$GIT_URL: http://example.com/git/repo.git/path/submodule.git
URL request: http://example.com/git/repo.git/path/submodule.git/info/refs
-Clients MUST strip a trailing '/', if present, from the user supplied
-$GIT_URL string to prevent empty path tokens ('//') from appearing
+Clients MUST strip a trailing `/`, if present, from the user supplied
+`$GIT_URL` string to prevent empty path tokens (`//`) from appearing
in any URL sent to a server. Compatible clients MUST expand
-'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.
+`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.
Authentication
@@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD be assumed
by both client and server. This includes (but is not necessarily
limited to):
-If there is no repository at $GIT_URL, or the resource pointed to by a
-location matching $GIT_URL does not exist, the server MUST NOT respond
-with '200 OK' response. A server SHOULD respond with
-'404 Not Found', '410 Gone', or any other suitable HTTP status code
+If there is no repository at `$GIT_URL`, or the resource pointed to by a
+location matching `$GIT_URL` does not exist, the server MUST NOT respond
+with `200 OK` response. A server SHOULD respond with
+`404 Not Found`, `410 Gone`, or any other suitable HTTP status code
which does not imply the resource exists as requested.
-If there is a repository at $GIT_URL, but access is not currently
-permitted, the server MUST respond with the '403 Forbidden' HTTP
+If there is a repository at `$GIT_URL`, but access is not currently
+permitted, the server MUST respond with the `403 Forbidden` HTTP
status code.
Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
@@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.
Clients MAY revalidate cached entities by including If-Modified-Since
and/or If-None-Match request headers.
-Servers MAY return '304 Not Modified' if the relevant headers appear
+Servers MAY return `304 Not Modified` if the relevant headers appear
in the request and the entity has not changed. Clients MUST treat
-'304 Not Modified' identical to '200 OK' by reusing the cached entity.
+`304 Not Modified` identical to `200 OK` by reusing the cached entity.
Clients MAY reuse a cached entity without revalidation if the
Cache-Control and/or Expires header permits caching. Clients and
@@ -148,7 +148,7 @@ HTTP clients that only support the "dumb" protocol MUST discover
references by making a request for the special info/refs file of
the repository.
-Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,
+Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,
without any search/query parameters.
C: GET $GIT_URL/info/refs HTTP/1.0
@@ -161,28 +161,28 @@ without any search/query parameters.
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
The Content-Type of the returned info/refs entity SHOULD be
-"text/plain; charset=utf-8", but MAY be any content type.
+`text/plain; charset=utf-8`, but MAY be any content type.
Clients MUST NOT attempt to validate the returned Content-Type.
Dumb servers MUST NOT return a return type starting with
-"application/x-git-".
+`application/x-git-`.
Cache-Control headers MAY be returned to disable caching of the
returned entity.
When examining the response clients SHOULD only examine the HTTP
-status code. Valid responses are '200 OK', or '304 Not Modified'.
+status code. Valid responses are `200 OK`, or `304 Not Modified`.
The returned content is a UNIX formatted text file describing
each ref and its known value. The file SHOULD be sorted by name
according to the C locale ordering. The file SHOULD NOT include
-the default ref named 'HEAD'.
+the default ref named `HEAD`.
info_refs = *( ref_record )
ref_record = any_ref / peeled_ref
any_ref = obj-id HTAB refname LF
peeled_ref = obj-id HTAB refname LF
- obj-id HTAB refname "^{}" LF
+ obj-id HTAB refname "^{}" LF
Smart Clients
~~~~~~~~~~~~~
@@ -192,13 +192,14 @@ HTTP clients that support the "smart" protocol (or both the
a parameterized request for the info/refs file of the repository.
The request MUST contain exactly one query parameter,
-'service=$servicename', where $servicename MUST be the service
+`service=$servicename`, where `$servicename` MUST be the service
name the client wishes to contact to complete the operation.
The request MUST NOT contain additional query parameters.
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
- dumb server reply:
+dumb server reply:
+
S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
@@ -206,7 +207,8 @@ The request MUST NOT contain additional query parameters.
S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
- smart server reply:
+smart server reply:
+
S: 200 OK
S: Content-Type: application/x-git-upload-pack-advertisement
S: Cache-Control: no-cache
@@ -228,7 +230,7 @@ Smart Server Response
^^^^^^^^^^^^^^^^^^^^^
If the server does not recognize the requested service name, or the
requested service name has been disabled by the server administrator,
-the server MUST respond with the '403 Forbidden' HTTP status code.
+the server MUST respond with the `403 Forbidden` HTTP status code.
Otherwise, smart servers MUST respond with the smart server reply
format for the requested service name.
@@ -236,46 +238,46 @@ format for the requested service name.
Cache-Control headers SHOULD be used to disable caching of the
returned entity.
-The Content-Type MUST be 'application/x-$servicename-advertisement'.
+The Content-Type MUST be `application/x-$servicename-advertisement`.
Clients SHOULD fall back to the dumb protocol if another content
type is returned. When falling back to the dumb protocol clients
-SHOULD NOT make an additional request to $GIT_URL/info/refs, but
+SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but
instead SHOULD use the response already in hand. Clients MUST NOT
continue if they do not support the dumb protocol.
-Clients MUST validate the status code is either '200 OK' or
-'304 Not Modified'.
+Clients MUST validate the status code is either `200 OK` or
+`304 Not Modified`.
Clients MUST validate the first five bytes of the response entity
-matches the regex "^[0-9a-f]{4}#". If this test fails, clients
+matches the regex `^[0-9a-f]{4}#`. If this test fails, clients
MUST NOT continue.
Clients MUST parse the entire response as a sequence of pkt-line
records.
-Clients MUST verify the first pkt-line is "# service=$servicename".
+Clients MUST verify the first pkt-line is `# service=$servicename`.
Servers MUST set $servicename to be the request parameter value.
Servers SHOULD include an LF at the end of this line.
Clients MUST ignore an LF at the end of the line.
-Servers MUST terminate the response with the magic "0000" end
+Servers MUST terminate the response with the magic `0000` end
pkt-line marker.
The returned response is a pkt-line stream describing each ref and
its known value. The stream SHOULD be sorted by name according to
the C locale ordering. The stream SHOULD include the default ref
-named 'HEAD' as the first ref. The stream MUST include capability
+named `HEAD` as the first ref. The stream MUST include capability
declarations behind a NUL on the first ref.
smart_reply = PKT-LINE("# service=$servicename" LF)
- ref_list
- "0000"
+ ref_list
+ "0000"
ref_list = empty_list / non_empty_list
empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF)
- *ref_record
+ *ref_record
cap-list = capability *(SP capability)
capability = 1*(LC_ALPHA / DIGIT / "-" / "_")
@@ -284,14 +286,15 @@ declarations behind a NUL on the first ref.
ref_record = any_ref / peeled_ref
any_ref = PKT-LINE(obj-id SP name LF)
peeled_ref = PKT-LINE(obj-id SP name LF)
- PKT-LINE(obj-id SP name "^{}" LF
+ PKT-LINE(obj-id SP name "^{}" LF
+
Smart Service git-upload-pack
------------------------------
-This service reads from the repository pointed to by $GIT_URL.
+This service reads from the repository pointed to by `$GIT_URL`.
Clients MUST first perform ref discovery with
-'$GIT_URL/info/refs?service=git-upload-pack'.
+`$GIT_URL/info/refs?service=git-upload-pack`.
C: POST $GIT_URL/git-upload-pack HTTP/1.0
C: Content-Type: application/x-git-upload-pack-request
@@ -313,18 +316,18 @@ to prevent caching of the response.
Servers SHOULD support all capabilities defined here.
-Clients MUST send at least one 'want' command in the request body.
-Clients MUST NOT reference an id in a 'want' command which did not
+Clients MUST send at least one "want" command in the request body.
+Clients MUST NOT reference an id in a "want" command which did not
appear in the response obtained through ref discovery unless the
-server advertises capability "allow-tip-sha1-in-want".
+server advertises capability `allow-tip-sha1-in-want`.
compute_request = want_list
- have_list
- request_end
+ have_list
+ request_end
request_end = "0000" / "done"
want_list = PKT-LINE(want NUL cap_list LF)
- *(want_pkt)
+ *(want_pkt)
want_pkt = PKT-LINE(want LF)
want = "want" SP id
cap_list = *(SP capability) SP
@@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.
The Negotiation Algorithm
~~~~~~~~~~~~~~~~~~~~~~~~~
The computation to select the minimal pack proceeds as follows
-(c = client, s = server):
+(C = client, S = server):
+
+'init step:'
+
+C: Use ref discovery to obtain the advertised refs.
+
+C: Place any object seen into set ADVERTISED.
- init step:
- (c) Use ref discovery to obtain the advertised refs.
- (c) Place any object seen into set ADVERTISED.
+C: Build an empty set, COMMON, to hold the objects that are later
+ determined to be on both ends.
- (c) Build an empty set, COMMON, to hold the objects that are later
- determined to be on both ends.
- (c) Build a set, WANT, of the objects from ADVERTISED the client
- wants to fetch, based on what it saw during ref discovery.
+C: Build a set, WANT, of the objects from ADVERTISED the client
+ wants to fetch, based on what it saw during ref discovery.
- (c) Start a queue, C_PENDING, ordered by commit time (popping newest
- first). Add all client refs. When a commit is popped from
- the queue its parents SHOULD be automatically inserted back.
- Commits MUST only enter the queue once.
+C: Start a queue, C_PENDING, ordered by commit time (popping newest
+ first). Add all client refs. When a commit is popped from
+ the queue its parents SHOULD be automatically inserted back.
+ Commits MUST only enter the queue once.
- one compute step:
- (c) Send one $GIT_URL/git-upload-pack request:
+'one compute step:'
+
+C: Send one `$GIT_URL/git-upload-pack` request:
C: 0032want <WANT #1>...............................
C: 0032want <WANT #2>...............................
@@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as follows
....
C: 0000
- The stream is organized into "commands", with each command
- appearing by itself in a pkt-line. Within a command line
- the text leading up to the first space is the command name,
- and the remainder of the line to the first LF is the value.
- Command lines are terminated with an LF as the last byte of
- the pkt-line value.
+The stream is organized into "commands", with each command
+appearing by itself in a pkt-line. Within a command line
+the text leading up to the first space is the command name,
+and the remainder of the line to the first LF is the value.
+Command lines are terminated with an LF as the last byte of
+the pkt-line value.
- Commands MUST appear in the following order, if they appear
- at all in the request stream:
+Commands MUST appear in the following order, if they appear
+at all in the request stream:
- * want
- * have
+* "want"
+* "have"
- The stream is terminated by a pkt-line flush ("0000").
+The stream is terminated by a pkt-line flush (`0000`).
- A single "want" or "have" command MUST have one hex formatted
- SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
- multiple commands.
+A single "want" or "have" command MUST have one hex formatted
+SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
+multiple commands.
- The HAVE list is created by popping the first 32 commits
- from C_PENDING. Less can be supplied if C_PENDING empties.
+The HAVE list is created by popping the first 32 commits
+from C_PENDING. Less can be supplied if C_PENDING empties.
- If the client has sent 256 HAVE commits and has not yet
- received one of those back from S_COMMON, or the client has
- emptied C_PENDING it SHOULD include a "done" command to let
- the server know it won't proceed:
+If the client has sent 256 HAVE commits and has not yet
+received one of those back from S_COMMON, or the client has
+emptied C_PENDING it SHOULD include a "done" command to let
+the server know it won't proceed:
C: 0009done
- (s) Parse the git-upload-pack request:
-
- Verify all objects in WANT are directly reachable from refs.
-
- The server MAY walk backwards through history or through
- the reflog to permit slightly stale requests.
+S: Parse the git-upload-pack request:
- If no WANT objects are received, send an error:
+Verify all objects in WANT are directly reachable from refs.
-TODO: Define error if no want lines are requested.
+The server MAY walk backwards through history or through
+the reflog to permit slightly stale requests.
- If any WANT object is not reachable, send an error:
+If no WANT objects are received, send an error:
+TODO: Define error if no "want" lines are requested.
-TODO: Define error if an invalid want is requested.
+If any WANT object is not reachable, send an error:
+TODO: Define error if an invalid "want" is requested.
- Create an empty list, S_COMMON.
+Create an empty list, S_COMMON.
- If 'have' was sent:
+If "have" was sent:
- Loop through the objects in the order supplied by the client.
- For each object, if the server has the object reachable from
- a ref, add it to S_COMMON. If a commit is added to S_COMMON,
- do not add any ancestors, even if they also appear in HAVE.
+Loop through the objects in the order supplied by the client.
- (s) Send the git-upload-pack response:
+For each object, if the server has the object reachable from
+a ref, add it to S_COMMON. If a commit is added to S_COMMON,
+do not add any ancestors, even if they also appear in HAVE.
- If the server has found a closed set of objects to pack or the
- request ends with "done", it replies with the pack.
+S: Send the git-upload-pack response:
+If the server has found a closed set of objects to pack or the
+request ends with "done", it replies with the pack.
TODO: Document the pack based response
- S: PACK...
- The returned stream is the side-band-64k protocol supported
- by the git-upload-pack service, and the pack is embedded into
- stream 1. Progress messages from the server side MAY appear
- in stream 2.
+ S: PACK...
- Here a "closed set of objects" is defined to have at least
- one path from every WANT to at least one COMMON object.
+The returned stream is the side-band-64k protocol supported
+by the git-upload-pack service, and the pack is embedded into
+stream 1. Progress messages from the server side MAY appear
+in stream 2.
- If the server needs more information, it replies with a
- status continue response:
+Here a "closed set of objects" is defined to have at least
+one path from every WANT to at least one COMMON object.
+If the server needs more information, it replies with a
+status continue response:
TODO: Document the non-pack response
- (c) Parse the upload-pack response:
-
-TODO: Document parsing response
+C: Parse the upload-pack response:
+ TODO: Document parsing response
- Do another compute step.
+'Do another compute step.'
Smart Service git-receive-pack
------------------------------
-This service reads from the repository pointed to by $GIT_URL.
+This service reads from the repository pointed to by `$GIT_URL`.
Clients MUST first perform ref discovery with
-'$GIT_URL/info/refs?service=git-receive-pack'.
+`$GIT_URL/info/refs?service=git-receive-pack`.
C: POST $GIT_URL/git-receive-pack HTTP/1.0
C: Content-Type: application/x-git-receive-pack-request
@@ -479,10 +483,10 @@ Within the command portion of the request body clients SHOULD send
the id obtained through ref discovery as old_id.
update_request = command_list
- "PACK" <binary data>
+ "PACK" <binary data>
command_list = PKT-LINE(command NUL cap_list LF)
- *(command_pkt)
+ *(command_pkt)
command_pkt = PKT-LINE(command LF)
cap_list = *(SP capability) SP
--
1.8.5.2.msysgit.0
---
Thomas
^ permalink raw reply related [flat|nested] 5+ messages in thread* Aw: [PATCH 1/2] create HTML for http-protocol.txt
2014-01-26 12:54 ` [PATCH 1/2] " Thomas Ackermann
@ 2014-01-26 13:01 ` Thomas Ackermann
0 siblings, 0 replies; 5+ messages in thread
From: Thomas Ackermann @ 2014-01-26 13:01 UTC (permalink / raw)
To: git; +Cc: gitster, spearce, th.acker
please ignore this one
----- Original Nachricht ----
Von: Thomas Ackermann <th.acker@arcor.de>
An: git@vger.kernel.org
Datum: 26.01.2014 13:54
Betreff: [PATCH 1/2] create HTML for http-protocol.txt
> [PATCH 1/2] 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>
> ---
> Documentation/Makefile | 3 +-
> Documentation/technical/http-protocol.txt | 232
> +++++++++++++++---------------
> 2 files changed, 120 insertions(+), 115 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 36c58fc..b19d52a 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git
> API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt
> technical/api-index.txt, $(wildcard technical/api-*.txt)))
> SP_ARTICLES += $(API_DOCS)
>
> -TECH_DOCS = technical/index-format
> +TECH_DOCS = technical/http-protocol
> +TECH_DOCS += technical/index-format
> TECH_DOCS += technical/pack-format
> TECH_DOCS += technical/pack-heuristics
> TECH_DOCS += technical/pack-protocol
> diff --git a/Documentation/technical/http-protocol.txt
> b/Documentation/technical/http-protocol.txt
> index d21d77d..7f0cf0b 100644
> --- a/Documentation/technical/http-protocol.txt
> +++ b/Documentation/technical/http-protocol.txt
> @@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the
> form:
>
> http://<host>:<port>/<path>?<searchpart>
>
> -Within this documentation the placeholder $GIT_URL will stand for
> +Within this documentation the placeholder `$GIT_URL` will stand for
> the http:// repository URL entered by the end-user.
>
> -Servers SHOULD handle all requests to locations matching $GIT_URL, as
> +Servers SHOULD handle all requests to locations matching `$GIT_URL`, as
> both the "smart" and "dumb" HTTP protocols used by Git operate
> by appending additional path components onto the end of the user
> -supplied $GIT_URL string.
> +supplied `$GIT_URL` string.
>
> An example of a dumb client requesting for a loose object:
>
> @@ -43,10 +43,10 @@ An example of a request to a submodule:
> $GIT_URL: http://example.com/git/repo.git/path/submodule.git
> URL request:
> http://example.com/git/repo.git/path/submodule.git/info/refs
>
> -Clients MUST strip a trailing '/', if present, from the user supplied
> -$GIT_URL string to prevent empty path tokens ('//') from appearing
> +Clients MUST strip a trailing `/`, if present, from the user supplied
> +`$GIT_URL` string to prevent empty path tokens (`//`) from appearing
> in any URL sent to a server. Compatible clients MUST expand
> -'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.
> +`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.
>
>
> Authentication
> @@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD
> be assumed
> by both client and server. This includes (but is not necessarily
> limited to):
>
> -If there is no repository at $GIT_URL, or the resource pointed to by a
> -location matching $GIT_URL does not exist, the server MUST NOT respond
> -with '200 OK' response. A server SHOULD respond with
> -'404 Not Found', '410 Gone', or any other suitable HTTP status code
> +If there is no repository at `$GIT_URL`, or the resource pointed to by a
> +location matching `$GIT_URL` does not exist, the server MUST NOT respond
> +with `200 OK` response. A server SHOULD respond with
> +`404 Not Found`, `410 Gone`, or any other suitable HTTP status code
> which does not imply the resource exists as requested.
>
> -If there is a repository at $GIT_URL, but access is not currently
> -permitted, the server MUST respond with the '403 Forbidden' HTTP
> +If there is a repository at `$GIT_URL`, but access is not currently
> +permitted, the server MUST respond with the `403 Forbidden` HTTP
> status code.
>
> Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
> @@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.
> Clients MAY revalidate cached entities by including If-Modified-Since
> and/or If-None-Match request headers.
>
> -Servers MAY return '304 Not Modified' if the relevant headers appear
> +Servers MAY return `304 Not Modified` if the relevant headers appear
> in the request and the entity has not changed. Clients MUST treat
> -'304 Not Modified' identical to '200 OK' by reusing the cached entity.
> +`304 Not Modified` identical to `200 OK` by reusing the cached entity.
>
> Clients MAY reuse a cached entity without revalidation if the
> Cache-Control and/or Expires header permits caching. Clients and
> @@ -148,7 +148,7 @@ HTTP clients that only support the "dumb" protocol MUST
> discover
> references by making a request for the special info/refs file of
> the repository.
>
> -Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,
> +Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,
> without any search/query parameters.
>
> C: GET $GIT_URL/info/refs HTTP/1.0
> @@ -161,28 +161,28 @@ without any search/query parameters.
> S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
>
> The Content-Type of the returned info/refs entity SHOULD be
> -"text/plain; charset=utf-8", but MAY be any content type.
> +`text/plain; charset=utf-8`, but MAY be any content type.
> Clients MUST NOT attempt to validate the returned Content-Type.
> Dumb servers MUST NOT return a return type starting with
> -"application/x-git-".
> +`application/x-git-`.
>
> Cache-Control headers MAY be returned to disable caching of the
> returned entity.
>
> When examining the response clients SHOULD only examine the HTTP
> -status code. Valid responses are '200 OK', or '304 Not Modified'.
> +status code. Valid responses are `200 OK`, or `304 Not Modified`.
>
> The returned content is a UNIX formatted text file describing
> each ref and its known value. The file SHOULD be sorted by name
> according to the C locale ordering. The file SHOULD NOT include
> -the default ref named 'HEAD'.
> +the default ref named `HEAD`.
>
> info_refs = *( ref_record )
> ref_record = any_ref / peeled_ref
>
> any_ref = obj-id HTAB refname LF
> peeled_ref = obj-id HTAB refname LF
> - obj-id HTAB refname "^{}" LF
> + obj-id HTAB refname "^{}" LF
>
> Smart Clients
> ~~~~~~~~~~~~~
> @@ -192,13 +192,14 @@ HTTP clients that support the "smart" protocol (or
> both the
> a parameterized request for the info/refs file of the repository.
>
> The request MUST contain exactly one query parameter,
> -'service=$servicename', where $servicename MUST be the service
> +`service=$servicename`, where `$servicename` MUST be the service
> name the client wishes to contact to complete the operation.
> The request MUST NOT contain additional query parameters.
>
> C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
>
> - dumb server reply:
> +dumb server reply:
> +
> S: 200 OK
> S:
> S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
> @@ -206,7 +207,8 @@ The request MUST NOT contain additional query
> parameters.
> S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
> S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
>
> - smart server reply:
> +smart server reply:
> +
> S: 200 OK
> S: Content-Type: application/x-git-upload-pack-advertisement
> S: Cache-Control: no-cache
> @@ -228,7 +230,7 @@ Smart Server Response
> ^^^^^^^^^^^^^^^^^^^^^
> If the server does not recognize the requested service name, or the
> requested service name has been disabled by the server administrator,
> -the server MUST respond with the '403 Forbidden' HTTP status code.
> +the server MUST respond with the `403 Forbidden` HTTP status code.
>
> Otherwise, smart servers MUST respond with the smart server reply
> format for the requested service name.
> @@ -236,46 +238,46 @@ format for the requested service name.
> Cache-Control headers SHOULD be used to disable caching of the
> returned entity.
>
> -The Content-Type MUST be 'application/x-$servicename-advertisement'.
> +The Content-Type MUST be `application/x-$servicename-advertisement`.
> Clients SHOULD fall back to the dumb protocol if another content
> type is returned. When falling back to the dumb protocol clients
> -SHOULD NOT make an additional request to $GIT_URL/info/refs, but
> +SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but
> instead SHOULD use the response already in hand. Clients MUST NOT
> continue if they do not support the dumb protocol.
>
> -Clients MUST validate the status code is either '200 OK' or
> -'304 Not Modified'.
> +Clients MUST validate the status code is either `200 OK` or
> +`304 Not Modified`.
>
> Clients MUST validate the first five bytes of the response entity
> -matches the regex "^[0-9a-f]{4}#". If this test fails, clients
> +matches the regex `^[0-9a-f]{4}#`. If this test fails, clients
> MUST NOT continue.
>
> Clients MUST parse the entire response as a sequence of pkt-line
> records.
>
> -Clients MUST verify the first pkt-line is "# service=$servicename".
> +Clients MUST verify the first pkt-line is `# service=$servicename`.
> Servers MUST set $servicename to be the request parameter value.
> Servers SHOULD include an LF at the end of this line.
> Clients MUST ignore an LF at the end of the line.
>
> -Servers MUST terminate the response with the magic "0000" end
> +Servers MUST terminate the response with the magic `0000` end
> pkt-line marker.
>
> The returned response is a pkt-line stream describing each ref and
> its known value. The stream SHOULD be sorted by name according to
> the C locale ordering. The stream SHOULD include the default ref
> -named 'HEAD' as the first ref. The stream MUST include capability
> +named `HEAD` as the first ref. The stream MUST include capability
> declarations behind a NUL on the first ref.
>
> smart_reply = PKT-LINE("# service=$servicename" LF)
> - ref_list
> - "0000"
> + ref_list
> + "0000"
> ref_list = empty_list / non_empty_list
>
> empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list
> LF)
>
> non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF)
> - *ref_record
> + *ref_record
>
> cap-list = capability *(SP capability)
> capability = 1*(LC_ALPHA / DIGIT / "-" / "_")
> @@ -284,14 +286,15 @@ declarations behind a NUL on the first ref.
> ref_record = any_ref / peeled_ref
> any_ref = PKT-LINE(obj-id SP name LF)
> peeled_ref = PKT-LINE(obj-id SP name LF)
> - PKT-LINE(obj-id SP name "^{}" LF
> + PKT-LINE(obj-id SP name "^{}" LF
> +
>
> Smart Service git-upload-pack
> ------------------------------
> -This service reads from the repository pointed to by $GIT_URL.
> +This service reads from the repository pointed to by `$GIT_URL`.
>
> Clients MUST first perform ref discovery with
> -'$GIT_URL/info/refs?service=git-upload-pack'.
> +`$GIT_URL/info/refs?service=git-upload-pack`.
>
> C: POST $GIT_URL/git-upload-pack HTTP/1.0
> C: Content-Type: application/x-git-upload-pack-request
> @@ -313,18 +316,18 @@ to prevent caching of the response.
>
> Servers SHOULD support all capabilities defined here.
>
> -Clients MUST send at least one 'want' command in the request body.
> -Clients MUST NOT reference an id in a 'want' command which did not
> +Clients MUST send at least one "want" command in the request body.
> +Clients MUST NOT reference an id in a "want" command which did not
> appear in the response obtained through ref discovery unless the
> -server advertises capability "allow-tip-sha1-in-want".
> +server advertises capability `allow-tip-sha1-in-want`.
>
> compute_request = want_list
> - have_list
> - request_end
> + have_list
> + request_end
> request_end = "0000" / "done"
>
> want_list = PKT-LINE(want NUL cap_list LF)
> - *(want_pkt)
> + *(want_pkt)
> want_pkt = PKT-LINE(want LF)
> want = "want" SP id
> cap_list = *(SP capability) SP
> @@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.
> The Negotiation Algorithm
> ~~~~~~~~~~~~~~~~~~~~~~~~~
> The computation to select the minimal pack proceeds as follows
> -(c = client, s = server):
> +(C = client, S = server):
> +
> +'init step:'
> +
> +C: Use ref discovery to obtain the advertised refs.
> +
> +C: Place any object seen into set ADVERTISED.
>
> - init step:
> - (c) Use ref discovery to obtain the advertised refs.
> - (c) Place any object seen into set ADVERTISED.
> +C: Build an empty set, COMMON, to hold the objects that are later
> + determined to be on both ends.
>
> - (c) Build an empty set, COMMON, to hold the objects that are later
> - determined to be on both ends.
> - (c) Build a set, WANT, of the objects from ADVERTISED the client
> - wants to fetch, based on what it saw during ref discovery.
> +C: Build a set, WANT, of the objects from ADVERTISED the client
> + wants to fetch, based on what it saw during ref discovery.
>
> - (c) Start a queue, C_PENDING, ordered by commit time (popping newest
> - first). Add all client refs. When a commit is popped from
> - the queue its parents SHOULD be automatically inserted back.
> - Commits MUST only enter the queue once.
> +C: Start a queue, C_PENDING, ordered by commit time (popping newest
> + first). Add all client refs. When a commit is popped from
> + the queue its parents SHOULD be automatically inserted back.
> + Commits MUST only enter the queue once.
>
> - one compute step:
> - (c) Send one $GIT_URL/git-upload-pack request:
> +'one compute step:'
> +
> +C: Send one `$GIT_URL/git-upload-pack` request:
>
> C: 0032want <WANT #1>...............................
> C: 0032want <WANT #2>...............................
> @@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as
> follows
> ....
> C: 0000
>
> - The stream is organized into "commands", with each command
> - appearing by itself in a pkt-line. Within a command line
> - the text leading up to the first space is the command name,
> - and the remainder of the line to the first LF is the value.
> - Command lines are terminated with an LF as the last byte of
> - the pkt-line value.
> +The stream is organized into "commands", with each command
> +appearing by itself in a pkt-line. Within a command line
> +the text leading up to the first space is the command name,
> +and the remainder of the line to the first LF is the value.
> +Command lines are terminated with an LF as the last byte of
> +the pkt-line value.
>
> - Commands MUST appear in the following order, if they appear
> - at all in the request stream:
> +Commands MUST appear in the following order, if they appear
> +at all in the request stream:
>
> - * want
> - * have
> +* "want"
> +* "have"
>
> - The stream is terminated by a pkt-line flush ("0000").
> +The stream is terminated by a pkt-line flush (`0000`).
>
> - A single "want" or "have" command MUST have one hex formatted
> - SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
> - multiple commands.
> +A single "want" or "have" command MUST have one hex formatted
> +SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
> +multiple commands.
>
> - The HAVE list is created by popping the first 32 commits
> - from C_PENDING. Less can be supplied if C_PENDING empties.
> +The HAVE list is created by popping the first 32 commits
> +from C_PENDING. Less can be supplied if C_PENDING empties.
>
> - If the client has sent 256 HAVE commits and has not yet
> - received one of those back from S_COMMON, or the client has
> - emptied C_PENDING it SHOULD include a "done" command to let
> - the server know it won't proceed:
> +If the client has sent 256 HAVE commits and has not yet
> +received one of those back from S_COMMON, or the client has
> +emptied C_PENDING it SHOULD include a "done" command to let
> +the server know it won't proceed:
>
> C: 0009done
>
> - (s) Parse the git-upload-pack request:
> -
> - Verify all objects in WANT are directly reachable from refs.
> -
> - The server MAY walk backwards through history or through
> - the reflog to permit slightly stale requests.
> +S: Parse the git-upload-pack request:
>
> - If no WANT objects are received, send an error:
> +Verify all objects in WANT are directly reachable from refs.
>
> -TODO: Define error if no want lines are requested.
> +The server MAY walk backwards through history or through
> +the reflog to permit slightly stale requests.
>
> - If any WANT object is not reachable, send an error:
> +If no WANT objects are received, send an error:
> +TODO: Define error if no "want" lines are requested.
>
> -TODO: Define error if an invalid want is requested.
> +If any WANT object is not reachable, send an error:
> +TODO: Define error if an invalid "want" is requested.
>
> - Create an empty list, S_COMMON.
> +Create an empty list, S_COMMON.
>
> - If 'have' was sent:
> +If "have" was sent:
>
> - Loop through the objects in the order supplied by the client.
> - For each object, if the server has the object reachable from
> - a ref, add it to S_COMMON. If a commit is added to S_COMMON,
> - do not add any ancestors, even if they also appear in HAVE.
> +Loop through the objects in the order supplied by the client.
>
> - (s) Send the git-upload-pack response:
> +For each object, if the server has the object reachable from
> +a ref, add it to S_COMMON. If a commit is added to S_COMMON,
> +do not add any ancestors, even if they also appear in HAVE.
>
> - If the server has found a closed set of objects to pack or the
> - request ends with "done", it replies with the pack.
> +S: Send the git-upload-pack response:
>
> +If the server has found a closed set of objects to pack or the
> +request ends with "done", it replies with the pack.
> TODO: Document the pack based response
> - S: PACK...
>
> - The returned stream is the side-band-64k protocol supported
> - by the git-upload-pack service, and the pack is embedded into
> - stream 1. Progress messages from the server side MAY appear
> - in stream 2.
> + S: PACK...
>
> - Here a "closed set of objects" is defined to have at least
> - one path from every WANT to at least one COMMON object.
> +The returned stream is the side-band-64k protocol supported
> +by the git-upload-pack service, and the pack is embedded into
> +stream 1. Progress messages from the server side MAY appear
> +in stream 2.
>
> - If the server needs more information, it replies with a
> - status continue response:
> +Here a "closed set of objects" is defined to have at least
> +one path from every WANT to at least one COMMON object.
>
> +If the server needs more information, it replies with a
> +status continue response:
> TODO: Document the non-pack response
>
> - (c) Parse the upload-pack response:
> -
> -TODO: Document parsing response
> +C: Parse the upload-pack response:
> + TODO: Document parsing response
>
> - Do another compute step.
> +'Do another compute step.'
>
>
> Smart Service git-receive-pack
> ------------------------------
> -This service reads from the repository pointed to by $GIT_URL.
> +This service reads from the repository pointed to by `$GIT_URL`.
>
> Clients MUST first perform ref discovery with
> -'$GIT_URL/info/refs?service=git-receive-pack'.
> +`$GIT_URL/info/refs?service=git-receive-pack`.
>
> C: POST $GIT_URL/git-receive-pack HTTP/1.0
> C: Content-Type: application/x-git-receive-pack-request
> @@ -479,10 +483,10 @@ Within the command portion of the request body clients
> SHOULD send
> the id obtained through ref discovery as old_id.
>
> update_request = command_list
> - "PACK" <binary data>
> + "PACK" <binary data>
>
> command_list = PKT-LINE(command NUL cap_list LF)
> - *(command_pkt)
> + *(command_pkt)
> command_pkt = PKT-LINE(command LF)
> cap_list = *(SP capability) SP
>
> --
> 1.8.5.2.msysgit.0
>
>
>
> ---
> Thomas
>
---
Thomas
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH 2/2] http-protocol.txt: don't use uppercase for variable names in "The Negotiation Algorithm"
2014-01-26 12:52 [PATCH v2 0/2] create HTML for http-protocol.txt Thomas Ackermann
2014-01-26 12:54 ` [PATCH 1/2] " Thomas Ackermann
@ 2014-01-26 12:56 ` Thomas Ackermann
2014-01-26 12:57 ` [PATCH 1/2] create HTML for http-protocol.txt Thomas Ackermann
2 siblings, 0 replies; 5+ messages in thread
From: Thomas Ackermann @ 2014-01-26 12:56 UTC (permalink / raw)
To: git; +Cc: gitster, spearce, th.acker
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
Documentation/technical/http-protocol.txt | 45 +++++++++++++++----------------
1 file changed, 22 insertions(+), 23 deletions(-)
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index 7f0cf0b..90beb32 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -335,7 +335,6 @@ server advertises capability `allow-tip-sha1-in-want`.
have_list = *PKT-LINE("have" SP id LF)
TODO: Document this further.
-TODO: Don't use uppercase for variable names below.
The Negotiation Algorithm
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -346,15 +345,15 @@ The computation to select the minimal pack proceeds as follows
C: Use ref discovery to obtain the advertised refs.
-C: Place any object seen into set ADVERTISED.
+C: Place any object seen into set `advertised`.
-C: Build an empty set, COMMON, to hold the objects that are later
+C: Build an empty set, `common`, to hold the objects that are later
determined to be on both ends.
-C: Build a set, WANT, of the objects from ADVERTISED the client
+C: Build a set, `want`, of the objects from `advertised` the client
wants to fetch, based on what it saw during ref discovery.
-C: Start a queue, C_PENDING, ordered by commit time (popping newest
+C: Start a queue, `c_pending`, ordered by commit time (popping newest
first). Add all client refs. When a commit is popped from
the queue its parents SHOULD be automatically inserted back.
Commits MUST only enter the queue once.
@@ -363,14 +362,14 @@ C: Start a queue, C_PENDING, ordered by commit time (popping newest
C: Send one `$GIT_URL/git-upload-pack` request:
- C: 0032want <WANT #1>...............................
- C: 0032want <WANT #2>...............................
+ C: 0032want <want #1>...............................
+ C: 0032want <want #2>...............................
....
- C: 0032have <COMMON #1>.............................
- C: 0032have <COMMON #2>.............................
+ C: 0032have <common #1>.............................
+ C: 0032have <common #2>.............................
....
- C: 0032have <HAVE #1>...............................
- C: 0032have <HAVE #2>...............................
+ C: 0032have <have #1>...............................
+ C: 0032have <have #2>...............................
....
C: 0000
@@ -393,38 +392,38 @@ A single "want" or "have" command MUST have one hex formatted
SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
multiple commands.
-The HAVE list is created by popping the first 32 commits
-from C_PENDING. Less can be supplied if C_PENDING empties.
+The `have` list is created by popping the first 32 commits
+from `c_pending`. Less can be supplied if `c_pending` empties.
-If the client has sent 256 HAVE commits and has not yet
-received one of those back from S_COMMON, or the client has
-emptied C_PENDING it SHOULD include a "done" command to let
+If the client has sent 256 "have" commits and has not yet
+received one of those back from `s_common`, or the client has
+emptied `c_pending` it SHOULD include a "done" command to let
the server know it won't proceed:
C: 0009done
S: Parse the git-upload-pack request:
-Verify all objects in WANT are directly reachable from refs.
+Verify all objects in `want` are directly reachable from refs.
The server MAY walk backwards through history or through
the reflog to permit slightly stale requests.
-If no WANT objects are received, send an error:
+If no "want" objects are received, send an error:
TODO: Define error if no "want" lines are requested.
-If any WANT object is not reachable, send an error:
+If any "want" object is not reachable, send an error:
TODO: Define error if an invalid "want" is requested.
-Create an empty list, S_COMMON.
+Create an empty list, `s_common`.
If "have" was sent:
Loop through the objects in the order supplied by the client.
For each object, if the server has the object reachable from
-a ref, add it to S_COMMON. If a commit is added to S_COMMON,
-do not add any ancestors, even if they also appear in HAVE.
+a ref, add it to `s_common`. If a commit is added to `s_common`,
+do not add any ancestors, even if they also appear in `have`.
S: Send the git-upload-pack response:
@@ -440,7 +439,7 @@ stream 1. Progress messages from the server side MAY appear
in stream 2.
Here a "closed set of objects" is defined to have at least
-one path from every WANT to at least one COMMON object.
+one path from every "want" to at least one "common" object.
If the server needs more information, it replies with a
status continue response:
--
1.8.5.2.msysgit.0
---
Thomas
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 1/2] create HTML for http-protocol.txt
2014-01-26 12:52 [PATCH v2 0/2] create HTML for http-protocol.txt Thomas Ackermann
2014-01-26 12:54 ` [PATCH 1/2] " Thomas Ackermann
2014-01-26 12:56 ` [PATCH 2/2] http-protocol.txt: don't use uppercase for variable names in "The Negotiation Algorithm" Thomas Ackermann
@ 2014-01-26 12:57 ` Thomas Ackermann
2 siblings, 0 replies; 5+ messages in thread
From: Thomas Ackermann @ 2014-01-26 12:57 UTC (permalink / raw)
To: git; +Cc: gitster, spearce, th.acker
./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>
---
Documentation/Makefile | 3 +-
Documentation/technical/http-protocol.txt | 232 +++++++++++++++---------------
2 files changed, 120 insertions(+), 115 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36c58fc..b19d52a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
SP_ARTICLES += $(API_DOCS)
-TECH_DOCS = technical/index-format
+TECH_DOCS = technical/http-protocol
+TECH_DOCS += technical/index-format
TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
TECH_DOCS += technical/pack-protocol
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index d21d77d..7f0cf0b 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the form:
http://<host>:<port>/<path>?<searchpart>
-Within this documentation the placeholder $GIT_URL will stand for
+Within this documentation the placeholder `$GIT_URL` will stand for
the http:// repository URL entered by the end-user.
-Servers SHOULD handle all requests to locations matching $GIT_URL, as
+Servers SHOULD handle all requests to locations matching `$GIT_URL`, as
both the "smart" and "dumb" HTTP protocols used by Git operate
by appending additional path components onto the end of the user
-supplied $GIT_URL string.
+supplied `$GIT_URL` string.
An example of a dumb client requesting for a loose object:
@@ -43,10 +43,10 @@ An example of a request to a submodule:
$GIT_URL: http://example.com/git/repo.git/path/submodule.git
URL request: http://example.com/git/repo.git/path/submodule.git/info/refs
-Clients MUST strip a trailing '/', if present, from the user supplied
-$GIT_URL string to prevent empty path tokens ('//') from appearing
+Clients MUST strip a trailing `/`, if present, from the user supplied
+`$GIT_URL` string to prevent empty path tokens (`//`) from appearing
in any URL sent to a server. Compatible clients MUST expand
-'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.
+`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.
Authentication
@@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD be assumed
by both client and server. This includes (but is not necessarily
limited to):
-If there is no repository at $GIT_URL, or the resource pointed to by a
-location matching $GIT_URL does not exist, the server MUST NOT respond
-with '200 OK' response. A server SHOULD respond with
-'404 Not Found', '410 Gone', or any other suitable HTTP status code
+If there is no repository at `$GIT_URL`, or the resource pointed to by a
+location matching `$GIT_URL` does not exist, the server MUST NOT respond
+with `200 OK` response. A server SHOULD respond with
+`404 Not Found`, `410 Gone`, or any other suitable HTTP status code
which does not imply the resource exists as requested.
-If there is a repository at $GIT_URL, but access is not currently
-permitted, the server MUST respond with the '403 Forbidden' HTTP
+If there is a repository at `$GIT_URL`, but access is not currently
+permitted, the server MUST respond with the `403 Forbidden` HTTP
status code.
Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
@@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.
Clients MAY revalidate cached entities by including If-Modified-Since
and/or If-None-Match request headers.
-Servers MAY return '304 Not Modified' if the relevant headers appear
+Servers MAY return `304 Not Modified` if the relevant headers appear
in the request and the entity has not changed. Clients MUST treat
-'304 Not Modified' identical to '200 OK' by reusing the cached entity.
+`304 Not Modified` identical to `200 OK` by reusing the cached entity.
Clients MAY reuse a cached entity without revalidation if the
Cache-Control and/or Expires header permits caching. Clients and
@@ -148,7 +148,7 @@ HTTP clients that only support the "dumb" protocol MUST discover
references by making a request for the special info/refs file of
the repository.
-Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,
+Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,
without any search/query parameters.
C: GET $GIT_URL/info/refs HTTP/1.0
@@ -161,28 +161,28 @@ without any search/query parameters.
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
The Content-Type of the returned info/refs entity SHOULD be
-"text/plain; charset=utf-8", but MAY be any content type.
+`text/plain; charset=utf-8`, but MAY be any content type.
Clients MUST NOT attempt to validate the returned Content-Type.
Dumb servers MUST NOT return a return type starting with
-"application/x-git-".
+`application/x-git-`.
Cache-Control headers MAY be returned to disable caching of the
returned entity.
When examining the response clients SHOULD only examine the HTTP
-status code. Valid responses are '200 OK', or '304 Not Modified'.
+status code. Valid responses are `200 OK`, or `304 Not Modified`.
The returned content is a UNIX formatted text file describing
each ref and its known value. The file SHOULD be sorted by name
according to the C locale ordering. The file SHOULD NOT include
-the default ref named 'HEAD'.
+the default ref named `HEAD`.
info_refs = *( ref_record )
ref_record = any_ref / peeled_ref
any_ref = obj-id HTAB refname LF
peeled_ref = obj-id HTAB refname LF
- obj-id HTAB refname "^{}" LF
+ obj-id HTAB refname "^{}" LF
Smart Clients
~~~~~~~~~~~~~
@@ -192,13 +192,14 @@ HTTP clients that support the "smart" protocol (or both the
a parameterized request for the info/refs file of the repository.
The request MUST contain exactly one query parameter,
-'service=$servicename', where $servicename MUST be the service
+`service=$servicename`, where `$servicename` MUST be the service
name the client wishes to contact to complete the operation.
The request MUST NOT contain additional query parameters.
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
- dumb server reply:
+dumb server reply:
+
S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
@@ -206,7 +207,8 @@ The request MUST NOT contain additional query parameters.
S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
- smart server reply:
+smart server reply:
+
S: 200 OK
S: Content-Type: application/x-git-upload-pack-advertisement
S: Cache-Control: no-cache
@@ -228,7 +230,7 @@ Smart Server Response
^^^^^^^^^^^^^^^^^^^^^
If the server does not recognize the requested service name, or the
requested service name has been disabled by the server administrator,
-the server MUST respond with the '403 Forbidden' HTTP status code.
+the server MUST respond with the `403 Forbidden` HTTP status code.
Otherwise, smart servers MUST respond with the smart server reply
format for the requested service name.
@@ -236,46 +238,46 @@ format for the requested service name.
Cache-Control headers SHOULD be used to disable caching of the
returned entity.
-The Content-Type MUST be 'application/x-$servicename-advertisement'.
+The Content-Type MUST be `application/x-$servicename-advertisement`.
Clients SHOULD fall back to the dumb protocol if another content
type is returned. When falling back to the dumb protocol clients
-SHOULD NOT make an additional request to $GIT_URL/info/refs, but
+SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but
instead SHOULD use the response already in hand. Clients MUST NOT
continue if they do not support the dumb protocol.
-Clients MUST validate the status code is either '200 OK' or
-'304 Not Modified'.
+Clients MUST validate the status code is either `200 OK` or
+`304 Not Modified`.
Clients MUST validate the first five bytes of the response entity
-matches the regex "^[0-9a-f]{4}#". If this test fails, clients
+matches the regex `^[0-9a-f]{4}#`. If this test fails, clients
MUST NOT continue.
Clients MUST parse the entire response as a sequence of pkt-line
records.
-Clients MUST verify the first pkt-line is "# service=$servicename".
+Clients MUST verify the first pkt-line is `# service=$servicename`.
Servers MUST set $servicename to be the request parameter value.
Servers SHOULD include an LF at the end of this line.
Clients MUST ignore an LF at the end of the line.
-Servers MUST terminate the response with the magic "0000" end
+Servers MUST terminate the response with the magic `0000` end
pkt-line marker.
The returned response is a pkt-line stream describing each ref and
its known value. The stream SHOULD be sorted by name according to
the C locale ordering. The stream SHOULD include the default ref
-named 'HEAD' as the first ref. The stream MUST include capability
+named `HEAD` as the first ref. The stream MUST include capability
declarations behind a NUL on the first ref.
smart_reply = PKT-LINE("# service=$servicename" LF)
- ref_list
- "0000"
+ ref_list
+ "0000"
ref_list = empty_list / non_empty_list
empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF)
- *ref_record
+ *ref_record
cap-list = capability *(SP capability)
capability = 1*(LC_ALPHA / DIGIT / "-" / "_")
@@ -284,14 +286,15 @@ declarations behind a NUL on the first ref.
ref_record = any_ref / peeled_ref
any_ref = PKT-LINE(obj-id SP name LF)
peeled_ref = PKT-LINE(obj-id SP name LF)
- PKT-LINE(obj-id SP name "^{}" LF
+ PKT-LINE(obj-id SP name "^{}" LF
+
Smart Service git-upload-pack
------------------------------
-This service reads from the repository pointed to by $GIT_URL.
+This service reads from the repository pointed to by `$GIT_URL`.
Clients MUST first perform ref discovery with
-'$GIT_URL/info/refs?service=git-upload-pack'.
+`$GIT_URL/info/refs?service=git-upload-pack`.
C: POST $GIT_URL/git-upload-pack HTTP/1.0
C: Content-Type: application/x-git-upload-pack-request
@@ -313,18 +316,18 @@ to prevent caching of the response.
Servers SHOULD support all capabilities defined here.
-Clients MUST send at least one 'want' command in the request body.
-Clients MUST NOT reference an id in a 'want' command which did not
+Clients MUST send at least one "want" command in the request body.
+Clients MUST NOT reference an id in a "want" command which did not
appear in the response obtained through ref discovery unless the
-server advertises capability "allow-tip-sha1-in-want".
+server advertises capability `allow-tip-sha1-in-want`.
compute_request = want_list
- have_list
- request_end
+ have_list
+ request_end
request_end = "0000" / "done"
want_list = PKT-LINE(want NUL cap_list LF)
- *(want_pkt)
+ *(want_pkt)
want_pkt = PKT-LINE(want LF)
want = "want" SP id
cap_list = *(SP capability) SP
@@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.
The Negotiation Algorithm
~~~~~~~~~~~~~~~~~~~~~~~~~
The computation to select the minimal pack proceeds as follows
-(c = client, s = server):
+(C = client, S = server):
+
+'init step:'
+
+C: Use ref discovery to obtain the advertised refs.
+
+C: Place any object seen into set ADVERTISED.
- init step:
- (c) Use ref discovery to obtain the advertised refs.
- (c) Place any object seen into set ADVERTISED.
+C: Build an empty set, COMMON, to hold the objects that are later
+ determined to be on both ends.
- (c) Build an empty set, COMMON, to hold the objects that are later
- determined to be on both ends.
- (c) Build a set, WANT, of the objects from ADVERTISED the client
- wants to fetch, based on what it saw during ref discovery.
+C: Build a set, WANT, of the objects from ADVERTISED the client
+ wants to fetch, based on what it saw during ref discovery.
- (c) Start a queue, C_PENDING, ordered by commit time (popping newest
- first). Add all client refs. When a commit is popped from
- the queue its parents SHOULD be automatically inserted back.
- Commits MUST only enter the queue once.
+C: Start a queue, C_PENDING, ordered by commit time (popping newest
+ first). Add all client refs. When a commit is popped from
+ the queue its parents SHOULD be automatically inserted back.
+ Commits MUST only enter the queue once.
- one compute step:
- (c) Send one $GIT_URL/git-upload-pack request:
+'one compute step:'
+
+C: Send one `$GIT_URL/git-upload-pack` request:
C: 0032want <WANT #1>...............................
C: 0032want <WANT #2>...............................
@@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as follows
....
C: 0000
- The stream is organized into "commands", with each command
- appearing by itself in a pkt-line. Within a command line
- the text leading up to the first space is the command name,
- and the remainder of the line to the first LF is the value.
- Command lines are terminated with an LF as the last byte of
- the pkt-line value.
+The stream is organized into "commands", with each command
+appearing by itself in a pkt-line. Within a command line
+the text leading up to the first space is the command name,
+and the remainder of the line to the first LF is the value.
+Command lines are terminated with an LF as the last byte of
+the pkt-line value.
- Commands MUST appear in the following order, if they appear
- at all in the request stream:
+Commands MUST appear in the following order, if they appear
+at all in the request stream:
- * want
- * have
+* "want"
+* "have"
- The stream is terminated by a pkt-line flush ("0000").
+The stream is terminated by a pkt-line flush (`0000`).
- A single "want" or "have" command MUST have one hex formatted
- SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
- multiple commands.
+A single "want" or "have" command MUST have one hex formatted
+SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
+multiple commands.
- The HAVE list is created by popping the first 32 commits
- from C_PENDING. Less can be supplied if C_PENDING empties.
+The HAVE list is created by popping the first 32 commits
+from C_PENDING. Less can be supplied if C_PENDING empties.
- If the client has sent 256 HAVE commits and has not yet
- received one of those back from S_COMMON, or the client has
- emptied C_PENDING it SHOULD include a "done" command to let
- the server know it won't proceed:
+If the client has sent 256 HAVE commits and has not yet
+received one of those back from S_COMMON, or the client has
+emptied C_PENDING it SHOULD include a "done" command to let
+the server know it won't proceed:
C: 0009done
- (s) Parse the git-upload-pack request:
-
- Verify all objects in WANT are directly reachable from refs.
-
- The server MAY walk backwards through history or through
- the reflog to permit slightly stale requests.
+S: Parse the git-upload-pack request:
- If no WANT objects are received, send an error:
+Verify all objects in WANT are directly reachable from refs.
-TODO: Define error if no want lines are requested.
+The server MAY walk backwards through history or through
+the reflog to permit slightly stale requests.
- If any WANT object is not reachable, send an error:
+If no WANT objects are received, send an error:
+TODO: Define error if no "want" lines are requested.
-TODO: Define error if an invalid want is requested.
+If any WANT object is not reachable, send an error:
+TODO: Define error if an invalid "want" is requested.
- Create an empty list, S_COMMON.
+Create an empty list, S_COMMON.
- If 'have' was sent:
+If "have" was sent:
- Loop through the objects in the order supplied by the client.
- For each object, if the server has the object reachable from
- a ref, add it to S_COMMON. If a commit is added to S_COMMON,
- do not add any ancestors, even if they also appear in HAVE.
+Loop through the objects in the order supplied by the client.
- (s) Send the git-upload-pack response:
+For each object, if the server has the object reachable from
+a ref, add it to S_COMMON. If a commit is added to S_COMMON,
+do not add any ancestors, even if they also appear in HAVE.
- If the server has found a closed set of objects to pack or the
- request ends with "done", it replies with the pack.
+S: Send the git-upload-pack response:
+If the server has found a closed set of objects to pack or the
+request ends with "done", it replies with the pack.
TODO: Document the pack based response
- S: PACK...
- The returned stream is the side-band-64k protocol supported
- by the git-upload-pack service, and the pack is embedded into
- stream 1. Progress messages from the server side MAY appear
- in stream 2.
+ S: PACK...
- Here a "closed set of objects" is defined to have at least
- one path from every WANT to at least one COMMON object.
+The returned stream is the side-band-64k protocol supported
+by the git-upload-pack service, and the pack is embedded into
+stream 1. Progress messages from the server side MAY appear
+in stream 2.
- If the server needs more information, it replies with a
- status continue response:
+Here a "closed set of objects" is defined to have at least
+one path from every WANT to at least one COMMON object.
+If the server needs more information, it replies with a
+status continue response:
TODO: Document the non-pack response
- (c) Parse the upload-pack response:
-
-TODO: Document parsing response
+C: Parse the upload-pack response:
+ TODO: Document parsing response
- Do another compute step.
+'Do another compute step.'
Smart Service git-receive-pack
------------------------------
-This service reads from the repository pointed to by $GIT_URL.
+This service reads from the repository pointed to by `$GIT_URL`.
Clients MUST first perform ref discovery with
-'$GIT_URL/info/refs?service=git-receive-pack'.
+`$GIT_URL/info/refs?service=git-receive-pack`.
C: POST $GIT_URL/git-receive-pack HTTP/1.0
C: Content-Type: application/x-git-receive-pack-request
@@ -479,10 +483,10 @@ Within the command portion of the request body clients SHOULD send
the id obtained through ref discovery as old_id.
update_request = command_list
- "PACK" <binary data>
+ "PACK" <binary data>
command_list = PKT-LINE(command NUL cap_list LF)
- *(command_pkt)
+ *(command_pkt)
command_pkt = PKT-LINE(command LF)
cap_list = *(SP capability) SP
--
1.8.5.2.msysgit.0
---
Thomas
^ permalink raw reply related [flat|nested] 5+ messages in thread