From edf78fcb6a144444cdea9897f87d486252a1e090 Mon Sep 17 00:00:00 2001
From: Marc Weber <marco-oweber@gmx.de>
Date: Sun, 8 Nov 2009 03:02:10 +0000
Subject: [PATCH] some fetchgit documentation

svn path=/nixpkgs/trunk/; revision=18283
---
 pkgs/build-support/fetchgit/default.nix | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/pkgs/build-support/fetchgit/default.nix b/pkgs/build-support/fetchgit/default.nix
index 6966b5c0bf9b..8fd86cd24815 100644
--- a/pkgs/build-support/fetchgit/default.nix
+++ b/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;