some fetchgit documentation

svn path=/nixpkgs/trunk/; revision=18283

pkgs/build-support/fetchgit/default.nix

@@ -1,6 +1,28 @@
 {stdenv, git}:
 {url, rev ? "HEAD", md5 ? "", sha256 ? ""}:
 
+/* NOTE:
+   fetchgit has one problem: git fetch only works for refs.
+   This is because fetching arbitrary (maybe dangling) commits may be a security risk
+   and checking whether a commit belongs to a ref is expensive. This may
+   change in the future when some caching is added to git (?)
+   Usually refs are either tags (refs/tags/*) or branches (refs/heads/*)
+   Cloning branches will make the hash check fail when there is an update.
+   But not all patches we want can be accessed by tags.
+
+   The workaround is getting the last n commits so that it's likly that they
+   still contain the hash we want.
+
+   for now : increase depth iteratively (TODO)
+
+   real fix: ask git folks to add a
+   git fetch $HASH contained in $BRANCH
+   facility because checking that $HASH is contained in $BRANCH is less
+   expensive than fetching --depth $N.
+   Even if git folks implemented this feature soon it may take years until
+   server admins start using the new version?
+*/
+
 stdenv.mkDerivation {
   name = "git-export";
   builder = ./builder.sh;