git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Marc Branchaud <marcnarc@xiplink.com>
Date
Jun 2, 2011, 14:21 UTC
Message-ID
<1307024488-10130-1-git-send-email-marcnarc@xiplink.com>
In-Reply-To
<7vsjrth4iy.fsf@alter.siamese.dyndns.org>
Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
---
 Documentation/git-submodule.txt |   17 +++++++++++++++--
 1 files changed, 15 insertions(+), 2 deletions(-)
On 11-06-01 12:59 PM, Junio C Hamano wrote:
Show 13 quoted lines
> Marc Branchaud <marcnarc@xiplink.com> writes:
> 
>> 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?
> 
> I do not necessarily think it is _solely_ about users. Another obvious
> example I left unsaid was what would happen when your project gets popular
> and gets mirrored to many places. Surely you need to advise people of
> alternate locations of the top-level, but what is recorded in .gitmodules
> will be relative to that top-level, so they do not have to be changed.
> Even if you have only one public repository, I would imagine that the same
> convenience would apply if you ever decide to switch the project hosting
> site.
I think I understand.  How does this version grab ya?
Show 27 quoted lines
> "Users can use a URL different from what was given by the maintainer" is
> merely an example; I doubt it deserves stressing that much.
> 
>> 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.
> 
> It is not "can not" but "do not", is it?  More importantly, I do not think
> it is limited to the case of relative path at all.

Well, the way the code currently works I think it's "can not". It'll happily accept an absolute file path but any relative path is either successfully "remotified" or the command fails.

(I also agree with Jens that there's utility in allowing local-filesystem submodules.)

		M.
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 1a16ff6..8daa33c 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -77,8 +77,21 @@ 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 submodule URLs provide flexibility in cases where the
+super-project and its submodules are hosted together.  For example,
+the relative submodule URLs remain valid if the repository collection
+moves to a different hosting site, or if the collection is mirrored at
+different sites.  Similarly, maintainers can conveniently make clones
+with a different URL (say an ssh:// URL) than users (who might use
+git:// 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.dirty
Previous: Phil HordNext: Marc Branchaud
Message 35 of 40 in “Tests for some submodule corner cases.”
  1. 0/2 Tests for some submodule corner cases.Marc Branchaud, May 30, 2011
  2. 1/2 Added a test for "submodule add" using a ../relative/path/to/the/submodule/repoMarc Branchaud, May 30, 2011
  3. 2/2 Added a test for "submodule status" when the submodule's working directory has deleted files.Marc Branchaud, May 30, 2011
  4. Jens LehmannMay 31, 2011
  5. submodule add: improve message when resolving a relative url failsJens Lehmann, May 31, 2011
  6. Marc BranchaudMay 31, 2011
  7. submodule add: improve message when resolving a relative url failsJens Lehmann, May 31, 2011
  8. Phil HordMay 31, 2011
  9. Marc BranchaudJun 1, 2011
  10. Phil HordJul 27, 2011
  11. Marc BranchaudJul 29, 2011
  12. Junio C HamanoMay 31, 2011
  13. Clarified how "git submodule add" handles relative paths.Marc Branchaud, Jun 1, 2011
  14. Junio C HamanoJun 1, 2011
  15. Jens LehmannJun 1, 2011
  16. Junio C HamanoJun 2, 2011
  17. Jens LehmannJun 3, 2011
  18. Junio C HamanoJun 3, 2011
  19. Mark LevedahlJun 4, 2011
  20. Jens LehmannJun 4, 2011
  21. Jens LehmannJun 4, 2011
  22. Junio C HamanoJun 5, 2011
  23. 0/3 submodule add: allow relative repository path even when no url is setJens Lehmann, Jun 6, 2011
  24. 1/3 submodule add: test failure when url is not configured in superprojectJens Lehmann, Jun 6, 2011
  25. 2/3 submodule add: allow relative repository path even when no url is setJens Lehmann, Jun 6, 2011
  26. 0/2 Improve "git submodule add" documentation.Marc Branchaud, Jun 6, 2011
  27. 1/2 More precisely described how "git submodule add" handles relative submodule URLs.Marc Branchaud, Jun 6, 2011
  28. 2/2 Moved paragraph describing the utility of relative submodule URLs.Marc Branchaud, Jun 6, 2011
  29. 3/3 submodule add: clean up duplicated codeJens Lehmann, Jun 6, 2011
  30. Junio C HamanoJun 6, 2011
  31. Marc BranchaudJun 6, 2011
  32. Jens LehmannJun 6, 2011
  33. Jens LehmannJun 7, 2011
  34. Phil HordJun 8, 2011
  35. [PATCHv2] Clarified how "git submodule add" handles relative paths.Marc Branchaud, Jun 2, 2011
  36. Marc BranchaudMay 31, 2011
  37. Jens LehmannMay 31, 2011
  38. Marc BranchaudJun 1, 2011
  39. Junio C HamanoJun 1, 2011
  40. Jens LehmannJun 1, 2011

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.