[PATCH 08/14] mention different variations around $GIT_URL

From

Tay Ray Chuan <rctay89@gmail.com>

Date

Sep 10, 2013, 17:07 UTC

Message-ID

<1378832878-12811-9-git-send-email-rctay89@gmail.com>

In-Reply-To

<1378832878-12811-8-git-send-email-rctay89@gmail.com>

Based on

  From:	Alex Blewitt <Alex.Blewitt@gmail.com>
  Message-ID: <loom.20091009T104530-586@post.gmane.org>

  Shawn O. Pearce <spearce <at> spearce.org> writes:

  > +URL Format
  > +----------
  > +
  > +URLs for Git repositories accessed by HTTP use the standard HTTP
  > +URL syntax documented by RFC 1738, so they are of the form:
  > +
  > +  http://<host>:<port>/<path>
  > +
  > +Within this documentation the placeholder $GIT_URL will stand for
  > +the http:// repository URL entered by the end-user.

  It's worth making clear here that $GIT_URL will be the path to the repository,
  rather than necessarily just the host upon which the server sits. Perhaps
  including an example, like http://example:8080/repos/example.git
  would make it clearer that there can be a path (and so leading to
  a request like http://example:8080/repos/example.git/info/refs?service=...

  It's also worth clarifying, therefore, that multiple repositories can be served
  by the same process (as with the git server today) by using different path(s).
  And for those that are interested in submodules, it's worth confirming that
  http://example/repos/master.git/child.git/info/refs?service= will ensure
  that the repository is the 'child' git rather than anything else.

Signed-off-by: Tay Ray Chuan <rctay89@gmail.com>
---
 Documentation/technical/http-protocol.txt | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index 2382384..d0955c2 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -22,15 +22,28 @@ URL Format
 URLs for Git repositories accessed by HTTP use the standard HTTP
 URL syntax documented by RFC 1738, so they are of the form:
 
-  http://<host>:<port>/<path>
+  http://<host>:<port>/<path>?<searchpart>
 
 Within this documentation the placeholder $GIT_URL will stand for
 the http:// repository URL entered by the end-user.
 
-Both the "smart" and "dumb" HTTP protocols used by Git operate
+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.
 
+An example of a dumb client requesting for a loose object:
+
+  $GIT_URL:     http://example.com:8080/git/repo.git
+  URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
+
+An example of a smart request to a catch-all gateway (notice how the
+'service' parameter is passed with '&', since a '?' was detected in
+$GIT_URL):
+
+  $GIT_URL:     http://example.com/daemon.cgi?svc=git&q=
+  URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack
+
 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
@@ -186,6 +199,11 @@ The request MUST contain exactly one query parameter,
 name the client wishes to contact to complete the operation.
 The request MUST NOT contain additional query parameters.
 
+TODO: "exactly" one query parameter may be too strict; see the catch-all
+gateway $GIT_URL for an example where more than one parameter is passed.
+In fact, the http client implementation in Git can handle similar
+$GIT_URLs, and thus may pass more than parameter to the server.
+
    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
 
    dumb server reply:

-- 
1.8.4.rc4.527.g303b16c