{"thread":{"id":"29255","subject":"Possible submodule or submodule documentation issue","startedAt":"2011-12-27T19:24:19Z","lastAt":"2012-01-03T20:48:21Z","messageCount":6,"participants":["Bill Zaumen","Jens Lehmann","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"181726","messageId":"1325013859.1987.65.camel@yos","threadId":"29255","inReplyTo":null,"subject":"Possible submodule or submodule documentation issue","fromName":"Bill Zaumen","fromEmail":"bill.zaumen+git@gmail.com","sentAt":"2011-12-27T19:24:19Z","receivedAt":"2011-12-27T19:24:19Z","isPatch":false,"sender":{"key":"bill.zaumen+git@gmail.com","avatar":null},"body":"For the 'add' command, the man page for get-submodule states\n\n\" is the URL of the new submodule’s origin repository. This\nmay be either an absolute URL, or (if it begins with ./ or ../), the\nlocation relative to the superproject’s origin repository.\"\n\nand\n\n\"In either case, the given URL is recorded into .gitmodules for use by\nsubsequent users cloning the superproject. If the URL is given relative\nto the superproject’s repository, the presumption is the superproject\nand submodule repositories will be kept together in the same relative\nlocation, and only the superproject’s URL needs to be provided:\ngit-submodule will correctly locate the submodule using the relative URL\nin .gitmodules.\"\n\nBased on that documentation, I tried the following sequence of commands:\n\ngit init --bare library.git\ngit init --bare library-pkg.git\ngit clone library.git\ncd library;\necho hello > hello\ngit add hello\ngit commit -m \"initial\"\ngit push origin master\ncd ..\ngit clone library-pkg.git\necho goodbye > goodbye\ngit add goodbye\ngit submodule add ./library.git src \ngit submodule add ../library.git src \ngit commit -a -m \"initial pkg\"\ngit push origin master\n\nThe documentation as written suggests that the first use of \n\"git submodule add\" is the one that should have worked because\nlibrary.git is in the same directory as the origin repository\nlibrary-pgk.git . I didn't try moving the two .git directories\nto a server to see if the behavior is the same in that case (my\ntest was using the local file system).\n\ngit --version reports 1.7.1 (current version for my linux\ndistribution).\n"},{"id":"181757","messageId":"4EFB725C.7030600@web.de","threadId":"29255","inReplyTo":"1325013859.1987.65.camel@yos","subject":"Re: Possible submodule or submodule documentation issue","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2011-12-28T19:47:40Z","receivedAt":"2011-12-28T19:47:40Z","isPatch":false,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Am 27.12.2011 20:24, schrieb Bill Zaumen:\n> For the 'add' command, the man page for get-submodule states\n> \n> \" is the URL of the new submodule’s origin repository. This\n> may be either an absolute URL, or (if it begins with ./ or ../), the\n> location relative to the superproject’s origin repository.\"\n> \n> and\n> \n> \"In either case, the given URL is recorded into .gitmodules for use by\n> subsequent users cloning the superproject. If the URL is given relative\n> to the superproject’s repository, the presumption is the superproject\n> and submodule repositories will be kept together in the same relative\n> location, and only the superproject’s URL needs to be provided:\n> git-submodule will correctly locate the submodule using the relative URL\n> in .gitmodules.\"\n> \n> Based on that documentation, I tried the following sequence of commands:\n> \n> git init --bare library.git\n> git init --bare library-pkg.git\n> git clone library.git\n> cd library;\n> echo hello > hello\n> git add hello\n> git commit -m \"initial\"\n> git push origin master\n> cd ..\n> git clone library-pkg.git\n\nI assume you did forget to add a \"cd library-pkg\" here.\n\n> echo goodbye > goodbye\n> git add goodbye\n> git submodule add ./library.git src \n\nWith Git 1.7.1 I get the following error message:\n\nfatal: '/tmp/library-pkg.git/library.git' does not appear to be a git repository\nfatal: The remote end hung up unexpectedly\nClone of '/tmp/library-pkg.git/library.git' into submodule path 'src' failed\n\nWhich is rather what I would have expected: Using \"./library.git src\"\nimplies the library living *inside* the \"library-pkg.git\" repo, not\nnext to it (and the error message shows that). \"../library.git\" is the\ncorrect relative path, so the next command works as expected.\n\n> git submodule add ../library.git src \n> git commit -a -m \"initial pkg\"\n> git push origin master\n> \n> The documentation as written suggests that the first use of \n> \"git submodule add\" is the one that should have worked because\n> library.git is in the same directory as the origin repository\n> library-pgk.git . I didn't try moving the two .git directories\n> to a server to see if the behavior is the same in that case (my\n> test was using the local file system).\n\nHmm, the documentation says \"the location relative to the\nsuperproject’s origin repository\", not the directory containing\nit. This means you have to use \"..\" first to get out of the\nrepository itself, no?\n"},{"id":"181770","messageId":"1325127030.1681.35.camel@yos","threadId":"29255","inReplyTo":"4EFB725C.7030600@web.de","subject":"Re: Possible submodule or submodule documentation issue","fromName":"Bill Zaumen","fromEmail":"bill.zaumen+git@gmail.com","sentAt":"2011-12-29T02:50:30Z","receivedAt":"2011-12-29T02:50:30Z","isPatch":false,"sender":{"key":"bill.zaumen+git@gmail.com","avatar":null},"body":"On Wed, 2011-12-28 at 20:47 +0100, Jens Lehmann wrote:\n> Am 27.12.2011 20:24, schrieb Bill Zaumen:\n> > For the 'add' command, the man page for get-submodule states\n> > \n> > \" is the URL of the new submodule’s origin repository. This\n> > may be either an absolute URL, or (if it begins with ./ or ../), the\n> > location relative to the superproject’s origin repository.\"\n> >\n...\n\n> I assume you did forget to add a \"cd library-pkg\" here.\n\nYes, sorry for miscopying.\n\n> \n> Hmm, the documentation says \"the location relative to the\n> superproject’s origin repository\", not the directory containing\n> it. This means you have to use \"..\" first to get out of the\n> repository itself, no?\n\nThe problem is that the documentation also says that \"\nis the URL of the new submodule's origin repository\" and the wording\nwould not make sense if the superproject's origin repository was not\nalso named by a URL. The rules for resolving relative URIs (a URL is\na specific type of URI) are given in\nhttp://tools.ietf.org/html/rfc3986#section-5.4\nwhich has some examples: if you resolve ./g against http://a/b/c/d;p?q\nyou get http://a/b/c/g (the rules are purely syntactic and the syntax\ndoes not indicate that \".../foo.git\" is a directory, and even the\nslashes do not definitively indicate directories in the sense of a\nfile-system directory although they often do). Also, I've enclosed a\nJava program illustrating the correct behavior (a method in the Java\nclass library can resolve URIs so this is an independent test).\n\nimport java.net.*;\npublic class Test {\n public static void main(String argv[]) {\n\ttry {\n\t URI base = new URI(\"file:///home/USER/Projects/test/repo.git\");\n\t URI relative = new URI(\"./submodule.git\");\n\t URI absolute = base.resolve(relative);\n\t System.out.println(relative.toString() + \" -> \"\n\t\t\t +absolute.toString());\n\t relative = new URI(\"../submodule.git\");\n\t absolute = base.resolve(relative);\n\t System.out.println(relative.toString() + \" -> \"\n\t\t\t +absolute.toString());\n\t} catch (Exception e) {\n\t e.printStackTrace();\n\t System.exit(1);\n\t}\n\tSystem.exit(0);\n }\n}\n"},{"id":"181824","messageId":"4F00780C.7090801@web.de","threadId":"29255","inReplyTo":"1325127030.1681.35.camel@yos","subject":"Re: Possible submodule or submodule documentation issue","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2012-01-01T15:13:16Z","receivedAt":"2012-01-01T15:13:16Z","isPatch":false,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Am 29.12.2011 03:50, schrieb Bill Zaumen:\n> On Wed, 2011-12-28 at 20:47 +0100, Jens Lehmann wrote:\n>> Am 27.12.2011 20:24, schrieb Bill Zaumen:\n>> Hmm, the documentation says \"the location relative to the\n>> superproject’s origin repository\", not the directory containing\n>> it. This means you have to use \"..\" first to get out of the\n>> repository itself, no?\n> \n> The problem is that the documentation also says that \"\n> is the URL of the new submodule's origin repository\" and the wording\n> would not make sense if the superproject's origin repository was not\n> also named by a URL. The rules for resolving relative URIs (a URL is\n> a specific type of URI) are given in\n> http://tools.ietf.org/html/rfc3986#section-5.4\n> which has some examples: if you resolve ./g against http://a/b/c/d;p?q\n> you get http://a/b/c/g (the rules are purely syntactic and the syntax\n> does not indicate that \".../foo.git\" is a directory, and even the\n> slashes do not definitively indicate directories in the sense of a\n> file-system directory although they often do).\n\nThanks for that pointer, now I understand what you expected and why.\n\nBut as this behavior is in Git since September 2007 (f31a522a2d), I\nsuppose changing the behavior is a no-go. So what about clarifying\nthe docs:\n---------8<-----------\n[PATCH] docs: describe behavior of relative submodule URLs\n\nSince the relative submodule URLs have been introduced in f31a522a2d, they\ndo not conform to the rules for resolving relative URIs but rather to\nthose of relative directories.\n\nDocument that behavior.\n\nSigned-off-by: Jens Lehmann \n---\n Documentation/git-submodule.txt | 7 ++++++-\n 1 files changed, 6 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 6ec3fef..b729649 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -79,7 +79,12 @@ to exist in the superproject. If is not given, the\n is the URL of the new submodule's origin repository.\n This may be either an absolute URL, or (if it begins with ./\n or ../), the location relative to the superproject's origin\n-repository. If the superproject doesn't have an origin configured\n+repository (Please note that to specify a repository 'foo.git'\n+which is located right next to a superproject 'bar.git', you'll\n+have to use '../foo.git' instead of './foo.git' - as one might expect\n+when following the rules for relative URLs - because the evaluation\n+of relative URLs in Git is identical to that of relative directories).\n+If the superproject doesn't have an origin configured\n the superproject is its own authoritative upstream and the current\n working directory is used instead.\n +\n-- \n1.7.8.GIT\n"},{"id":"181833","messageId":"1325476413.1718.20.camel@yos","threadId":"29255","inReplyTo":"4F00780C.7090801@web.de","subject":"Re: Possible submodule or submodule documentation issue","fromName":"Bill Zaumen","fromEmail":"bill.zaumen+git@gmail.com","sentAt":"2012-01-02T03:53:33Z","receivedAt":"2012-01-02T03:53:33Z","isPatch":false,"sender":{"key":"bill.zaumen+git@gmail.com","avatar":null},"body":"On Sun, 2012-01-01 at 16:13 +0100, Jens Lehmann wrote:\n> Am 29.12.2011 03:50, schrieb Bill Zaumen:\n> > So what about clarifying\n> the docs: ...\n\nClarifying the docs is a good solution given that a possibly large\nnumber of existing repositories are dependent on the current behavior.\n\nOne way of explaining it is to say that \"git first appends a\n'/' to the superproject's origin URL if that URL does not already\nend in a '/'. Relative URLs for submodules' origin repository are\nresolved relative to this modified URL.\" Then the reader can simply\napply the normal URL rules.\n\nI think either is OK - it's simply a judgment call as to which \nexplanation is easiest for a typical git user to understand.\n"},{"id":"181894","messageId":"7vvcosseay.fsf@alter.siamese.dyndns.org","threadId":"29255","inReplyTo":"4F00780C.7090801@web.de","subject":"Re: Possible submodule or submodule documentation issue","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-01-03T20:48:21Z","receivedAt":"2012-01-03T20:48:21Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Will queue; thanks.\n"}]}