Aw: [PATCH 1/2] create HTML for http-protocol.txt

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



 
please ignore this one

----- Original Nachricht ----
Von:     Thomas Ackermann <th.acker@xxxxxxxx>
An:      git@xxxxxxxxxxxxxxx
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@xxxxxxxx>
> ---
>  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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]