posts/Relative_submodules.mdwn

   1 I like [[Git]] [submodules][] quite a bit, but they often get a [bad
   2 rap][issues].  Most of the problems involve bad git hygiene (e.g. not
   3 developing in feature branches) or limitations in the current
   4 submodule implementation (e.g. it's hard to move submodules).  Other
   5 problems involve [not being able to fetch submodules with `git://`
   6 URLs][no-git] (due to restrictive firewalls).
   7
   8 This last case is easily solved by using relative submodule URLs in
   9 `.gitmodules`.  I've been through the relative-vs.-absolute URL
  10 argument [a][pycuda] [few][IPython] [times][IPython-2] now, so I
  11 thought I'd write up my position for future reference.  I prefer the
  12 relative URL in:
  13
  14     [submodule "some-name"]
  15       path = some/path
  16       url = ../submod-repo.git
  17
  18 to the absolute URL in:
  19
  20     [submodule "some-name"]
  21       path = some/path
  22       url = git://example.net/submod-repo.git
  23
  24 Arguments in favor of relative URLs:
  25
  26 * Users get submodules over their preferred transport (`ssh://`,
  27   `git://`, `https://`, …).  Whatever transport you used to clone the
  28   superproject will be recycled when you use `submodule init` to set
  29   submodule URLs in your `.git/config`.
  30 * No need to tweak `.gitmodules` if you mirror (or move) your
  31   superproject Git hosting somewhere else (e.g. from `example.net` to
  32   `elsewhere.com`).
  33 * As a special case of the mirror/move situation, there's no need to
  34   tweak `.gitmodules` in long-term forks.  If I setup a local version
  35   of the project and host it on my local box, my lab-mates can clone
  36   my local superproject and use my local submodules without my having
  37   to alter `.gitmodules`.  Reducing trivial differences between forks
  38   makes collaboration on substantive changes more likely.
  39
  40 The only argument I've heard in favor of absolute URLs is [Brian
  41 Granger's][IPython-2] GitHub workflow:
  42
  43 * If a user forks `upstream/repo` to `username/repo` and then clones
  44   their fork for local work, relative submodule URLs will not work
  45   until they also fork the submodules into `username/`.
  46
  47 This workflow needs absolute URLs:
  48
  49 <object type="image/svg+xml" data="fork.svg"></object>
  50
  51 But relative URLs are fine if you also fork the submodule(s):
  52
  53 <object type="image/svg+xml" data="mirror.svg"></object>
  54
  55 Personally, I only create a public repository (`username/repo`) after
  56 cloning the central repository (`upstream/repo`).  Several projects I
  57 contribute too (such as [Git itself][email]) prefer changes via
  58 [send-email][], in which case there is no need for contributors to
  59 create public repositories at all.  Relative URLs are also fine here:
  60
  61 <object type="image/svg+xml" data="clone.svg"></object>
  62
  63 Once you understand the trade-offs, picking absolute/relative is just
  64 a political/engineering decision.  I don't see any benefit to the
  65 absolute-URL-only repo relationship, so I favor relative URLs.  The
  66 [IPython folks][MRK] felt that too many devs already used the
  67 absolute-URL-only relationship, and that the relative-URL benefits
  68 were not worth the cost of retraining those developers.
  69 `
  70 [submodules]: http://git-scm.com/docs/git-submodule
  71 [issues]: http://git-scm.com/book/en/Git-Tools-Submodules#Issues-with-Submodules
  72 [no-git]: http://thread.gmane.org/gmane.comp.python.ipython.devel/10287
  73 [pycuda]: https://github.com/inducer/pycuda/commit/6ba1a47802ec896c6eccf3cebf1f9863989aeb4d
  74 [IPython]: http://thread.gmane.org/gmane.comp.python.ipython.devel/10287/focus=10290
  75 [IPython-2]: http://thread.gmane.org/gmane.comp.python.ipython.devel/10304
  76 [email]: https://github.com/gitster/git/blob/master/Documentation/SubmittingPatches#L123
  77 [send-email]: http://git-scm.com/docs/git-send-email
  78 [MRK]: http://article.gmane.org/gmane.comp.python.ipython.devel/10307
  79
  80 [[!tag tags/git]]