Added SymbolicReference and HEAD type to better represent these special types of references and allow special handling

Head.reset now is an instance method of HEAD type
Concatenated all reference specific tests into test_refs
started to fix tests breaking now because of changed interface

Author: Byron

CHANGES

@@ -87,9 +87,12 @@ Index
 * A new Index class allows to read and write index files directly, and to perform
   simple two and three way merges based on an arbitrary index.
 
-Refs
-----
-* Will dynmically retrieve their object at the time of query to assure the information 
+Referernces
+------------
+* References are object that point to a Commit
+* SymbolicReference are a pointer to a Reference Object, which itself points to a specific
+  Commit
+* They will dynmically retrieve their object at the time of query to assure the information 
   is actual. Recently objects would be cached, hence ref object not be safely kept 
   persistent.
 

TODO

@@ -58,14 +58,12 @@ Index
   creating several tree objects, so in the end it might be slower. 
   Hmm, probably its okay to use the command unless we go c(++)
 
-
-Head.reset
-----------
-* Should better be an instance method. Problem was that there is no class specifying
-  the HEAD  - in a way reset would always effect the active branch.
-  Probably it would be okay to have a special type called SymbolicReference
-  which represents items like HEAD. These could naturally carry the reset 
-  instance method.
+Refs
+-----
+* If the HEAD is detached as it points to a specific commit, its not technically
+  a symbolic reference anymore. Currently, we cannot handle this that well 
+  as we do not check for this case. This should be added though as it is 
+  valid to have a detached head in some cases.
 
 Remote
 ------

lib/git/refs.py

@@ -6,6 +6,7 @@
 """
 Module containing all ref based objects
 """
+import os
 from objects.base import Object
 from objects.utils import get_object_type_by_name
 from utils import LazyMixin, Iterable
@@ -31,6 +32,9 @@ def __init__(self, repo, path, object = None):
 		``object``
 			Object instance, will be retrieved on demand if None
 		"""
+		if not path.startswith(self._common_path_default):
+			raise ValueError("Cannot instantiate %s Reference from path %s" % ( self.__class__.__name__, path ))
+			
 		self.repo = repo
 		self.path = path
 		if object is not None:
@@ -75,6 +79,17 @@ def object(self):
 		# have to be dynamic here as we may be a tag which can point to anything
 		# Our path will be resolved to the hexsha which will be used accordingly
 		return Object.new(self.repo, self.path)
+		
+	@property
+	def commit(self):
+		"""
+		Returns
+			Commit object the head points to
+		"""
+		commit = self.object
+		if commit.type != "commit":
+			raise TypeError("Object of reference %s did not point to a commit" % self)
+		return commit
 
 	@classmethod
 	def iter_items(cls, repo, common_path = None, **kwargs):
@@ -112,6 +127,29 @@ def iter_items(cls, repo, common_path = None, **kwargs):
 
 		output = repo.git.for_each_ref(common_path, **options)
 		return cls._iter_from_stream(repo, iter(output.splitlines()))
+		
+	@classmethod
+	def from_path(cls, repo, path):
+		"""
+		Return
+			Instance of type Reference, Head, Tag, SymbolicReference or HEAD
+			depending on the given path
+		"""
+		if path == 'HEAD':
+			return HEAD(repo, path)
+		
+		if '/' not in path:
+			return SymbolicReference(repo, path)
+			
+		for ref_type in (Head, RemoteReference, TagReference, Reference):
+			try:
+				return ref_type(repo, path)
+			except ValueError:
+				pass
+			# END exception handling
+		# END for each type to try
+		raise ValueError("Could not find reference type suitable to handle path %r" % path)
+		
 
 	@classmethod
 	def _iter_from_stream(cls, repo, stream):
@@ -145,47 +183,91 @@ def _from_string(cls, repo, line):
 		# return cls(repo, full_path, obj)
 
 
-class Head(Reference):
+class SymbolicReference(object):
 	"""
-	A Head is a named reference to a Commit. Every Head instance contains a name
-	and a Commit object.
-
-	Examples::
-
-		>>> repo = Repo("/path/to/repo")
-		>>> head = repo.heads[0]
-
-		>>> head.name		
-		'master'
-
-		>>> head.commit		
-		<git.Commit "1c09f116cbc2cb4100fb6935bb162daa4723f455">
-
-		>>> head.commit.id
-		'1c09f116cbc2cb4100fb6935bb162daa4723f455'
+	Represents a special case of a reference such that this reference is symbolic.
+	It does not point to a specific commit, but to another Head, which itself 
+	specifies a commit.
+	
+	A typical example for a symbolic reference is HEAD.
 	"""
-	_common_path_default = "refs/heads"
+	__slots__ = ("repo", "name")
 
+	def __init__(self, repo, name):
+		if '/' in name:
+			raise ValueError("SymbolicReferences are not located within a directory, got %s" % name)
+		self.repo = repo
+		self.name = name
+		
+	def __str__(self):
+		return self.name
+		
+	def __repr__(self):
+		return '<git.%s "%s">' % (self.__class__.__name__, self.name)
+		
+	def __eq__(self, other):
+		return self.name == other.name
+		
+	def __ne__(self, other):
+		return not ( self == other )
+		
+	def __hash__(self):
+		return hash(self.name)
+		
 	@property
-	def commit(self):
+	def reference(self):
 		"""
 		Returns
-			Commit object the head points to
+			Reference Object we point to
 		"""
-		return self.object
+		fp = open(os.path.join(self.repo.path, self.name), 'r')
+		try:
+			tokens = fp.readline().split(' ')
+			if tokens[0] != 'ref:':
+				raise TypeError("%s is a detached symbolic reference as it points to %r" % tokens[0])
+			return Reference.from_path(self.repo, tokens[1])
+		finally:
+			fp.close()
 
-	@classmethod
-	def reset(cls, repo, commit='HEAD', index=True, working_tree = False, 
+	# alias
+	ref = reference
+		
+	@property
+	def is_detached(self):
+		"""
+		Returns
+			True if we are a detached reference, hence we point to a specific commit
+			instead to another reference
+		"""
+		try:
+			self.reference
+			return False
+		except TypeError:
+			return True
+	
+	
+class HEAD(SymbolicReference):
+	"""
+	Special case of a Symbolic Reference as it represents the repository's 
+	HEAD reference.
+	"""
+	__slots__ = tuple()
+	
+	def __init__(self, repo, name):
+		if name != 'HEAD':
+			raise ValueError("HEAD instance must point to 'HEAD', got %s" % name)
+		super(HEAD, self).__init__(repo, name)
+	
+	
+	def reset(self, commit='HEAD', index=True, working_tree = False, 
 				paths=None, **kwargs):
 		"""
-		Reset the current head to the given commit optionally synchronizing 
+		Reset our HEAD to the given commit optionally synchronizing 
 		the index and working tree.
 		
-		``repo``
-			Repository containing commit
-			
 		``commit``
-			Commit object, Reference Object or string identifying a revision
+			Commit object, Reference Object or string identifying a revision we 
+			should reset HEAD to.
 			
 		``index``
 			If True, the index will be set to match the given commit. Otherwise
@@ -204,7 +286,7 @@ def reset(cls, repo, commit='HEAD', index=True, working_tree = False,
 			Additional arguments passed to git-reset. 
 		
 		Returns
-			Head pointing to the specified commit
+			self
 		"""
 		mode = "--soft"
 		if index:
@@ -219,9 +301,32 @@ def reset(cls, repo, commit='HEAD', index=True, working_tree = False,
 		repo.git.reset(mode, commit, paths, **kwargs)
 
 		# we always point to the active branch as it is the one changing
-		return repo.active_branch
+		self
+	
+
+class Head(Reference):
+	"""
+	A Head is a named reference to a Commit. Every Head instance contains a name
+	and a Commit object.
+
+	Examples::
+
+		>>> repo = Repo("/path/to/repo")
+		>>> head = repo.heads[0]
+
+		>>> head.name		
+		'master'
+
+		>>> head.commit		
+		<git.Commit "1c09f116cbc2cb4100fb6935bb162daa4723f455">
+
+		>>> head.commit.id
+		'1c09f116cbc2cb4100fb6935bb162daa4723f455'
+	"""
+	_common_path_default = "refs/heads"
+	
 
-class TagReference(Head):
+class TagReference(Reference):
 	"""
 	Class representing a lightweight tag reference which either points to a commit 
 	or to a tag object. In the latter case additional information, like the signature
@@ -230,7 +335,7 @@ class TagReference(Head):
 	This tag object will always point to a commit object, but may carray additional
 	information in a tag object::
 	
-	 tagref = TagRef.list_items(repo)[0]
+	 tagref = TagReference.list_items(repo)[0]
 	 print tagref.commit.message
 	 if tagref.tag is not None:
 		print tagref.tag.message

lib/git/repo.py

@@ -147,15 +147,12 @@ def heads(self):
 	branches = heads
 
 	@property
-	def head(self,path="HEAD"):
+	def head(self):
 		"""
 		Return
-			Head Object, reference pointing to commit
-			
-		``path``
-			path to the head or its name, i.e. master or heads/master
+			HEAD Object pointing to the current head reference
 		"""
-		return Head(self,path)
+		return HEAD(self,'HEAD')
 
 	@property
 	def remotes(self):
@@ -486,8 +483,7 @@ def active_branch(self):
 		Returns
 			Head to the active branch
 		"""
-		return Head( self, self.git.symbolic_ref('HEAD').strip() )
-		
+		return self.head.reference
 
 	def blame(self, rev, file):
 		"""

test/git/test_base.py

@@ -66,50 +66,6 @@ def test_base_object(self):
 		assert len(s|s) == num_objs
 		assert num_index_objs == 2
 
-		
-	def test_tags(self):
-		# tag refs can point to tag objects or to commits
-		s = set()
-		ref_count = 0
-		for ref in chain(self.rorepo.tags, self.rorepo.heads):
-			ref_count += 1
-			assert isinstance(ref, refs.Reference)
-			assert str(ref) == ref.name
-			assert repr(ref)
-			assert ref == ref
-			assert not ref != ref
-			s.add(ref)
-		# END for each ref
-		assert len(s) == ref_count
-		assert len(s|s) == ref_count
-		
-	def test_heads(self):
-		# see how it dynmically updates its object
-		for head in self.rorepo.heads:
-			head.name
-			head.path
-			prev_object = head.object
-			cur_object = head.object
-			assert prev_object == cur_object		# represent the same git object
-			assert prev_object is not cur_object	# but are different instances
-		# END for each head
-		
-	@with_rw_repo('0.1.6')
-	def test_head_reset(self, rw_repo):
-		cur_head = rw_repo.head
-		new_head_commit = cur_head.commit.parents[0]
-		reset_head = Head.reset(rw_repo, new_head_commit, index=True)	# index only
-		assert reset_head.commit == new_head_commit
-		
-		self.failUnlessRaises(ValueError, Head.reset, rw_repo, new_head_commit, index=False, working_tree=True)
-		new_head_commit = new_head_commit.parents[0]
-		reset_head = Head.reset(rw_repo, new_head_commit, index=True, working_tree=True)	# index + wt
-		assert reset_head.commit == new_head_commit
-		
-		# paths
-		Head.reset(rw_repo, new_head_commit, paths = "lib")
-		
-		
 	def test_get_object_type_by_name(self):
 		for tname in base.Object.TYPES:
 			assert base.Object in get_object_type_by_name(tname).mro()
@@ -119,7 +75,7 @@ def test_get_object_type_by_name(self):
 
 	def test_object_resolution(self):
 		# objects must be resolved to shas so they compare equal
-		assert self.rorepo.head.object == self.rorepo.active_branch.object
+		assert self.rorepo.head.reference.object == self.rorepo.active_branch.object
 
 	@with_bare_rw_repo
 	def test_with_bare_rw_repo(self, bare_rw_repo):

test/git/test_commit.py

@@ -64,7 +64,7 @@ def test_rev_list_bisect_all(self, git):
 			assert_equal(sha1, commit.id)
 
 	def test_count(self):
-		assert self.rorepo.tag('0.1.5').commit.count( ) == 141
+		assert self.rorepo.tag('refs/tags/0.1.5').commit.count( ) == 141
 
 	def test_list(self):
 		assert isinstance(Commit.list_items(self.rorepo, '0.1.5', max_count=5)['5117c9c8a4d3af19a9958677e45cda9269de1541'], Commit)