Re: Possible submodule or submodule documentation issue

[Jens Lehmann <Jens.Lehmann@web.de>]

Am 29.12.2011 03:50, schrieb Bill Zaumen:
> On Wed, 2011-12-28 at 20:47 +0100, Jens Lehmann wrote:
>> Am 27.12.2011 20:24, schrieb Bill Zaumen:
>> Hmm, the documentation says "the location relative to the
>> superproject’s origin repository", not the directory containing
>> it. This means you have to use ".." first to get out of the
>> repository itself, no?
> 
> The problem is  that the documentation also says that "<repository>
> is the URL of the new submodule's origin repository" and the wording
> would not make sense if the superproject's origin repository was not
> also named by a URL.  The rules for resolving relative URIs (a URL is
> a specific type of URI) are given in
> http://tools.ietf.org/html/rfc3986#section-5.4
> which has some examples:  if you resolve ./g against http://a/b/c/d;p?q
> you get http://a/b/c/g (the rules are purely syntactic and the syntax
> does not indicate that ".../foo.git" is a directory, and even the
> slashes do not definitively indicate directories in the sense of a
> file-system directory although they often do).

Thanks for that pointer, now I understand what you expected and why.

But as this behavior is in Git since September 2007 (f31a522a2d), I
suppose changing the behavior is a no-go. So what about clarifying
the docs:
---------8<-----------
[PATCH] docs: describe behavior of relative submodule URLs

Since the relative submodule URLs have been introduced in f31a522a2d, they
do not conform to the rules for resolving relative URIs but rather to
those of relative directories.

Document that behavior.

Signed-off-by: Jens Lehmann <Jens.Lehmann@web.de>
---
 Documentation/git-submodule.txt |    7 ++++++-
 1 files changed, 6 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 6ec3fef..b729649 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -79,7 +79,12 @@ to exist in the superproject. If <path> is not given, the
 <repository> is the URL of the new submodule's origin repository.
 This may be either an absolute URL, or (if it begins with ./
 or ../), the location relative to the superproject's origin
-repository. If the superproject doesn't have an origin configured
+repository (Please note that to specify a repository 'foo.git'
+which is located right next to a superproject 'bar.git', you'll
+have to use '../foo.git' instead of './foo.git' - as one might expect
+when following the rules for relative URLs - because the evaluation
+of relative URLs in Git is identical to that of relative directories).
+If the superproject doesn't have an origin configured
 the superproject is its own authoritative upstream and the current
 working directory is used instead.
 +
-- 
1.7.8.GIT