From: W. Trevor King Date: Sat, 13 Jul 2013 15:02:29 +0000 (-0400) Subject: posts:relative-submodules: Add a post promoting relative URLs X-Git-Url: http://git.tremily.us/?p=blog.git;a=commitdiff_plain;h=53ba1f47ada01855348e0f656c73ae1815510d90 posts:relative-submodules: Add a post promoting relative URLs --- diff --git a/posts/Relative_submodules.mdwn b/posts/Relative_submodules.mdwn new file mode 100644 index 0000000..1fa5188 --- /dev/null +++ b/posts/Relative_submodules.mdwn @@ -0,0 +1,80 @@ +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]]