Signed-off-by: Marc Branchaud <marcnarc@xxxxxxxxxxx> --- Documentation/git-submodule.txt | 13 +++++++++++-- 1 files changed, 11 insertions(+), 2 deletions(-) On 11-05-31 07:23 PM, Junio C Hamano wrote: > Marc Branchaud <marcnarc@xxxxxxxxxxx> writes: > >> Back when Junio accepted the original patch, he said "If you maintain and >> serve a set related projects you need to give the users a single URL (per >> where the user is and how to reach the server)." > > I think it was phrased badly. At least it should have s/need/only need/; > > Imagine ta project has many components, all of which are kept as > submodules of a single top-level superproject. You wrote and manage > everything; there is no borrowed code. In that context, imagine that I am > talking to the maintainer of that set of projects and calling the person > "you". > > By giving the URL for the top-level superproject, without having to give > any other URL for the subprojects, you can let your users fetch from you, > as everything underneath is relative. Another convenience this may give > you and your users is when the user needs to talk to you over different > transport. You may give "git://your.site/project.git" to the users, but > they may come to "http://your.site/project.git";. > > By recording submodule.<path>.url as relative to where your users happen > to have fetched your project in the superproject's .gitmodules file, your > users do not have to run around fixing URLs for 47 different component > submodules. > > At least I think that is what I meant back then. I see -- I was confused by the phrase "give ... a single URL" (since the URLs are already in the .gitmodules file, how is there ever any need to give more than one URL?). So this is really about saving the users the hassle of modifying all the URLs in the .gitmodules file. Does this patch document what you mean? M. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 1a16ff6..54dfebb 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -77,8 +77,17 @@ 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. +or ../) a URL relative to one of the superproject's remote +repostories: If the superprojet'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 +superproject's maintainer might use (e.g. the maintainer can use ssh:// +URLs while the users might use git:// URLs). With relative URLs in the +.gitmodules file, the users won't have to edit all the submodule URLs. ++ +*NOTE*: This means that you can *not* use a relative path to refer to a +repository in your local filesystem. + <path> is the relative location for the cloned submodule to exist in the superproject. If <path> does not exist, then the -- 1.7.5.3.1.ge85f0 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html