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

From

Marc Branchaud <marcnarc@xiplink.com>

Date

Jun 1, 2011, 15:56 UTC

Message-ID

<1306943792-1825-1-git-send-email-marcnarc@xiplink.com>

In-Reply-To

<7vaae2ihe1.fsf@alter.siamese.dyndns.org>

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
---
 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@xiplink.com> 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.

		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