Possible submodule or submodule documentation issue

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

Am 27.12.2011 20:24, schrieb Bill Zaumen:

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

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.

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?

On Wed, 2011-12-28 at 20:47 +0100, Jens Lehmann wrote:

...

Yes, sorry for miscopying.

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);
    }
}

Am 29.12.2011 03:50, schrieb Bill Zaumen:

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(-)

On Sun, 2012-01-01 at 16:13 +0100, Jens Lehmann wrote:

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.

Will queue; thanks.