Added ref implementation and tried to fix it so that it has a chance of running. Currently it requires an object implementation which will be ported next. None of the tests is expected to run yet.

Author: Byron

gitdb/db/base.py

@@ -419,7 +419,7 @@ class TransportDBMixin(object):
 
 	#{ Interface
 
-	def fetch(self, url, refspecs, progress=None):
+	def fetch(self, url, refspecs, progress=None, **kwargs):
 		"""Fetch the objects defined by the given refspec from the given url.
 		:param url: url identifying the source of the objects. It may also be 
 			a symbol from which the respective url can be resolved, like the
@@ -428,7 +428,9 @@ def fetch(self, url, refspecs, progress=None):
 		:param refspecs: iterable of reference specifiers or RefSpec instance, 
 			identifying the references to be fetch from the remote.
 		:param progress: callable which receives progress messages for user consumption
-		:return: List of binary object shas matching the respective remote ref which 
+		:param kwargs: may be used for additional parameters that the actual implementation could 
+			find useful.
+		:return: List of FetchInfo compatible instances which provide information about what 
 			was previously fetched, in the order of the input refspecs.
 		:note: even if the operation fails, one of the returned FetchInfo instances
 			may still contain errors or failures in only part of the refspecs.
@@ -437,14 +439,16 @@ def fetch(self, url, refspecs, progress=None):
 		"""
 		raise NotImplementedError()
 
-	def push(self, url, refspecs, progress=None):
+	def push(self, url, refspecs, progress=None, **kwargs):
 		"""Transport the objects identified by the given refspec to the remote
 		at the given url.
 		:param url: Decribes the location which is to receive the objects
 			see fetch() for more details
 		:param refspecs: iterable of refspecs strings or RefSpec instances
 			to identify the objects to push
 		:param progress: see fetch() 
+		:param kwargs: additional arguments which may be provided by the caller
+			as they may be useful to the actual implementation
 		:todo: what to return ?
 		:raise: if any issue arises during transport or if the url cannot be handled"""
 		raise NotImplementedError()

gitdb/ref/__init__.py

@@ -0,0 +1,21 @@
+
+# import all modules in order, fix the names they require
+from symbolic import *
+from reference import *
+from head import *
+from tag import *
+from remote import *
+
+# name fixes
+import head
+head.Head.RemoteReferenceCls = RemoteReference
+del(head)
+
+
+import symbolic
+for item in (HEAD, Head, RemoteReference, TagReference, Reference, SymbolicReference):
+	setattr(symbolic.SymbolicReference, item.__name__+'Cls', item)
+del(symbolic)
+
+
+from log import *

gitdb/ref/head.py

@@ -0,0 +1,106 @@
+from symbolic import SymbolicReference
+from reference import Reference
+from gitdb.config import SectionConstraint
+from gitdb.util import join_path
+
+__all__ = ["HEAD", "Head"]
+
+
+	
+class HEAD(SymbolicReference):
+	"""Special case of a Symbolic Reference as it represents the repository's 
+	HEAD reference."""
+	_HEAD_NAME = 'HEAD'
+	_ORIG_HEAD_NAME = 'ORIG_HEAD'
+	__slots__ = tuple()
+	
+	def __init__(self, repo, path=_HEAD_NAME):
+		if path != self._HEAD_NAME:
+			raise ValueError("HEAD instance must point to %r, got %r" % (self._HEAD_NAME, path))
+		super(HEAD, self).__init__(repo, path)
+	
+	def orig_head(self):
+		"""
+		:return: SymbolicReference pointing at the ORIG_HEAD, which is maintained 
+			to contain the previous value of HEAD"""
+		return SymbolicReference(self.repo, self._ORIG_HEAD_NAME)
+		
+
+class Head(Reference):
+	"""A Head is a named reference to a Commit"""
+	_common_path_default = "refs/heads"
+	k_config_remote = "remote"
+	k_config_remote_ref = "merge"			# branch to merge from remote
+	
+	# will be set by init method !
+	RemoteReferenceCls = None
+	
+	#{ Configuration
+	
+	def set_tracking_branch(self, remote_reference):
+		"""
+		Configure this branch to track the given remote reference. This will alter
+			this branch's configuration accordingly.
+		
+		:param remote_reference: The remote reference to track or None to untrack 
+			any references
+		:return: self"""
+		if remote_reference is not None and not isinstance(remote_reference, self.RemoteReferenceCls):
+			raise ValueError("Incorrect parameter type: %r" % remote_reference)
+		# END handle type
+		
+		writer = self.config_writer()
+		if remote_reference is None:
+			writer.remove_option(self.k_config_remote)
+			writer.remove_option(self.k_config_remote_ref)
+			if len(writer.options()) == 0:
+				writer.remove_section()
+			# END handle remove section
+		else:
+			writer.set_value(self.k_config_remote, remote_reference.remote_name)
+			writer.set_value(self.k_config_remote_ref, Head.to_full_path(remote_reference.remote_head))
+		# END handle ref value
+		
+		return self
+		
+	def tracking_branch(self):
+		"""
+		:return: The remote_reference we are tracking, or None if we are 
+			not a tracking branch"""
+		reader = self.config_reader()
+		if reader.has_option(self.k_config_remote) and reader.has_option(self.k_config_remote_ref):
+			ref = Head(self.repo, Head.to_full_path(reader.get_value(self.k_config_remote_ref)))
+			remote_refpath = self.RemoteReferenceCls.to_full_path(join_path(reader.get_value(self.k_config_remote), ref.name))
+			return self.RemoteReferenceCls(self.repo, remote_refpath)
+		# END handle have tracking branch
+		
+		# we are not a tracking branch
+		return None
+	
+		
+	#{ Configruation
+	
+	def _config_parser(self, read_only):
+		if read_only:
+			parser = self.repo.config_reader()
+		else:
+			parser = self.repo.config_writer()
+		# END handle parser instance
+		
+		return SectionConstraint(parser, 'branch "%s"' % self.name)
+	
+	def config_reader(self):
+		"""
+		:return: A configuration parser instance constrained to only read 
+			this instance's values"""
+		return self._config_parser(read_only=True)
+		
+	def config_writer(self):
+		"""
+		:return: A configuration writer instance with read-and write acccess
+			to options of this head"""
+		return self._config_parser(read_only=False)
+	
+	#} END configuration
+		
+