Subject: Re: [PATCH] Clarified how "git submodule add" handles relative paths.

From: Jens Lehmann <[email-masked]>
Date: Sat, 04 Jun 2011 18:19:15 +0200

Am 04.06.2011 01:16, schrieb Junio C Hamano:
> Jens Lehmann <[email-masked]> writes:
> 
>> Now I understand this issue better I'd vote for leaving the relative url
>> like it is, comment it better in the man page and give a better error
>> message when that happens. After all this issue only surprised a few
>> people, mostly due to the lack of information in the error message and
>> man page, so I'd rather prefer to not change the behavior but the wording.
> 
> The "how about this" patch you are voting against (I am neutral by the
> way) is a response to your earlier "I have three use cases and the current
> implementation is forgetting the third", which in turn was a response to
> my "your third use case does not count, so the updated wording of the
> documentation is wrong---it should say 'do not', not 'cannot'".
> 
> So what should the updated document say?

I think that for the improved error message the v2 of my 'submodule add:
improve message when resolving a relative url fails' should be sufficient.

For the documentation I'd propose to apply Marc's 'Clarified how "git
submodule add" handles relative paths.' patch with the interdiff below
squashed in. It fixes a typo and explains that absolute paths are allowed
too (and join case three with the absolute url one by using a "file://"
scheme as default, which is what Mark hinted in his email).

If you want me to resend these two as an updated series just let me know.
---------- 8< ----------
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2294fa6..99d0a83 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -76,9 +76,10 @@ to exist in the superproject. If <path> is not given, the
 "/path/to/repo.git" and "foo" for "host.xz:foo/.git").
 +
 <repository> is the URL of the new submodule's origin repository.
-This may be either an absolute URL, or (if it begins with ./
+This may be either an absolute URL (when the scheme part is not
+specified "file://" is assumed) or (if it begins with ./
 or ../) a URL relative to one of the superproject's remote
-repostories:  If the superprojet's currently checked-out branch tracks
+repostories:  If the superproject's currently checked-out branch tracks
 a remote branch then that remote's URL is used, otherwise the "origin"
 remote's URL is used.  Relative URLs allow users to easily clone the
 superproject and its submodules using a different URL than what the