I like [[Git]] [submodules][] quite a bit, but they often get a [bad
rap][issues]. Most of the problems involve bad git hygiene (e.g. not
developing in feature branches) or limitations in the current
submodule implementation (e.g. it's hard to move submodules). Other
problems involve [not being able to fetch submodules with `git://`
URLs][no-git] (due to restrictive firewalls).
This last case is easily solved by using relative submodule URLs in
`.gitmodules`. I've been through the relative-vs.-absolute URL
argument [a][pycuda] [few][IPython] [times][IPython-2] now, so I
thought I'd write up my position for future reference. I prefer the
relative URL in:
[submodule "some-name"]
path = some/path
url = ../submod-repo.git
to the absolute URL in:
[submodule "some-name"]
path = some/path
url = git://example.net/submod-repo.git
Arguments in favor of relative URLs:
* Users get submodules over their preferred transport (`ssh://`,
`git://`, `https://`, …). Whatever transport you used to clone the
superproject will be recycled when you use `submodule init` to set
submodule URLs in your `.git/config`.
* No need to tweak `.gitmodules` if you mirror (or move) your
superproject Git hosting somewhere else (e.g. from `example.net` to
`elsewhere.com`).
* As a special case of the mirror/move situation, there's no need to
tweak `.gitmodules` in long-term forks. If I setup a local version
of the project and host it on my local box, my lab-mates can clone
my local superproject and use my local submodules without my having
to alter `.gitmodules`. Reducing trivial differences between forks
makes collaboration on substantive changes more likely.
The only argument I've heard in favor of absolute URLs is [Brian
Granger's][IPython-2] GitHub workflow:
* If a user forks `upstream/repo` to `username/repo` and then clones
their fork for local work, relative submodule URLs will not work
until they also fork the submodules into `username/`.
This workflow needs absolute URLs:
But relative URLs are fine if you also fork the submodule(s):
Personally, I only create a public repository (`username/repo`) after
cloning the central repository (`upstream/repo`). Several projects I
contribute too (such as [Git itself][email]) prefer changes via
[send-email][], in which case there is no need for contributors to
create public repositories at all. Relative URLs are also fine here:
Once you understand the trade-offs, picking absolute/relative is just
a political/engineering decision. I don't see any benefit to the
absolute-URL-only repo relationship, so I favor relative URLs. The
[IPython folks][MRK] felt that too many devs already used the
absolute-URL-only relationship, and that the relative-URL benefits
were not worth the cost of retraining those developers.
`
[submodules]: http://git-scm.com/docs/git-submodule
[issues]: http://git-scm.com/book/en/Git-Tools-Submodules#Issues-with-Submodules
[no-git]: http://thread.gmane.org/gmane.comp.python.ipython.devel/10287
[pycuda]: https://github.com/inducer/pycuda/commit/6ba1a47802ec896c6eccf3cebf1f9863989aeb4d
[IPython]: http://thread.gmane.org/gmane.comp.python.ipython.devel/10287/focus=10290
[IPython-2]: http://thread.gmane.org/gmane.comp.python.ipython.devel/10304
[email]: https://github.com/gitster/git/blob/master/Documentation/SubmittingPatches#L123
[send-email]: http://git-scm.com/docs/git-send-email
[MRK]: http://article.gmane.org/gmane.comp.python.ipython.devel/10307
[[!tag tags/git]]