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:

<object type="image/svg+xml" data="fork.svg"></object>

But relative URLs are fine if you also fork the submodule(s):

<object type="image/svg+xml" data="mirror.svg"></object>

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:

<object type="image/svg+xml" data="clone.svg"></object>

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]]