Possible submodule or submodule documentation issue

Possible submodule or submodule documentation issue

[Bill Zaumen]

For the 'add' command, the man page for get-submodule states

"<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."

and

"In either case, the given URL is recorded into .gitmodules for use by
subsequent users cloning the superproject. If the URL is given relative
to the superproject’s repository, the presumption is the superproject
and submodule repositories will be kept together in the same relative
location, and only the superproject’s URL needs to be provided:
git-submodule will correctly locate the submodule using the relative URL
in .gitmodules."

Based on that documentation, I tried the following sequence of commands:

git init --bare library.git
git init --bare library-pkg.git
git clone library.git
cd library;
echo hello > hello
git add hello
git commit -m "initial"
git push origin master
cd ..
git clone library-pkg.git
echo goodbye > goodbye
git add goodbye
git submodule add ./library.git src   <FAILS>
git submodule add ../library.git src  <WORKS>
git commit -a -m "initial pkg"
git push origin master

The documentation as written suggests that the first use of 
"git submodule add" is the one that should have worked because
library.git is in the same directory as the origin repository
library-pgk.git .  I didn't try moving the two .git directories
to a server to see if the behavior is the same in that case (my
test was using the local file system).

git --version  reports 1.7.1  (current version for my linux
distribution).

Re: Possible submodule or submodule documentation issue

[Jens Lehmann]

Am 27.12.2011 20:24, schrieb Bill Zaumen:
> For the 'add' command, the man page for get-submodule states
> 
> "<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."
> 
> and
> 
> "In either case, the given URL is recorded into .gitmodules for use by
> subsequent users cloning the superproject. If the URL is given relative
> to the superproject’s repository, the presumption is the superproject
> and submodule repositories will be kept together in the same relative
> location, and only the superproject’s URL needs to be provided:
> git-submodule will correctly locate the submodule using the relative URL
> in .gitmodules."
> 
> Based on that documentation, I tried the following sequence of commands:
> 
> git init --bare library.git
> git init --bare library-pkg.git
> git clone library.git
> cd library;
> echo hello > hello
> git add hello
> git commit -m "initial"
> git push origin master
> cd ..
> git clone library-pkg.git

I assume you did forget to add a "cd library-pkg" here.

> echo goodbye > goodbye
> git add goodbye
> git submodule add ./library.git src   <FAILS>

With Git 1.7.1 I get the following error message:

fatal: '/tmp/library-pkg.git/library.git' does not appear to be a git repository
fatal: The remote end hung up unexpectedly
Clone of '/tmp/library-pkg.git/library.git' into submodule path 'src' failed

Which is rather what I would have expected: Using "./library.git src"
implies the library living *inside* the "library-pkg.git" repo, not
next to it (and the error message shows that). "../library.git" is the
correct relative path, so the next command works as expected.

> git submodule add ../library.git src  <WORKS>
> git commit -a -m "initial pkg"
> git push origin master
> 
> The documentation as written suggests that the first use of 
> "git submodule add" is the one that should have worked because
> library.git is in the same directory as the origin repository
> library-pgk.git .  I didn't try moving the two .git directories
> to a server to see if the behavior is the same in that case (my
> test was using the local file system).

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?

Re: Possible submodule or submodule documentation issue

[Bill Zaumen]

On Wed, 2011-12-28 at 20:47 +0100, Jens Lehmann wrote:
> Am 27.12.2011 20:24, schrieb Bill Zaumen:
> > For the 'add' command, the man page for get-submodule states
> > 
> > "<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."
> >
...

> I assume you did forget to add a "cd library-pkg" here.

Yes, sorry for miscopying.

> 
> 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).  Also, I've enclosed a
Java program illustrating the correct behavior (a method in the Java
class library can resolve URIs so this is an independent test).

import java.net.*;
public class Test {
    public static void main(String argv[]) {
	try {
	    URI base = new URI("file:///home/USER/Projects/test/repo.git");
	    URI relative = new URI("./submodule.git");
	    URI absolute = base.resolve(relative);
	    System.out.println(relative.toString() + " -> "
			       +absolute.toString());
	    relative = new URI("../submodule.git");
	    absolute = base.resolve(relative);
	    System.out.println(relative.toString() + " -> "
			       +absolute.toString());
	} catch (Exception e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	System.exit(0);
    }
}

Re: Possible submodule or submodule documentation issue

[Jens Lehmann]

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

Re: Possible submodule or submodule documentation issue

[Bill Zaumen]

On Sun, 2012-01-01 at 16:13 +0100, Jens Lehmann wrote:
> Am 29.12.2011 03:50, schrieb Bill Zaumen:
> >  So what about clarifying
> the docs: ...

Clarifying the docs is a good solution given that a possibly large
number of existing repositories are dependent on the current behavior.

One way of explaining it is to say that "git first appends a
'/' to the superproject's origin URL if that URL does not already
end in a '/'. Relative URLs for submodules' origin repository are
resolved relative to this modified URL." Then the reader can simply
apply the normal URL rules.

I think either is OK - it's simply a judgment call as to which 
explanation is easiest for a typical git user to understand.

Re: Possible submodule or submodule documentation issue

[Junio C Hamano]

Will queue; thanks.