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 (file)
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:
+
+<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]]