Added all code from gitdb to gitpython. Next is to make it generally work. Then the tests will need some work

64 files changed, 9917 insertions, 197 deletions

diff --git a/git/base.py b/git/base.py
new file mode 100644
index 00000000..ff1062bf
--- /dev/null
+++ b/git/base.py
@@ -0,0 +1,311 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Module with basic data structures - they are designed to be lightweight and fast"""
+from util import (
+		bin_to_hex,
+		zlib
+	)
+
+from fun import (
+					type_id_to_type_map,
+					type_to_type_id_map
+				)
+
+__all__ = ('OInfo', 'OPackInfo', 'ODeltaPackInfo', 
+			'OStream', 'OPackStream', 'ODeltaPackStream',
+			'IStream', 'InvalidOInfo', 'InvalidOStream' )
+
+#{ ODB Bases
+
+class OInfo(tuple):
+	"""Carries information about an object in an ODB, provding information 
+	about the binary sha of the object, the type_string as well as the uncompressed size
+	in bytes.
+	
+	It can be accessed using tuple notation and using attribute access notation::
+	
+		assert dbi[0] == dbi.binsha
+		assert dbi[1] == dbi.type
+		assert dbi[2] == dbi.size
+	
+	The type is designed to be as lighteight as possible."""
+	__slots__ = tuple()
+	
+	def __new__(cls, sha, type, size):
+		return tuple.__new__(cls, (sha, type, size))
+	
+	def __init__(self, *args):
+		tuple.__init__(self)
+	
+	#{ Interface 
+	@property
+	def binsha(self):
+		""":return: our sha as binary, 20 bytes"""
+		return self[0]
+	
+	@property
+	def hexsha(self):
+		""":return: our sha, hex encoded, 40 bytes"""
+		return bin_to_hex(self[0])
+		
+	@property
+	def type(self):
+		return self[1]
+	
+	@property
+	def type_id(self):
+		return type_to_type_id_map[self[1]]
+		
+	@property
+	def size(self):
+		return self[2]
+	#} END interface
+	
+	
+class OPackInfo(tuple):
+	"""As OInfo, but provides a type_id property to retrieve the numerical type id, and 
+	does not include a sha.
+	
+	Additionally, the pack_offset is the absolute offset into the packfile at which 
+	all object information is located. The data_offset property points to the abosolute
+	location in the pack at which that actual data stream can be found."""
+	__slots__ = tuple()
+	
+	def __new__(cls, packoffset, type, size):
+		return tuple.__new__(cls, (packoffset,type, size))
+	
+	def __init__(self, *args):
+		tuple.__init__(self)
+		
+	#{ Interface 
+	
+	@property
+	def pack_offset(self):
+		return self[0]
+	
+	@property
+	def type(self):
+		return type_id_to_type_map[self[1]]
+	
+	@property
+	def type_id(self):
+		return self[1]
+		
+	@property
+	def size(self):
+		return self[2]
+		
+	#} END interface
+		
+		
+class ODeltaPackInfo(OPackInfo):
+	"""Adds delta specific information, 
+	Either the 20 byte sha which points to some object in the database, 
+	or the negative offset from the pack_offset, so that pack_offset - delta_info yields
+	the pack offset of the base object"""
+	__slots__ = tuple()
+	
+	def __new__(cls, packoffset, type, size, delta_info):
+		return tuple.__new__(cls, (packoffset, type, size, delta_info))
+		
+	#{ Interface 
+	@property
+	def delta_info(self):
+		return self[3]
+	#} END interface 
+	
+	
+class OStream(OInfo):
+	"""Base for object streams retrieved from the database, providing additional 
+	information about the stream.
+	Generally, ODB streams are read-only as objects are immutable"""
+	__slots__ = tuple()
+	
+	def __new__(cls, sha, type, size, stream, *args, **kwargs):
+		"""Helps with the initialization of subclasses"""
+		return tuple.__new__(cls, (sha, type, size, stream))
+	
+	
+	def __init__(self, *args, **kwargs):
+		tuple.__init__(self)
+	
+	#{ Stream Reader Interface 
+	
+	def read(self, size=-1):
+		return self[3].read(size)
+		
+	@property
+	def stream(self):
+		return self[3]
+		
+	#} END stream reader interface
+	
+	
+class ODeltaStream(OStream):
+	"""Uses size info of its stream, delaying reads"""
+	
+	def __new__(cls, sha, type, size, stream, *args, **kwargs):
+		"""Helps with the initialization of subclasses"""
+		return tuple.__new__(cls, (sha, type, size, stream))
+	
+	#{ Stream Reader Interface
+	
+	@property
+	def size(self):
+		return self[3].size
+		
+	#} END stream reader interface
+	
+	
+class OPackStream(OPackInfo):
+	"""Next to pack object information, a stream outputting an undeltified base object
+	is provided"""
+	__slots__ = tuple()
+	
+	def __new__(cls, packoffset, type, size, stream, *args):
+		"""Helps with the initialization of subclasses"""
+		return tuple.__new__(cls, (packoffset, type, size, stream))
+		
+	#{ Stream Reader Interface 
+	def read(self, size=-1):
+		return self[3].read(size)
+		
+	@property
+	def stream(self):
+		return self[3]
+	#} END stream reader interface
+
+	
+class ODeltaPackStream(ODeltaPackInfo):
+	"""Provides a stream outputting the uncompressed offset delta information"""
+	__slots__ = tuple()
+	
+	def __new__(cls, packoffset, type, size, delta_info, stream):
+		return tuple.__new__(cls, (packoffset, type, size, delta_info, stream))
+
+
+	#{ Stream Reader Interface 
+	def read(self, size=-1):
+		return self[4].read(size)
+		
+	@property
+	def stream(self):
+		return self[4]
+	#} END stream reader interface
+
+
+class IStream(list):
+	"""Represents an input content stream to be fed into the ODB. It is mutable to allow 
+	the ODB to record information about the operations outcome right in this instance.
+	
+	It provides interfaces for the OStream and a StreamReader to allow the instance
+	to blend in without prior conversion.
+	
+	The only method your content stream must support is 'read'"""
+	__slots__ = tuple()
+	
+	def __new__(cls, type, size, stream, sha=None):
+		return list.__new__(cls, (sha, type, size, stream, None))
+		
+	def __init__(self, type, size, stream, sha=None):
+		list.__init__(self, (sha, type, size, stream, None))
+	
+	#{ Interface 
+	@property
+	def hexsha(self):
+		""":return: our sha, hex encoded, 40 bytes"""
+		return bin_to_hex(self[0])
+		
+	def _error(self):
+		""":return: the error that occurred when processing the stream, or None"""
+		return self[4]
+		
+	def _set_error(self, exc):
+		"""Set this input stream to the given exc, may be None to reset the error"""
+		self[4] = exc
+			
+	error = property(_error, _set_error)
+	
+	#} END interface
+	
+	#{ Stream Reader Interface
+	
+	def read(self, size=-1):
+		"""Implements a simple stream reader interface, passing the read call on 
+			to our internal stream"""
+		return self[3].read(size)
+		
+	#} END stream reader interface 
+	
+	#{  interface
+	
+	def _set_binsha(self, binsha):
+		self[0] = binsha
+		
+	def _binsha(self):
+		return self[0]
+		
+	binsha = property(_binsha, _set_binsha)
+	
+	
+	def _type(self):
+		return self[1]
+	
+	def _set_type(self, type):
+		self[1] = type
+		
+	type = property(_type, _set_type)
+	
+	def _size(self):
+		return self[2]
+		
+	def _set_size(self, size):
+		self[2] = size
+	
+	size = property(_size, _set_size)
+	
+	def _stream(self):
+		return self[3]
+		
+	def _set_stream(self, stream):
+		self[3] = stream
+	
+	stream = property(_stream, _set_stream)
+	
+	#} END odb info interface 
+		
+
+class InvalidOInfo(tuple):
+	"""Carries information about a sha identifying an object which is invalid in 
+	the queried database. The exception attribute provides more information about
+	the cause of the issue"""
+	__slots__ = tuple()
+	
+	def __new__(cls, sha, exc):
+		return tuple.__new__(cls, (sha, exc))
+		
+	def __init__(self, sha, exc):
+		tuple.__init__(self, (sha, exc))
+	
+	@property
+	def binsha(self):
+		return self[0]
+		
+	@property
+	def hexsha(self):
+		return bin_to_hex(self[0])
+		
+	@property
+	def error(self):
+		""":return: exception instance explaining the failure"""
+		return self[1]
+
+
+class InvalidOStream(InvalidOInfo):
+	"""Carries information about an invalid ODB stream"""
+	__slots__ = tuple()
+	
+#} END ODB Bases
+
diff --git a/git/config.py b/git/config.py
index 40475ee4..f1a8832e 100644
--- a/git/config.py
+++ b/git/config.py
@@ -6,5 +6,415 @@
 """Module containing module parser implementation able to properly read and write
 configuration files"""
 
-from gitdb.config import GitConfigParser, SectionConstraint
+import re
+import os
+import ConfigParser as cp
+import inspect
+import cStringIO
+
+from git.odict import OrderedDict
+from git.util import LockFile
+
 __all__ = ('GitConfigParser', 'SectionConstraint')
+
+class MetaParserBuilder(type):
+	"""Utlity class wrapping base-class methods into decorators that assure read-only properties"""
+	def __new__(metacls, name, bases, clsdict):
+		"""
+		Equip all base-class methods with a needs_values decorator, and all non-const methods
+		with a set_dirty_and_flush_changes decorator in addition to that."""
+		kmm = '_mutating_methods_'
+		if kmm in clsdict:
+			mutating_methods = clsdict[kmm]
+			for base in bases:
+				methods = ( t for t in inspect.getmembers(base, inspect.ismethod) if not t[0].startswith("_") )
+				for name, method in methods:
+					if name in clsdict:
+						continue
+					method_with_values = needs_values(method)
+					if name in mutating_methods:
+						method_with_values = set_dirty_and_flush_changes(method_with_values)
+					# END mutating methods handling
+					
+					clsdict[name] = method_with_values
+				# END for each name/method pair
+			# END for each base
+		# END if mutating methods configuration is set
+		
+		new_type = super(MetaParserBuilder, metacls).__new__(metacls, name, bases, clsdict)
+		return new_type
+	
+	
+
+def needs_values(func):
+	"""Returns method assuring we read values (on demand) before we try to access them"""
+	def assure_data_present(self, *args, **kwargs):
+		self.read()
+		return func(self, *args, **kwargs)
+	# END wrapper method
+	assure_data_present.__name__ = func.__name__
+	return assure_data_present
+	
+def set_dirty_and_flush_changes(non_const_func):
+	"""Return method that checks whether given non constant function may be called.
+	If so, the instance will be set dirty.
+	Additionally, we flush the changes right to disk"""
+	def flush_changes(self, *args, **kwargs):
+		rval = non_const_func(self, *args, **kwargs)
+		self.write()
+		return rval
+	# END wrapper method
+	flush_changes.__name__ = non_const_func.__name__
+	return flush_changes
+	
+
+class SectionConstraint(object):
+	"""Constrains a ConfigParser to only option commands which are constrained to 
+	always use the section we have been initialized with.
+	
+	It supports all ConfigParser methods that operate on an option"""
+	__slots__ = ("_config", "_section_name")
+	_valid_attrs_ = ("get_value", "set_value", "get", "set", "getint", "getfloat", "getboolean", "has_option", 
+					"remove_section", "remove_option", "options")
+	
+	def __init__(self, config, section):
+		self._config = config
+		self._section_name = section
+		
+	def __getattr__(self, attr):
+		if attr in self._valid_attrs_:
+			return lambda *args, **kwargs: self._call_config(attr, *args, **kwargs)
+		return super(SectionConstraint,self).__getattribute__(attr)
+		
+	def _call_config(self, method, *args, **kwargs):
+		"""Call the configuration at the given method which must take a section name 
+		as first argument"""
+		return getattr(self._config, method)(self._section_name, *args, **kwargs)
+		
+	@property
+	def config(self):
+		"""return: Configparser instance we constrain"""
+		return self._config
+		
+
+class GitConfigParser(cp.RawConfigParser, object):
+	"""Implements specifics required to read git style configuration files.
+	
+	This variation behaves much like the git.config command such that the configuration
+	will be read on demand based on the filepath given during initialization.
+	
+	The changes will automatically be written once the instance goes out of scope, but 
+	can be triggered manually as well.
+	
+	The configuration file will be locked if you intend to change values preventing other 
+	instances to write concurrently.
+	
+	:note:
+		The config is case-sensitive even when queried, hence section and option names
+		must match perfectly."""
+	__metaclass__ = MetaParserBuilder
+	
+	
+	#{ Configuration
+	# The lock type determines the type of lock to use in new configuration readers.
+	# They must be compatible to the LockFile interface.
+	# A suitable alternative would be the BlockingLockFile
+	t_lock = LockFile
+	
+	#} END configuration 
+	
+	OPTCRE = re.compile(
+		r'\s?(?P<option>[^:=\s][^:=]*)'		  # very permissive, incuding leading whitespace
+		r'\s*(?P<vi>[:=])\s*'				  # any number of space/tab,
+											  # followed by separator
+											  # (either : or =), followed
+											  # by any # space/tab
+		r'(?P<value>.*)$'					  # everything up to eol
+		)
+	
+	# list of RawConfigParser methods able to change the instance
+	_mutating_methods_ = ("add_section", "remove_section", "remove_option", "set")
+	__slots__ = ("_sections", "_defaults", "_file_or_files", "_read_only","_is_initialized", '_lock')
+	
+	def __init__(self, file_or_files, read_only=True):
+		"""Initialize a configuration reader to read the given file_or_files and to 
+		possibly allow changes to it by setting read_only False
+		
+		:param file_or_files:
+			A single file path or file objects or multiple of these
+		
+		:param read_only:
+			If True, the ConfigParser may only read the data , but not change it.
+			If False, only a single file path or file object may be given."""
+		super(GitConfigParser, self).__init__()
+		# initialize base with ordered dictionaries to be sure we write the same 
+		# file back 
+		self._sections = OrderedDict()
+		self._defaults = OrderedDict()
+		
+		self._file_or_files = file_or_files
+		self._read_only = read_only
+		self._is_initialized = False
+		self._lock = None
+		
+		if not read_only:
+			if isinstance(file_or_files, (tuple, list)):
+				raise ValueError("Write-ConfigParsers can operate on a single file only, multiple files have been passed")
+			# END single file check
+			
+			if not isinstance(file_or_files, basestring):
+				file_or_files = file_or_files.name
+			# END get filename from handle/stream
+			# initialize lock base - we want to write
+			self._lock = self.t_lock(file_or_files)
+			
+			self._lock._obtain_lock()
+		# END read-only check
+		
+	
+	def __del__(self):
+		"""Write pending changes if required and release locks"""
+		# checking for the lock here makes sure we do not raise during write()
+		# in case an invalid parser was created who could not get a lock
+		if self.read_only or not self._lock._has_lock():
+			return
+		
+		try:
+			try:
+				self.write()
+			except IOError,e:
+				print "Exception during destruction of GitConfigParser: %s" % str(e)
+		finally:
+			self._lock._release_lock()
+	
+	def optionxform(self, optionstr):
+		"""Do not transform options in any way when writing"""
+		return optionstr
+	
+	def _read(self, fp, fpname):
+		"""A direct copy of the py2.4 version of the super class's _read method
+		to assure it uses ordered dicts. Had to change one line to make it work.
+		
+		Future versions have this fixed, but in fact its quite embarassing for the 
+		guys not to have done it right in the first place !
+		
+		Removed big comments to make it more compact.
+		
+		Made sure it ignores initial whitespace as git uses tabs"""
+		cursect = None							  # None, or a dictionary
+		optname = None
+		lineno = 0
+		e = None								  # None, or an exception
+		while True:
+			line = fp.readline()
+			if not line:
+				break
+			lineno = lineno + 1
+			# comment or blank line?
+			if line.strip() == '' or line[0] in '#;':
+				continue
+			if line.split(None, 1)[0].lower() == 'rem' and line[0] in "rR":
+				# no leading whitespace
+				continue
+			else:
+				# is it a section header?
+				mo = self.SECTCRE.match(line)
+				if mo:
+					sectname = mo.group('header')
+					if sectname in self._sections:
+						cursect = self._sections[sectname]
+					elif sectname == cp.DEFAULTSECT:
+						cursect = self._defaults
+					else:
+						# THE ONLY LINE WE CHANGED !
+						cursect = OrderedDict((('__name__', sectname),))
+						self._sections[sectname] = cursect
+					# So sections can't start with a continuation line
+					optname = None
+				# no section header in the file?
+				elif cursect is None:
+					raise cp.MissingSectionHeaderError(fpname, lineno, line)
+				# an option line?
+				else:
+					mo = self.OPTCRE.match(line)
+					if mo:
+						optname, vi, optval = mo.group('option', 'vi', 'value')
+						if vi in ('=', ':') and ';' in optval:
+							pos = optval.find(';')
+							if pos != -1 and optval[pos-1].isspace():
+								optval = optval[:pos]
+						optval = optval.strip()
+						if optval == '""':
+							optval = ''
+						optname = self.optionxform(optname.rstrip())
+						cursect[optname] = optval
+					else:
+						if not e:
+							e = cp.ParsingError(fpname)
+						e.append(lineno, repr(line))
+					# END  
+				# END ? 
+			# END ?
+		# END while reading 
+		# if any parsing errors occurred, raise an exception
+		if e:
+			raise e
+	
+	
+	def read(self):
+		"""Reads the data stored in the files we have been initialized with. It will 
+		ignore files that cannot be read, possibly leaving an empty configuration
+		
+		:return: Nothing
+		:raise IOError: if a file cannot be handled"""
+		if self._is_initialized:
+			return
+			
+		files_to_read = self._file_or_files
+		if not isinstance(files_to_read, (tuple, list)):
+			files_to_read = [ files_to_read ]
+		
+		for file_object in files_to_read:
+			fp = file_object
+			close_fp = False
+			# assume a path if it is not a file-object
+			if not hasattr(file_object, "seek"):
+				try:
+					fp = open(file_object)
+					close_fp = True
+				except IOError,e:
+					continue
+			# END fp handling
+				
+			try:
+				self._read(fp, fp.name)
+			finally:
+				if close_fp:
+					fp.close()
+			# END read-handling
+		# END  for each file object to read
+		self._is_initialized = True
+		
+	def _write(self, fp):
+		"""Write an .ini-format representation of the configuration state in 
+		git compatible format"""
+		def write_section(name, section_dict):
+			fp.write("[%s]\n" % name)
+			for (key, value) in section_dict.items():
+				if key != "__name__":
+					fp.write("\t%s = %s\n" % (key, str(value).replace('\n', '\n\t')))
+				# END if key is not __name__
+		# END section writing 
+		
+		if self._defaults:
+			write_section(cp.DEFAULTSECT, self._defaults)
+		map(lambda t: write_section(t[0],t[1]), self._sections.items())
+
+		
+	@needs_values
+	def write(self):
+		"""Write changes to our file, if there are changes at all
+		
+		:raise IOError: if this is a read-only writer instance or if we could not obtain 
+			a file lock"""
+		self._assure_writable("write")
+		
+		fp = self._file_or_files
+		close_fp = False
+		
+		# we have a physical file on disk, so get a lock
+		if isinstance(fp, (basestring, file)):
+			self._lock._obtain_lock()
+		# END get lock for physical files
+		
+		if not hasattr(fp, "seek"):
+			fp = open(self._file_or_files, "w")
+			close_fp = True
+		else:
+			fp.seek(0)
+		# END handle stream or file
+		
+		# WRITE DATA
+		try:
+			self._write(fp)
+		finally:
+			if close_fp:
+				fp.close()
+		# END data writing
+			
+		# we do not release the lock - it will be done automatically once the 
+		# instance vanishes
+		
+	def _assure_writable(self, method_name):
+		if self.read_only:
+			raise IOError("Cannot execute non-constant method %s.%s" % (self, method_name))
+		
+	@needs_values
+	@set_dirty_and_flush_changes
+	def add_section(self, section):
+		"""Assures added options will stay in order"""
+		super(GitConfigParser, self).add_section(section)
+		self._sections[section] = OrderedDict()
+		
+	@property
+	def read_only(self):
+		""":return: True if this instance may change the configuration file"""
+		return self._read_only
+		
+	def get_value(self, section, option, default = None):
+		"""
+		:param default:
+			If not None, the given default value will be returned in case 
+			the option did not exist
+		:return: a properly typed value, either int, float or string
+		
+		:raise TypeError: in case the value could not be understood
+			Otherwise the exceptions known to the ConfigParser will be raised."""
+		try:
+			valuestr = self.get(section, option)
+		except Exception:
+			if default is not None:
+				return default
+			raise
+		
+		types = ( long, float )
+		for numtype in types:
+			try:
+				val = numtype( valuestr )
+
+				# truncated value ?
+				if val != float( valuestr ):
+					continue
+
+				return val
+			except (ValueError,TypeError):
+				continue
+		# END for each numeric type
+		
+		# try boolean values as git uses them
+		vl = valuestr.lower() 
+		if vl == 'false':
+			return False
+		if vl == 'true':
+			return True
+		
+		if not isinstance( valuestr, basestring ):
+			raise TypeError( "Invalid value type: only int, long, float and str are allowed", valuestr )
+		
+		return valuestr
+	
+	@needs_values
+	@set_dirty_and_flush_changes
+	def set_value(self, section, option, value):
+		"""Sets the given option in section to the given value.
+		It will create the section if required, and will not throw as opposed to the default 
+		ConfigParser 'set' method.
+		
+		:param section: Name of the section in which the option resides or should reside
+		:param option: Name of the options whose value to set
+			
+		:param value: Value to set the option to. It must be a string or convertible 
+			to a string"""
+		if not self.has_section(section):
+			self.add_section(section)
+		self.set(section, option, str(value))
diff --git a/git/db/__init__.py b/git/db/__init__.py
new file mode 100644
index 00000000..25948326
--- /dev/null
+++ b/git/db/__init__.py
@@ -0,0 +1,6 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+
+from interface import *
diff --git a/git/db/cmd/__init__.py b/git/db/cmd/__init__.py
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/git/db/cmd/__init__.py
@@ -0,0 +1 @@
+
diff --git a/git/db.py b/git/db/cmd/git.py
index 5f977c6f..5f977c6f 100644
--- a/git/db.py
+++ b/git/db/cmd/git.py
diff --git a/git/db/interface.py b/git/db/interface.py
new file mode 100644
index 00000000..b7c167c5
--- /dev/null
+++ b/git/db/interface.py
@@ -0,0 +1,469 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Contains interfaces for basic database building blocks"""
+
+__all__ = (	'ObjectDBR', 'ObjectDBW', 'RootPathDB', 'CompoundDB', 'CachingDB', 
+			'TransportDB', 'ConfigurationMixin', 'RepositoryPathsMixin',  
+			'RefSpec', 'FetchInfo', 'PushInfo', 'ReferencesMixin')
+
+
+class ObjectDBR(object):
+	"""Defines an interface for object database lookup.
+	Objects are identified either by their 20 byte bin sha"""
+	
+	def __contains__(self, sha):
+		return self.has_obj(sha)
+	
+	#{ Query Interface 
+	def has_object(self, sha):
+		"""
+		:return: True if the object identified by the given 20 bytes
+			binary sha is contained in the database"""
+		raise NotImplementedError("To be implemented in subclass")
+		
+	def has_object_async(self, reader):
+		"""Return a reader yielding information about the membership of objects
+		as identified by shas
+		:param reader: Reader yielding 20 byte shas.
+		:return: async.Reader yielding tuples of (sha, bool) pairs which indicate
+			whether the given sha exists in the database or not"""
+		raise NotImplementedError("To be implemented in subclass")
+		
+	def info(self, sha):
+		""" :return: OInfo instance
+		:param sha: bytes binary sha
+		:raise BadObject:"""
+		raise NotImplementedError("To be implemented in subclass")
+		
+	def info_async(self, reader):
+		"""Retrieve information of a multitude of objects asynchronously
+		:param reader: Channel yielding the sha's of the objects of interest
+		:return: async.Reader yielding OInfo|InvalidOInfo, in any order"""
+		raise NotImplementedError("To be implemented in subclass")
+		
+	def stream(self, sha):
+		""":return: OStream instance
+		:param sha: 20 bytes binary sha
+		:raise BadObject:"""
+		raise NotImplementedError("To be implemented in subclass")
+		
+	def stream_async(self, reader):
+		"""Retrieve the OStream of multiple objects
+		:param reader: see ``info``
+		:param max_threads: see ``ObjectDBW.store``
+		:return: async.Reader yielding OStream|InvalidOStream instances in any order
+		:note: depending on the system configuration, it might not be possible to 
+			read all OStreams at once. Instead, read them individually using reader.read(x)
+			where x is small enough."""
+		raise NotImplementedError("To be implemented in subclass")
+	
+	def size(self):
+		""":return: amount of objects in this database"""
+		raise NotImplementedError()
+		
+	def sha_iter(self):
+		"""Return iterator yielding 20 byte shas for all objects in this data base"""
+		raise NotImplementedError()
+		
+	def partial_to_complete_sha_hex(self, partial_hexsha):
+		"""
+		:return: 20 byte binary sha1 from the given less-than-40 byte hexsha
+		:param partial_hexsha: hexsha with less than 40 byte
+		:raise AmbiguousObjectName: If multiple objects would match the given sha 
+		:raies BadObject: If object was not found"""
+		raise NotImplementedError()
+			
+	def partial_to_complete_sha(self, partial_binsha, canonical_length):
+		""":return: 20 byte sha as inferred by the given partial binary sha
+		:param partial_binsha: binary sha with less than 20 bytes 
+		:param canonical_length: length of the corresponding canonical (hexadecimal) representation.
+			It is required as binary sha's cannot display whether the original hex sha
+			had an odd or even number of characters
+		:raise AmbiguousObjectName: 
+		:raise BadObject: """
+	#} END query interface
+	
+	
+class ObjectDBW(object):
+	"""Defines an interface to create objects in the database"""
+	
+	#{ Edit Interface
+	def set_ostream(self, stream):
+		"""
+		Adjusts the stream to which all data should be sent when storing new objects
+		
+		:param stream: if not None, the stream to use, if None the default stream
+			will be used.
+		:return: previously installed stream, or None if there was no override
+		:raise TypeError: if the stream doesn't have the supported functionality"""
+		raise NotImplementedError("To be implemented in subclass")
+		
+	def ostream(self):
+		"""
+		:return: overridden output stream this instance will write to, or None
+			if it will write to the default stream"""
+		raise NotImplementedError("To be implemented in subclass")
+	
+	def store(self, istream):
+		"""
+		Create a new object in the database
+		:return: the input istream object with its sha set to its corresponding value
+		
+		:param istream: IStream compatible instance. If its sha is already set 
+			to a value, the object will just be stored in the our database format, 
+			in which case the input stream is expected to be in object format ( header + contents ).
+		:raise IOError: if data could not be written"""
+		raise NotImplementedError("To be implemented in subclass")
+	
+	def store_async(self, reader):
+		"""
+		Create multiple new objects in the database asynchronously. The method will 
+		return right away, returning an output channel which receives the results as 
+		they are computed.
+		
+		:return: Channel yielding your IStream which served as input, in any order.
+			The IStreams sha will be set to the sha it received during the process, 
+			or its error attribute will be set to the exception informing about the error.
+			
+		:param reader: async.Reader yielding IStream instances.
+			The same instances will be used in the output channel as were received
+			in by the Reader.
+		
+		:note:As some ODB implementations implement this operation atomic, they might 
+			abort the whole operation if one item could not be processed. Hence check how 
+			many items have actually been produced."""
+		raise NotImplementedError("To be implemented in subclass")
+	
+	#} END edit interface
+	
+
+class RootPathDB(object):
+	"""Provides basic facilities to retrieve files of interest"""
+	
+	def __init__(self, root_path):
+		"""Initialize this instance to look for its files at the given root path
+		All subsequent operations will be relative to this path
+		:raise InvalidDBRoot: 
+		:note: The base will not perform any accessablity checking as the base
+			might not yet be accessible, but become accessible before the first 
+			access."""
+		super(RootPathDB, self).__init__(root_path)
+		
+	#{ Interface 
+	def root_path(self):
+		""":return: path at which this db operates"""
+		raise NotImplementedError()
+	
+	def db_path(self, rela_path):
+		"""
+		:return: the given relative path relative to our database root, allowing 
+			to pontentially access datafiles"""
+		raise NotImplementedError()
+	#} END interface
+		
+
+class CachingDB(object):
+	"""A database which uses caches to speed-up access"""
+	
+	#{ Interface 
+	
+	def update_cache(self, force=False):
+		"""
+		Call this method if the underlying data changed to trigger an update
+		of the internal caching structures.
+		
+		:param force: if True, the update must be performed. Otherwise the implementation
+			may decide not to perform an update if it thinks nothing has changed.
+		:return: True if an update was performed as something change indeed"""
+		
+	# END interface
+
+class CompoundDB(object):
+	"""A database which delegates calls to sub-databases.
+	They should usually be cached and lazy-loaded"""
+	
+	#{ Interface
+	
+	def databases(self):
+		""":return: tuple of database instances we use for lookups"""
+		raise NotImplementedError()
+
+	#} END interface
+	
+
+class RefSpec(object):
+	"""A refspec is a simple container which provides information about the way
+	something should be fetched or pushed. It requires to use symbols to describe
+	the actual objects which is done using reference names (or respective instances
+	which resolve to actual reference names)."""
+	__slots__ = ('source', 'destination', 'force')
+	
+	def __init__(self, source, destination, force=False):
+		"""initalize the instance with the required values
+		:param source: reference name or instance. If None, the Destination 
+			is supposed to be deleted."""
+		self.source = source
+		self.destination = destination
+		self.force = force
+		if self.destination is None:
+			raise ValueError("Destination must be set")
+		
+	def __str__(self):
+		""":return: a git-style refspec"""
+		s = str(self.source)
+		if self.source is None:
+			s = ''
+		#END handle source
+		d = str(self.destination)
+		p = ''
+		if self.force:
+			p = '+'
+		#END handle force
+		res = "%s%s:%s" % (p, s, d)
+		
+	def delete_destination(self):
+		return self.source is None
+		
+		
+class PushInfo(object):
+	"""A type presenting information about the result of a push operation for exactly
+	one refspec
+
+	flags				# bitflags providing more information about the result
+	local_ref			# Reference pointing to the local reference that was pushed
+						# It is None if the ref was deleted.
+	remote_ref_string 	# path to the remote reference located on the remote side
+	remote_ref 			# Remote Reference on the local side corresponding to 
+						# the remote_ref_string. It can be a TagReference as well.
+	old_commit 			# commit at which the remote_ref was standing before we pushed
+						# it to local_ref.commit. Will be None if an error was indicated
+	summary				# summary line providing human readable english text about the push
+	"""
+	__slots__ = tuple()
+	
+	NEW_TAG, NEW_HEAD, NO_MATCH, REJECTED, REMOTE_REJECTED, REMOTE_FAILURE, DELETED, \
+	FORCED_UPDATE, FAST_FORWARD, UP_TO_DATE, ERROR = [ 1 << x for x in range(11) ]
+		
+		
+class FetchInfo(object):
+	"""A type presenting information about the fetch operation on exactly one refspec
+	
+	The following members are defined:
+	ref				# name of the reference to the changed 
+					# remote head or FETCH_HEAD. Implementations can provide
+					# actual class instance which convert to a respective string
+	flags			# additional flags to be & with enumeration members, 
+					# i.e. info.flags & info.REJECTED 
+					# is 0 if ref is FETCH_HEAD
+	note				# additional notes given by the fetch-pack implementation intended for the user
+	old_commit		# if info.flags & info.FORCED_UPDATE|info.FAST_FORWARD, 
+					# field is set to the previous location of ref as hexsha or None
+					# Implementors may use their own type too, but it should decay into a
+					# string of its hexadecimal sha representation"""
+	__slots__ = tuple()
+	
+	NEW_TAG, NEW_HEAD, HEAD_UPTODATE, TAG_UPDATE, REJECTED, FORCED_UPDATE, \
+	FAST_FORWARD, ERROR = [ 1 << x for x in range(8) ]
+
+
+class TransportDB(object):
+	"""A database which allows to transport objects from and to different locations
+	which are specified by urls (location) and refspecs (what to transport, 
+	see http://www.kernel.org/pub/software/scm/git/docs/git-fetch.html).
+	
+	At the beginning of a transport operation, it will be determined which objects
+	have to be sent (either by this or by the other side).
+	
+	Afterwards a pack with the required objects is sent (or received). If there is 
+	nothing to send, the pack will be empty.
+	
+	As refspecs involve symbolic names for references to be handled, we require
+	RefParse functionality. How this is done is up to the actual implementation."""
+	# The following variables need to be set by the derived class
+	
+	#{ Interface
+	
+	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
+			name of the remote. The implementation should allow objects as input
+			as well, these are assumed to resovle to a meaningful string though.
+		: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
+		: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.
+		:raise: if any issue occours during the transport or if the url is not 
+			supported by the protocol.
+		"""
+		raise NotImplementedError()
+		
+	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()
+		
+	@property
+	def remotes(self):
+		""":return: An IterableList of Remote objects allowing to access and manipulate remotes
+		:note: Remote objects can also be used for the actual push or fetch operation"""
+		raise NotImplementedError()
+		
+	#}end interface
+
+
+class ReferencesMixin(object):
+	"""Database providing reference objects which in turn point to database objects
+	like Commits or Tag(Object)s.
+	
+	The returned types are compatible to the interfaces of the pure python 
+	reference implementation in GitDB.ref"""
+	
+	def resolve(self, name):
+		"""Resolve the given name into a binary sha. Valid names are as defined 
+		in the rev-parse documentation http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html
+		:return: binary sha matching the name
+		:raise AmbiguousObjectName:
+		:raise BadObject: """
+		raise NotImplementedError()
+	
+	@property
+	def references(self):
+		""":return: iterable list of all Reference objects representing tags, heads
+		and remote references. This is the most general method to obtain any 
+		references."""
+		raise NotImplementedError()
+		
+	@property
+	def heads(self):
+		""":return: IterableList with HeadReference objects pointing to all
+		heads in the repository."""
+		raise NotImplementedError()
+		
+	@property
+	def tags(self):
+		""":return: An IterableList of TagReferences that are available in this repo"""
+		raise NotImplementedError()
+		
+		
+class RepositoryPathsMixin(object):
+	"""Represents basic functionality of a full git repository. This involves an 
+	optional working tree, a git directory with references and an object directory.
+	
+	This type collects the respective paths and verifies the provided base path 
+	truly is a git repository.
+	
+	If the underlying type provides the config_reader() method, we can properly determine 
+	whether this is a bare repository as well. Otherwise it will make an educated guess
+	based on the path name."""
+	#{ Subclass Interface
+	def _initialize(self, path):
+		"""initialize this instance with the given path. It may point to 
+		any location within the repositories own data, as well as the working tree.
+		
+		The implementation will move up and search for traces of a git repository, 
+		which is indicated by a child directory ending with .git or the 
+		current path portion ending with .git.
+		
+		The paths made available for query are suitable for full git repositories
+		only. Plain object databases need to be fed the "objects" directory path.
+		
+		:param path: the path to initialize the repository with
+		:raise InvalidDBRoot:
+		"""
+		raise NotImplementedError()
+	#} end subclass interface
+	
+	#{ Interface
+	
+	def is_bare(self):
+		""":return: True if this is a bare repository
+		:note: this value is cached upon initialization"""
+		raise NotImplementedError()
+		
+	def git_path(self):
+		""":return: path to directory containing this actual git repository (which 
+		in turn provides access to objects and references"""
+		raise NotImplementedError()
+		
+	def working_tree_path(self):
+		""":return: path to directory containing the working tree checkout of our 
+		git repository.
+		:raise AssertionError: If this is a bare repository"""
+		raise NotImplementedError()
+		
+	def objects_path(self):
+		""":return: path to the repository's objects directory"""
+		raise NotImplementedError()
+		
+	def working_dir(self):
+		""":return: working directory of the git process or related tools, being 
+		either the working_tree_path if available or the git_path"""
+		raise NotImplementedError()
+		
+	#} END interface
+		
+		
+class ConfigurationMixin(object):
+	"""Interface providing configuration handler instances, which provide locked access
+	to a single git-style configuration file (ini like format, using tabs as improve readablity).
+	
+	Configuration readers can be initialized with multiple files at once, whose information is concatenated
+	when reading. Lower-level files overwrite values from higher level files, i.e. a repository configuration file 
+	overwrites information coming from a system configuration file
+	
+	:note: for the 'repository' config level, a git_path() compatible type is required"""
+	config_level = ("system", "global", "repository")
+		
+	#{ Interface
+	
+	def config_reader(self, config_level=None):
+		"""
+		:return:
+			GitConfigParser allowing to read the full git configuration, but not to write it
+			
+			The configuration will include values from the system, user and repository 
+			configuration files.
+			
+		:param config_level:
+			For possible values, see config_writer method
+			If None, all applicable levels will be used. Specify a level in case 
+			you know which exact file you whish to read to prevent reading multiple files for 
+			instance
+		:note: On windows, system configuration cannot currently be read as the path is 
+			unknown, instead the global path will be used."""
+		raise NotImplementedError()
+		
+	def config_writer(self, config_level="repository"):
+		"""
+		:return:
+			GitConfigParser allowing to write values of the specified configuration file level.
+			Config writers should be retrieved, used to change the configuration ,and written 
+			right away as they will lock the configuration file in question and prevent other's
+			to write it.
+			
+		:param config_level:
+			One of the following values
+			system = sytem wide configuration file
+			global = user level configuration file
+			repository = configuration file for this repostory only"""
+		raise NotImplementedError()
+	
+	#} END interface
+	
diff --git a/git/db/py/__init__.py b/git/db/py/__init__.py
new file mode 100644
index 00000000..046c699d
--- /dev/null
+++ b/git/db/py/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+
+from base import *
+from loose import *
+from mem import *
+from pack import *
+from git import *
+from ref import *
+from resolve import *
+from transport import *
diff --git a/git/db/py/base.py b/git/db/py/base.py
new file mode 100644
index 00000000..c378b10e
--- /dev/null
+++ b/git/db/py/base.py
@@ -0,0 +1,351 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Contains basic implementations for the interface building blocks"""
+
+from gitdb.db.interface import *
+
+from gitdb.util import (
+		pool,
+		join,
+		normpath,
+		abspath,
+		dirname,
+		LazyMixin, 
+		hex_to_bin,
+		bin_to_hex,
+		expandvars,
+		expanduser,
+		exists,
+		is_git_dir
+	)
+
+from gitdb.config import GitConfigParser
+from gitdb.exc import 	(
+						BadObject, 
+						AmbiguousObjectName,
+						InvalidDBRoot
+						)
+
+from async import ChannelThreadTask
+
+from itertools import chain
+import sys
+import os
+
+
+__all__ = (	'PureObjectDBR', 'PureObjectDBW', 'PureRootPathDB', 'PureCompoundDB', 
+			'PureConfigurationMixin', 'PureRepositoryPathsMixin')
+
+
+class PureObjectDBR(ObjectDBR):
+	
+	#{ Query Interface 
+		
+	def has_object_async(self, reader):
+		task = ChannelThreadTask(reader, str(self.has_object_async), lambda sha: (sha, self.has_object(sha)))
+		return pool.add_task(task) 
+		
+	def info_async(self, reader):
+		task = ChannelThreadTask(reader, str(self.info_async), self.info)
+		return pool.add_task(task)
+		
+	def stream_async(self, reader):
+		# base implementation just uses the stream method repeatedly
+		task = ChannelThreadTask(reader, str(self.stream_async), self.stream)
+		return pool.add_task(task)
+	
+	def partial_to_complete_sha_hex(self, partial_hexsha):
+		len_partial_hexsha = len(partial_hexsha)
+		if len_partial_hexsha % 2 != 0:
+			partial_binsha = hex_to_bin(partial_hexsha + "0")
+		else:
+			partial_binsha = hex_to_bin(partial_hexsha)
+		# END assure successful binary conversion
+		return self.partial_to_complete_sha(partial_binsha, len(partial_hexsha))
+	
+	#} END query interface
+	
+	
+class PureObjectDBW(ObjectDBW):
+	
+	def __init__(self, *args, **kwargs):
+		super(PureObjectDBW, self).__init__(*args, **kwargs)
+		self._ostream = None
+	
+	#{ Edit Interface
+	def set_ostream(self, stream):
+		cstream = self._ostream
+		self._ostream = stream
+		return cstream
+		
+	def ostream(self):
+		return self._ostream
+	
+	def store_async(self, reader):
+		task = ChannelThreadTask(reader, str(self.store_async), self.store) 
+		return pool.add_task(task)
+	
+	#} END edit interface
+	
+
+class PureRootPathDB(RootPathDB):
+	
+	def __init__(self, root_path):
+		super(PureRootPathDB, self).__init__(root_path)
+		self._root_path = root_path
+		
+		
+	#{ Interface 
+	def root_path(self):
+		return self._root_path
+	
+	def db_path(self, rela_path):
+		return join(self._root_path, rela_path)
+	#} END interface
+		
+
+def _databases_recursive(database, output):
+	"""Fill output list with database from db, in order. Deals with Loose, Packed 
+	and compound databases."""
+	if isinstance(database, CompoundDB):
+		compounds = list()
+		dbs = database.databases()
+		output.extend(db for db in dbs if not isinstance(db, CompoundDB))
+		for cdb in (db for db in dbs if isinstance(db, CompoundDB)):
+			_databases_recursive(cdb, output)
+	else:
+		output.append(database)
+	# END handle database type
+	
+
+class PureCompoundDB(CompoundDB, PureObjectDBR, LazyMixin, CachingDB):
+	def _set_cache_(self, attr):
+		if attr == '_dbs':
+			self._dbs = list()
+		elif attr == '_db_cache':
+			self._db_cache = dict()
+		else:
+			super(PureCompoundDB, self)._set_cache_(attr)
+	
+	def _db_query(self, sha):
+		""":return: database containing the given 20 byte sha
+		:raise BadObject:"""
+		# most databases use binary representations, prevent converting 
+		# it everytime a database is being queried
+		try:
+			return self._db_cache[sha]
+		except KeyError:
+			pass
+		# END first level cache
+		
+		for db in self._dbs:
+			if db.has_object(sha):
+				self._db_cache[sha] = db
+				return db
+		# END for each database
+		raise BadObject(sha)
+	
+	#{ PureObjectDBR interface 
+	
+	def has_object(self, sha):
+		try:
+			self._db_query(sha)
+			return True
+		except BadObject:
+			return False
+		# END handle exceptions
+		
+	def info(self, sha):
+		return self._db_query(sha).info(sha)
+		
+	def stream(self, sha):
+		return self._db_query(sha).stream(sha)
+
+	def size(self):
+		return reduce(lambda x,y: x+y, (db.size() for db in self._dbs), 0)
+		
+	def sha_iter(self):
+		return chain(*(db.sha_iter() for db in self._dbs))
+		
+	#} END object DBR Interface
+	
+	#{ Interface
+	
+	def databases(self):
+		return tuple(self._dbs)
+
+	def update_cache(self, force=False):
+		# something might have changed, clear everything
+		self._db_cache.clear()
+		stat = False
+		for db in self._dbs:
+			if isinstance(db, CachingDB):
+				stat |= db.update_cache(force)
+			# END if is caching db
+		# END for each database to update
+		return stat
+		
+	def partial_to_complete_sha_hex(self, partial_hexsha):
+		databases = self.databases()
+		
+		len_partial_hexsha = len(partial_hexsha)
+		if len_partial_hexsha % 2 != 0:
+			partial_binsha = hex_to_bin(partial_hexsha + "0")
+		else:
+			partial_binsha = hex_to_bin(partial_hexsha)
+		# END assure successful binary conversion 
+		
+		candidate = None
+		for db in self._dbs:
+			full_bin_sha = None
+			try:
+				if hasattr(db, 'partial_to_complete_sha_hex'):
+					full_bin_sha = db.partial_to_complete_sha_hex(partial_hexsha)
+				else:
+					full_bin_sha = db.partial_to_complete_sha(partial_binsha, len_partial_hexsha)
+				# END handle database type
+			except BadObject:
+				continue
+			# END ignore bad objects
+			if full_bin_sha:
+				if candidate and candidate != full_bin_sha:
+					raise AmbiguousObjectName(partial_hexsha)
+				candidate = full_bin_sha
+			# END handle candidate
+		# END for each db
+		if not candidate:
+			raise BadObject(partial_binsha)
+		return candidate
+		
+	def partial_to_complete_sha(self, partial_binsha, hex_len):
+		"""Simple adaptor to feed into our implementation"""
+		return self.partial_to_complete_sha_hex(bin_to_hex(partial_binsha)[:hex_len])
+	#} END interface
+	
+		
+class PureRepositoryPathsMixin(RepositoryPathsMixin):
+	# slots has no effect here, its just to keep track of used attrs
+	__slots__  = ("_git_path", '_bare')
+	
+	#{ Configuration 
+	repo_dir = '.git'
+	objs_dir = 'objects'
+	#} END configuration
+	
+	#{ Subclass Interface
+	def _initialize(self, path):
+		epath = abspath(expandvars(expanduser(path or os.getcwd())))
+
+		if not exists(epath):
+			raise InvalidDBRoot(epath)
+		#END check file 
+
+		self._working_tree_dir = None
+		self._git_path = None
+		curpath = epath
+		
+		# walk up the path to find the .git dir
+		while curpath:
+			if is_git_dir(curpath):
+				self._git_path = curpath
+				self._working_tree_dir = os.path.dirname(curpath)
+				break
+			gitpath = join(curpath, self.repo_dir)
+			if is_git_dir(gitpath):
+				self._git_path = gitpath
+				self._working_tree_dir = curpath
+				break
+			curpath, dummy = os.path.split(curpath)
+			if not dummy:
+				break
+		# END while curpath
+		
+		if self._git_path is None:
+			raise InvalidDBRoot(epath)
+		# END path not found
+
+		self._bare = self._git_path.endswith(self.repo_dir)
+		if hasattr(self, 'config_reader'):
+			try:
+				self._bare = self.config_reader("repository").getboolean('core','bare') 
+			except Exception:
+				# lets not assume the option exists, although it should
+				pass
+		#END check bare flag
+
+	
+	#} end subclass interface
+	
+	#{ Interface
+	
+	def is_bare(self):
+		return self._bare
+		
+	def git_path(self):
+		return self._git_path
+		
+	def working_tree_path(self):
+		if self.is_bare():
+			raise AssertionError("Repository at %s is bare and does not have a working tree directory" % self.git_path())
+		#END assertion
+		return dirname(self.git_path())
+		
+	def objects_path(self):
+		return join(self.git_path(), self.objs_dir)
+		
+	def working_dir(self):
+		if self.is_bare():
+			return self.git_path()
+		else:
+			return self.working_tree_dir()
+		#END handle bare state
+		
+	#} END interface
+		
+		
+class PureConfigurationMixin(ConfigurationMixin):
+	
+	#{ Configuration
+	system_config_file_name = "gitconfig"
+	repo_config_file_name = "config"
+	#} END
+	
+	def __init__(self, *args, **kwargs):
+		"""Verify prereqs"""
+		assert hasattr(self, 'git_path')
+	
+	def _path_at_level(self, level ):
+		# we do not support an absolute path of the gitconfig on windows , 
+		# use the global config instead
+		if sys.platform == "win32" and level == "system":
+			level = "global"
+		#END handle windows
+			
+		if level == "system":
+			return "/etc/%s" % self.system_config_file_name
+		elif level == "global":
+			return normpath(expanduser("~/.%s" % self.system_config_file_name))
+		elif level == "repository":
+			return join(self.git_path(), self.repo_config_file_name)
+		#END handle level
+		
+		raise ValueError("Invalid configuration level: %r" % level)
+		
+	#{ Interface
+	
+	def config_reader(self, config_level=None):
+		files = None
+		if config_level is None:
+			files = [ self._path_at_level(f) for f in self.config_level ]
+		else:
+			files = [ self._path_at_level(config_level) ]
+		#END handle level
+		return GitConfigParser(files, read_only=True)
+		
+	def config_writer(self, config_level="repository"):
+		return GitConfigParser(self._path_at_level(config_level), read_only=False)
+	
+	#} END interface
+	
diff --git a/git/db/py/git.py b/git/db/py/git.py
new file mode 100644
index 00000000..bc148c6f
--- /dev/null
+++ b/git/db/py/git.py
@@ -0,0 +1,113 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of PureGitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from base import (
+						PureCompoundDB, 
+						PureObjectDBW, 
+						PureRootPathDB, 
+						PureRepositoryPathsMixin,
+						PureConfigurationMixin,
+					)
+
+from resolve import PureReferencesMixin
+
+from loose import PureLooseObjectODB
+from pack import PurePackedODB
+from ref import PureReferenceDB
+
+from gitdb.util import (
+						LazyMixin, 
+						normpath,
+						join,
+						dirname
+					)
+from gitdb.exc import (
+						InvalidDBRoot, 
+						BadObject, 
+						AmbiguousObjectName
+						)
+import os
+
+__all__ = ('PureGitODB', 'PureGitDB')
+
+
+class PureGitODB(PureRootPathDB, PureObjectDBW, PureCompoundDB):
+	"""A git-style object-only database, which contains all objects in the 'objects'
+	subdirectory.
+	:note: The type needs to be initialized on the ./objects directory to function, 
+		as it deals solely with object lookup. Use a PureGitDB type if you need
+		reference and push support."""
+	# Configuration
+	PackDBCls = PurePackedODB
+	LooseDBCls = PureLooseObjectODB
+	PureReferenceDBCls = PureReferenceDB
+	
+	# Directories
+	packs_dir = 'pack'
+	loose_dir = ''
+	alternates_dir = os.path.join('info', 'alternates')
+	
+	def __init__(self, root_path):
+		"""Initialize ourselves on a git ./objects directory"""
+		super(PureGitODB, self).__init__(root_path)
+		
+	def _set_cache_(self, attr):
+		if attr == '_dbs' or attr == '_loose_db':
+			self._dbs = list()
+			loose_db = None
+			for subpath, dbcls in ((self.packs_dir, self.PackDBCls), 
+									(self.loose_dir, self.LooseDBCls),
+									(self.alternates_dir, self.PureReferenceDBCls)):
+				path = self.db_path(subpath)
+				if os.path.exists(path):
+					self._dbs.append(dbcls(path))
+					if dbcls is self.LooseDBCls:
+						loose_db = self._dbs[-1]
+					# END remember loose db
+				# END check path exists
+			# END for each db type
+			
+			# should have at least one subdb
+			if not self._dbs:
+				raise InvalidDBRoot(self.root_path())
+			# END handle error
+			
+			# we the first one should have the store method
+			assert loose_db is not None and hasattr(loose_db, 'store'), "First database needs store functionality"
+			
+			# finally set the value
+			self._loose_db = loose_db
+		else:
+			super(PureGitODB, self)._set_cache_(attr)
+		# END handle attrs
+		
+	#{ PureObjectDBW interface
+		
+	def store(self, istream):
+		return self._loose_db.store(istream)
+		
+	def ostream(self):
+		return self._loose_db.ostream()
+	
+	def set_ostream(self, ostream):
+		return self._loose_db.set_ostream(ostream)
+		
+	#} END objectdbw interface
+	
+	
+class PureGitDB(PureGitODB, PureRepositoryPathsMixin, PureConfigurationMixin, PureReferencesMixin):
+	"""Git like database with support for object lookup as well as reference resolution.
+	Our rootpath is set to the actual .git directory (bare on unbare).
+	
+	The root_path will be the git objects directory. Use git_path() to obtain the actual top-level 
+	git directory."""
+	#directories
+	
+	def __init__(self, root_path):
+		"""Initialize ourselves on the .git directory, or the .git/objects directory."""
+		PureRepositoryPathsMixin._initialize(self, root_path)
+		super(PureGitDB, self).__init__(self.objects_path())
+	
+	
+	
diff --git a/git/db/py/loose.py b/git/db/py/loose.py
new file mode 100644
index 00000000..34e31da6
--- /dev/null
+++ b/git/db/py/loose.py
@@ -0,0 +1,262 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from base import (
+						PureRootPathDB, 
+						PureObjectDBR, 
+						PureObjectDBW
+				)
+
+
+from gitdb.exc import (
+	InvalidDBRoot, 
+	BadObject,
+	AmbiguousObjectName
+	)
+
+from gitdb.stream import (
+		DecompressMemMapReader,
+		FDCompressedSha1Writer,
+		FDStream,
+		Sha1Writer
+	)
+
+from gitdb.base import (
+							OStream,
+							OInfo
+						)
+
+from gitdb.util import (
+		file_contents_ro_filepath,
+		ENOENT,
+		hex_to_bin,
+		bin_to_hex,
+		exists,
+		chmod,
+		isdir,
+		isfile,
+		remove,
+		mkdir,
+		rename,
+		dirname,
+		basename,
+		join
+	)
+
+from gitdb.fun import ( 
+	chunk_size,
+	loose_object_header_info, 
+	write_object,
+	stream_copy
+	)
+
+import tempfile
+import mmap
+import sys
+import os
+
+
+__all__ = ( 'PureLooseObjectODB', )
+
+
+class PureLooseObjectODB(PureRootPathDB, PureObjectDBR, PureObjectDBW):
+	"""A database which operates on loose object files"""
+	
+	# CONFIGURATION
+	# chunks in which data will be copied between streams
+	stream_chunk_size = chunk_size
+	
+	# On windows we need to keep it writable, otherwise it cannot be removed
+	# either
+	new_objects_mode = 0444
+	if os.name == 'nt':
+		new_objects_mode = 0644
+			
+	
+	def __init__(self, root_path):
+		super(PureLooseObjectODB, self).__init__(root_path)
+		self._hexsha_to_file = dict()
+		# Additional Flags - might be set to 0 after the first failure
+		# Depending on the root, this might work for some mounts, for others not, which
+		# is why it is per instance
+		self._fd_open_flags = getattr(os, 'O_NOATIME', 0)
+	
+	#{ Interface 
+	def object_path(self, hexsha):
+		"""
+		:return: path at which the object with the given hexsha would be stored, 
+			relative to the database root"""
+		return join(hexsha[:2], hexsha[2:])
+	
+	def readable_db_object_path(self, hexsha):
+		"""
+		:return: readable object path to the object identified by hexsha
+		:raise BadObject: If the object file does not exist"""
+		try:
+			return self._hexsha_to_file[hexsha]
+		except KeyError:
+			pass
+		# END ignore cache misses 
+			
+		# try filesystem
+		path = self.db_path(self.object_path(hexsha))
+		if exists(path):
+			self._hexsha_to_file[hexsha] = path
+			return path
+		# END handle cache
+		raise BadObject(hexsha)
+		
+	def partial_to_complete_sha_hex(self, partial_hexsha):
+		""":return: 20 byte binary sha1 string which matches the given name uniquely
+		:param name: hexadecimal partial name
+		:raise AmbiguousObjectName: 
+		:raise BadObject: """
+		candidate = None
+		for binsha in self.sha_iter():
+			if bin_to_hex(binsha).startswith(partial_hexsha):
+				# it can't ever find the same object twice
+				if candidate is not None:
+					raise AmbiguousObjectName(partial_hexsha)
+				candidate = binsha
+		# END for each object
+		if candidate is None:
+			raise BadObject(partial_hexsha)
+		return candidate
+		
+	#} END interface
+	
+	def _map_loose_object(self, sha):
+		"""
+		:return: memory map of that file to allow random read access
+		:raise BadObject: if object could not be located"""
+		db_path = self.db_path(self.object_path(bin_to_hex(sha)))
+		try:
+			return file_contents_ro_filepath(db_path, flags=self._fd_open_flags)
+		except OSError,e:
+			if e.errno != ENOENT:
+				# try again without noatime
+				try:
+					return file_contents_ro_filepath(db_path)
+				except OSError:
+					raise BadObject(sha)
+				# didn't work because of our flag, don't try it again
+				self._fd_open_flags = 0
+			else:
+				raise BadObject(sha)
+			# END handle error
+		# END exception handling
+		try:
+			return mmap.mmap(fd, 0, access=mmap.ACCESS_READ)
+		finally:
+			os.close(fd)
+		# END assure file is closed
+		
+	def set_ostream(self, stream):
+		""":raise TypeError: if the stream does not support the Sha1Writer interface"""
+		if stream is not None and not isinstance(stream, Sha1Writer):
+			raise TypeError("Output stream musst support the %s interface" % Sha1Writer.__name__)
+		return super(PureLooseObjectODB, self).set_ostream(stream)
+			
+	def info(self, sha):
+		m = self._map_loose_object(sha)
+		try:
+			type, size = loose_object_header_info(m)
+			return OInfo(sha, type, size)
+		finally:
+			m.close()
+		# END assure release of system resources
+		
+	def stream(self, sha):
+		m = self._map_loose_object(sha)
+		type, size, stream = DecompressMemMapReader.new(m, close_on_deletion = True)
+		return OStream(sha, type, size, stream)
+		
+	def has_object(self, sha):
+		try:
+			self.readable_db_object_path(bin_to_hex(sha))
+			return True
+		except BadObject:
+			return False
+		# END check existance
+	
+	def store(self, istream):
+		"""note: The sha we produce will be hex by nature"""
+		tmp_path = None
+		writer = self.ostream()
+		if writer is None:
+			# open a tmp file to write the data to
+			fd, tmp_path = tempfile.mkstemp(prefix='obj', dir=self._root_path)
+			
+			if istream.binsha is None:
+				writer = FDCompressedSha1Writer(fd)
+			else:
+				writer = FDStream(fd)
+			# END handle direct stream copies
+		# END handle custom writer
+	
+		try:
+			try:
+				if istream.binsha is not None:
+					# copy as much as possible, the actual uncompressed item size might
+					# be smaller than the compressed version
+					stream_copy(istream.read, writer.write, sys.maxint, self.stream_chunk_size)
+				else:
+					# write object with header, we have to make a new one
+					write_object(istream.type, istream.size, istream.read, writer.write,
+									chunk_size=self.stream_chunk_size)
+				# END handle direct stream copies
+			finally:
+				if tmp_path:
+					writer.close()
+			# END assure target stream is closed
+		except:
+			if tmp_path:
+				os.remove(tmp_path)
+			raise
+		# END assure tmpfile removal on error
+		
+		hexsha = None
+		if istream.binsha:
+			hexsha = istream.hexsha
+		else:
+			hexsha = writer.sha(as_hex=True)
+		# END handle sha
+		
+		if tmp_path:
+			obj_path = self.db_path(self.object_path(hexsha))
+			obj_dir = dirname(obj_path)
+			if not isdir(obj_dir):
+				mkdir(obj_dir)
+			# END handle destination directory
+			# rename onto existing doesn't work on windows
+			if os.name == 'nt' and isfile(obj_path):
+				remove(obj_path)
+			# END handle win322
+			rename(tmp_path, obj_path)
+			
+			# make sure its readable for all ! It started out as rw-- tmp file
+			# but needs to be rwrr
+			chmod(obj_path, self.new_objects_mode)
+		# END handle dry_run
+		
+		istream.binsha = hex_to_bin(hexsha)
+		return istream
+		
+	def sha_iter(self):
+		# find all files which look like an object, extract sha from there
+		for root, dirs, files in os.walk(self.root_path()):
+			root_base = basename(root)
+			if len(root_base) != 2:
+				continue
+				
+			for f in files:
+				if len(f) != 38:
+					continue
+				yield hex_to_bin(root_base + f)
+			# END for each file
+		# END for each walk iteration
+		
+	def size(self):
+		return len(tuple(self.sha_iter()))
+	
diff --git a/git/db/py/mem.py b/git/db/py/mem.py
new file mode 100644
index 00000000..ba922e96
--- /dev/null
+++ b/git/db/py/mem.py
@@ -0,0 +1,113 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Contains the MemoryDatabase implementation"""
+from loose import PureLooseObjectODB
+from base import (
+						PureObjectDBR, 
+						PureObjectDBW
+					)
+
+from gitdb.base import (
+							OStream,
+							IStream,
+						)
+
+from gitdb.exc import (
+						BadObject,
+						UnsupportedOperation
+						)
+from gitdb.stream import (
+							ZippedStoreShaWriter,
+							DecompressMemMapReader,
+						)
+
+from cStringIO import StringIO
+
+__all__ = ("PureMemoryDB", )
+
+class PureMemoryDB(PureObjectDBR, PureObjectDBW):
+	"""A memory database stores everything to memory, providing fast IO and object
+	retrieval. It should be used to buffer results and obtain SHAs before writing
+	it to the actual physical storage, as it allows to query whether object already
+	exists in the target storage before introducing actual IO
+	
+	:note: memory is currently not threadsafe, hence the async methods cannot be used
+		for storing"""
+	
+	def __init__(self):
+		super(PureMemoryDB, self).__init__()
+		self._db = PureLooseObjectODB("path/doesnt/matter")
+		
+		# maps 20 byte shas to their OStream objects
+		self._cache = dict()
+		
+	def set_ostream(self, stream):
+		raise UnsupportedOperation("PureMemoryDB's always stream into memory")
+		
+	def store(self, istream):
+		zstream = ZippedStoreShaWriter()
+		self._db.set_ostream(zstream)
+		
+		istream = self._db.store(istream)
+		zstream.close()		# close to flush
+		zstream.seek(0)
+		
+		# don't provide a size, the stream is written in object format, hence the 
+		# header needs decompression
+		decomp_stream = DecompressMemMapReader(zstream.getvalue(), close_on_deletion=False) 
+		self._cache[istream.binsha] = OStream(istream.binsha, istream.type, istream.size, decomp_stream)
+		
+		return istream
+		
+	def store_async(self, reader):
+		raise UnsupportedOperation("PureMemoryDBs cannot currently be used for async write access")
+	
+	def has_object(self, sha):
+		return sha in self._cache
+
+	def info(self, sha):
+		# we always return streams, which are infos as well
+		return self.stream(sha)
+	
+	def stream(self, sha):
+		try:
+			ostream = self._cache[sha]
+			# rewind stream for the next one to read
+			ostream.stream.seek(0)
+			return ostream
+		except KeyError:
+			raise BadObject(sha)
+		# END exception handling
+	
+	def size(self):
+		return len(self._cache)
+		
+	def sha_iter(self):
+		return self._cache.iterkeys()
+		
+		
+	#{ Interface 
+	def stream_copy(self, sha_iter, odb):
+		"""Copy the streams as identified by sha's yielded by sha_iter into the given odb
+		The streams will be copied directly
+		:note: the object will only be written if it did not exist in the target db
+		:return: amount of streams actually copied into odb. If smaller than the amount
+			of input shas, one or more objects did already exist in odb"""
+		count = 0
+		for sha in sha_iter:
+			if odb.has_object(sha):
+				continue
+			# END check object existance
+			
+			ostream = self.stream(sha)
+			# compressed data including header
+			sio = StringIO(ostream.stream.data())
+			istream = IStream(ostream.type, ostream.size, sio, sha)
+			
+			odb.store(istream)
+			count += 1
+		# END for each sha
+		return count
+	#} END interface
diff --git a/git/db/py/pack.py b/git/db/py/pack.py
new file mode 100644
index 00000000..1d0e9bfc
--- /dev/null
+++ b/git/db/py/pack.py
@@ -0,0 +1,212 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Module containing a database to deal with packs"""
+from gitdb.db import CachingDB
+from base import (
+						PureRootPathDB, 
+						PureObjectDBR 
+				)
+
+from gitdb.util import LazyMixin
+
+from gitdb.exc import (
+							BadObject,
+							UnsupportedOperation,
+							AmbiguousObjectName
+						)
+
+from gitdb.pack import PackEntity
+
+import os
+import glob
+
+__all__ = ('PurePackedODB', )
+
+#{ Utilities
+
+
+class PurePackedODB(PureRootPathDB, PureObjectDBR, CachingDB, LazyMixin):
+	"""A database operating on a set of object packs"""
+	
+	# the type to use when instantiating a pack entity
+	PackEntityCls = PackEntity
+	
+	# sort the priority list every N queries
+	# Higher values are better, performance tests don't show this has 
+	# any effect, but it should have one
+	_sort_interval = 500
+	
+	def __init__(self, root_path):
+		super(PurePackedODB, self).__init__(root_path)
+		# list of lists with three items:
+		# * hits - number of times the pack was hit with a request
+		# * entity - Pack entity instance
+		# * sha_to_index - PackIndexFile.sha_to_index method for direct cache query
+		# self._entities = list()		# lazy loaded list
+		self._hit_count	= 0				# amount of hits
+		self._st_mtime = 0				# last modification data of our root path
+		
+	def _set_cache_(self, attr):
+		if attr == '_entities':
+			self._entities = list()
+			self.update_cache(force=True)
+		# END handle entities initialization
+		
+	def _sort_entities(self):
+		self._entities.sort(key=lambda l: l[0], reverse=True)
+		
+	def _pack_info(self, sha):
+		""":return: tuple(entity, index) for an item at the given sha
+		:param sha: 20 or 40 byte sha
+		:raise BadObject:
+		:note: This method is not thread-safe, but may be hit in multi-threaded
+			operation. The worst thing that can happen though is a counter that 
+			was not incremented, or the list being in wrong order. So we safe
+			the time for locking here, lets see how that goes"""
+		# presort ?
+		if self._hit_count % self._sort_interval == 0:
+			self._sort_entities()
+		# END update sorting
+		
+		for item in self._entities:
+			index = item[2](sha)
+			if index is not None:
+				item[0] += 1			# one hit for you
+				self._hit_count += 1	# general hit count
+				return (item[1], index)
+			# END index found in pack
+		# END for each item
+		
+		# no hit, see whether we have to update packs
+		# NOTE: considering packs don't change very often, we safe this call
+		# and leave it to the super-caller to trigger that
+		raise BadObject(sha)
+	
+	#{ Object DB Read 
+	
+	def has_object(self, sha):
+		try:
+			self._pack_info(sha)
+			return True
+		except BadObject:
+			return False
+		# END exception handling
+		
+	def info(self, sha):
+		entity, index = self._pack_info(sha)
+		return entity.info_at_index(index)
+	
+	def stream(self, sha):
+		entity, index = self._pack_info(sha)
+		return entity.stream_at_index(index)
+		
+	def sha_iter(self):
+		sha_list = list()
+		for entity in self.entities():
+			index = entity.index()
+			sha_by_index = index.sha
+			for index in xrange(index.size()):
+				yield sha_by_index(index)
+			# END for each index
+		# END for each entity
+	
+	def size(self):
+		sizes = [item[1].index().size() for item in self._entities]
+		return reduce(lambda x,y: x+y, sizes, 0)
+	
+	#} END object db read
+	
+	#{ object db write
+	
+	def store(self, istream):
+		"""Storing individual objects is not feasible as a pack is designed to 
+		hold multiple objects. Writing or rewriting packs for single objects is
+		inefficient"""
+		raise UnsupportedOperation()
+		
+	def store_async(self, reader):
+		# TODO: add PureObjectDBRW before implementing this
+		raise NotImplementedError()
+	
+	#} END object db write
+	
+	
+	#{ Interface 
+	
+	def update_cache(self, force=False):
+		"""
+		Update our cache with the acutally existing packs on disk. Add new ones, 
+		and remove deleted ones. We keep the unchanged ones
+		
+		:param force: If True, the cache will be updated even though the directory
+			does not appear to have changed according to its modification timestamp.
+		:return: True if the packs have been updated so there is new information, 
+			False if there was no change to the pack database"""
+		stat = os.stat(self.root_path())
+		if not force and stat.st_mtime <= self._st_mtime:
+			return False
+		# END abort early on no change
+		self._st_mtime = stat.st_mtime
+		
+		# packs are supposed to be prefixed with pack- by git-convention
+		# get all pack files, figure out what changed
+		pack_files = set(glob.glob(os.path.join(self.root_path(), "pack-*.pack")))
+		our_pack_files = set(item[1].pack().path() for item in self._entities)
+		
+		# new packs
+		for pack_file in (pack_files - our_pack_files):
+			# init the hit-counter/priority with the size, a good measure for hit-
+			# probability. Its implemented so that only 12 bytes will be read
+			entity = self.PackEntityCls(pack_file)
+			self._entities.append([entity.pack().size(), entity, entity.index().sha_to_index])
+		# END for each new packfile
+		
+		# removed packs
+		for pack_file in (our_pack_files - pack_files):
+			del_index = -1
+			for i, item in enumerate(self._entities):
+				if item[1].pack().path() == pack_file:
+					del_index = i
+					break
+				# END found index
+			# END for each entity
+			assert del_index != -1
+			del(self._entities[del_index])
+		# END for each removed pack
+		
+		# reinitialize prioritiess
+		self._sort_entities()
+		return True
+		
+	def entities(self):
+		""":return: list of pack entities operated upon by this database"""
+		return [ item[1] for item in self._entities ]
+		
+	def partial_to_complete_sha(self, partial_binsha, canonical_length):
+		""":return: 20 byte sha as inferred by the given partial binary sha
+		:param partial_binsha: binary sha with less than 20 bytes 
+		:param canonical_length: length of the corresponding canonical representation.
+			It is required as binary sha's cannot display whether the original hex sha
+			had an odd or even number of characters
+		:raise AmbiguousObjectName: 
+		:raise BadObject: """
+		candidate = None
+		for item in self._entities:
+			item_index = item[1].index().partial_sha_to_index(partial_binsha, canonical_length)
+			if item_index is not None:
+				sha = item[1].index().sha(item_index)
+				if candidate and candidate != sha:
+					raise AmbiguousObjectName(partial_binsha)
+				candidate = sha
+			# END handle full sha could be found
+		# END for each entity
+		
+		if candidate:
+			return candidate
+		
+		# still not found ?
+		raise BadObject(partial_binsha)
+	
+	#} END interface
diff --git a/git/db/py/ref.py b/git/db/py/ref.py
new file mode 100644
index 00000000..951f0437
--- /dev/null
+++ b/git/db/py/ref.py
@@ -0,0 +1,77 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from base import PureCompoundDB
+
+import os
+__all__ = ('PureReferenceDB', )
+
+class PureReferenceDB(PureCompoundDB):
+	"""A database consisting of database referred to in a file"""
+	
+	# Configuration
+	# Specifies the object database to use for the paths found in the alternates
+	# file. If None, it defaults to the PureGitODB
+	ObjectDBCls = None
+	
+	def __init__(self, ref_file):
+		super(PureReferenceDB, self).__init__()
+		self._ref_file = ref_file
+		
+	def _set_cache_(self, attr):
+		if attr == '_dbs':
+			self._dbs = list()
+			self._update_dbs_from_ref_file()
+		else:
+			super(PureReferenceDB, self)._set_cache_(attr)
+		# END handle attrs
+		
+	def _update_dbs_from_ref_file(self):
+		dbcls = self.ObjectDBCls
+		if dbcls is None:
+			# late import
+			from git import PureGitODB
+			dbcls = PureGitODB
+		# END get db type
+		
+		# try to get as many as possible, don't fail if some are unavailable
+		ref_paths = list()
+		try:
+			ref_paths = [l.strip() for l in open(self._ref_file, 'r').readlines()]
+		except (OSError, IOError):
+			pass
+		# END handle alternates
+		
+		ref_paths_set = set(ref_paths)
+		cur_ref_paths_set = set(db.root_path() for db in self._dbs)
+		
+		# remove existing
+		for path in (cur_ref_paths_set - ref_paths_set):
+			for i, db in enumerate(self._dbs[:]):
+				if db.root_path() == path:
+					del(self._dbs[i])
+					continue
+				# END del matching db
+		# END for each path to remove
+		
+		# add new
+		# sort them to maintain order
+		added_paths = sorted(ref_paths_set - cur_ref_paths_set, key=lambda p: ref_paths.index(p))
+		for path in added_paths:
+			try:
+				db = dbcls(path)
+				# force an update to verify path
+				if isinstance(db, PureCompoundDB):
+					db.databases()
+				# END verification
+				self._dbs.append(db)
+			except Exception, e:
+				# ignore invalid paths or issues
+				pass
+		# END for each path to add
+		
+	def update_cache(self, force=False):
+		# re-read alternates and update databases
+		self._update_dbs_from_ref_file()
+		return super(PureReferenceDB, self).update_cache(force)
diff --git a/git/db/py/resolve.py b/git/db/py/resolve.py
new file mode 100644
index 00000000..86c1e594
--- /dev/null
+++ b/git/db/py/resolve.py
@@ -0,0 +1,297 @@
+"""Module with an implementation for refspec parsing. It is the pure-python
+version assuming compatible interface for reference and object types"""
+
+from gitdb.db.interface import ReferencesMixin
+from gitdb.exc import BadObject
+from gitdb.ref import SymbolicReference
+from gitdb.object.base import Object
+from gitdb.util import (
+							join,
+							isdir, 
+							isfile,
+							hex_to_bin, 
+							bin_to_hex,
+							is_git_dir
+						)
+from string import digits
+import os
+import re
+
+__all__ = ["PureReferencesMixin"]
+
+#{ Utilities
+
+def short_to_long(odb, hexsha):
+	""":return: long hexadecimal sha1 from the given less-than-40 byte hexsha
+		or None if no candidate could be found.
+	:param hexsha: hexsha with less than 40 byte"""
+	try:
+		return bin_to_hex(odb.partial_to_complete_sha_hex(hexsha))
+	except BadObject:
+		return None
+	# END exception handling
+	
+	
+def name_to_object(repo, name, return_ref=False):
+	"""
+	:return: object specified by the given name, hexshas ( short and long )
+		as well as references are supported
+	:param return_ref: if name specifies a reference, we will return the reference
+		instead of the object. Otherwise it will raise BadObject
+	"""
+	hexsha = None
+	
+	# is it a hexsha ? Try the most common ones, which is 7 to 40
+	if repo.re_hexsha_shortened.match(name):
+		if len(name) != 40:
+			# find long sha for short sha
+			hexsha = short_to_long(repo.odb, name)
+		else:
+			hexsha = name
+		# END handle short shas
+	#END find sha if it matches
+	
+	# if we couldn't find an object for what seemed to be a short hexsha 
+	# try to find it as reference anyway, it could be named 'aaa' for instance
+	if hexsha is None:
+		for base in ('%s', 'refs/%s', 'refs/tags/%s', 'refs/heads/%s', 'refs/remotes/%s', 'refs/remotes/%s/HEAD'):
+			try:
+				hexsha = SymbolicReference.dereference_recursive(repo, base % name)
+				if return_ref:
+					return SymbolicReference(repo, base % name)
+				#END handle symbolic ref
+				break
+			except ValueError:
+				pass
+		# END for each base
+	# END handle hexsha
+
+	# didn't find any ref, this is an error
+	if return_ref:
+		raise BadObject("Couldn't find reference named %r" % name)
+	#END handle return ref
+
+	# tried everything ? fail
+	if hexsha is None:
+		raise BadObject(name)
+	# END assert hexsha was found
+	
+	return Object.new_from_sha(repo, hex_to_bin(hexsha))
+
+def deref_tag(tag):
+	"""Recursively dereference a tag and return the resulting object"""
+	while True:
+		try:
+			tag = tag.object
+		except AttributeError:
+			break
+	# END dereference tag
+	return tag
+
+def to_commit(obj):
+	"""Convert the given object to a commit if possible and return it"""
+	if obj.type == 'tag':
+		obj = deref_tag(obj)
+		
+	if obj.type != "commit":
+		raise ValueError("Cannot convert object %r to type commit" % obj)
+	# END verify type
+	return obj
+
+def rev_parse(repo, rev):
+	"""
+	:return: Object at the given revision, either Commit, Tag, Tree or Blob
+	:param rev: git-rev-parse compatible revision specification, please see
+		http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html
+		for details
+	:note: Currently there is no access to the rev-log, rev-specs may only contain
+		topological tokens such ~ and ^.
+	:raise BadObject: if the given revision could not be found
+	:raise ValueError: If rev couldn't be parsed
+	:raise IndexError: If invalid reflog index is specified"""
+	
+	# colon search mode ?
+	if rev.startswith(':/'):
+		# colon search mode
+		raise NotImplementedError("commit by message search ( regex )")
+	# END handle search
+	
+	obj = None
+	ref = None
+	output_type = "commit"
+	start = 0
+	parsed_to = 0
+	lr = len(rev)
+	while start < lr:
+		if rev[start] not in "^~:@":
+			start += 1
+			continue
+		# END handle start
+		
+		token = rev[start]
+		
+		if obj is None:
+			# token is a rev name
+			if start == 0:
+				ref = repo.head.ref
+			else:
+				if token == '@':
+					ref = name_to_object(repo, rev[:start], return_ref=True)
+				else:
+					obj = name_to_object(repo, rev[:start])
+				#END handle token
+			#END handle refname
+			
+			if ref is not None:
+				obj = ref.commit
+			#END handle ref
+		# END initialize obj on first token
+		
+		
+		start += 1
+		
+		# try to parse {type}
+		if start < lr and rev[start] == '{':
+			end = rev.find('}', start)
+			if end == -1:
+				raise ValueError("Missing closing brace to define type in %s" % rev)
+			output_type = rev[start+1:end]	# exclude brace
+			
+			# handle type 
+			if output_type == 'commit':
+				pass # default
+			elif output_type == 'tree':
+				try:
+					obj = to_commit(obj).tree
+				except (AttributeError, ValueError):
+					pass	# error raised later
+				# END exception handling
+			elif output_type in ('', 'blob'):
+				if obj.type == 'tag':
+					obj = deref_tag(obj)
+				else:
+					# cannot do anything for non-tags
+					pass
+				# END handle tag
+			elif token == '@':
+				# try single int
+				assert ref is not None, "Require Reference to access reflog"
+				revlog_index = None
+				try:
+					# transform reversed index into the format of our revlog
+					revlog_index = -(int(output_type)+1)
+				except ValueError:
+					# TODO: Try to parse the other date options, using parse_date
+					# maybe
+					raise NotImplementedError("Support for additional @{...} modes not implemented")
+				#END handle revlog index
+				
+				try:
+					entry = ref.log_entry(revlog_index)
+				except IndexError:
+					raise IndexError("Invalid revlog index: %i" % revlog_index)
+				#END handle index out of bound
+				
+				obj = Object.new_from_sha(repo, hex_to_bin(entry.newhexsha))
+				
+				# make it pass the following checks
+				output_type = None
+			else:
+				raise ValueError("Invalid output type: %s ( in %s )"  % (output_type, rev))
+			# END handle output type
+			
+			# empty output types don't require any specific type, its just about dereferencing tags
+			if output_type and obj.type != output_type:
+				raise ValueError("Could not accomodate requested object type %r, got %s" % (output_type, obj.type))
+			# END verify ouput type
+			
+			start = end+1					# skip brace
+			parsed_to = start
+			continue
+		# END parse type
+		
+		# try to parse a number
+		num = 0
+		if token != ":":
+			found_digit = False
+			while start < lr:
+				if rev[start] in digits:
+					num = num * 10 + int(rev[start])
+					start += 1
+					found_digit = True
+				else:
+					break
+				# END handle number
+			# END number parse loop
+			
+			# no explicit number given, 1 is the default
+			# It could be 0 though 
+			if not found_digit:
+				num = 1
+			# END set default num
+		# END number parsing only if non-blob mode
+		
+		
+		parsed_to = start
+		# handle hiererarchy walk
+		try:
+			if token == "~":
+				obj = to_commit(obj)
+				for item in xrange(num):
+					obj = obj.parents[0]
+				# END for each history item to walk
+			elif token == "^":
+				obj = to_commit(obj)
+				# must be n'th parent
+				if num:
+					obj = obj.parents[num-1]
+			elif token == ":":
+				if obj.type != "tree":
+					obj = obj.tree
+				# END get tree type
+				obj = obj[rev[start:]]
+				parsed_to = lr
+			else:
+				raise ValueError("Invalid token: %r" % token)
+			# END end handle tag
+		except (IndexError, AttributeError):
+			raise BadObject("Invalid Revision in %s" % rev)
+		# END exception handling
+	# END parse loop
+	
+	# still no obj ? Its probably a simple name
+	if obj is None:
+		obj = name_to_object(repo, rev)
+		parsed_to = lr
+	# END handle simple name
+	
+	if obj is None:
+		raise ValueError("Revision specifier could not be parsed: %s" % rev)
+
+	if parsed_to != lr:
+		raise ValueError("Didn't consume complete rev spec %s, consumed part: %s" % (rev, rev[:parsed_to]))
+	
+	return obj
+
+#} END utilities
+
+class PureReferencesMixin(ReferencesMixin):
+	"""Pure-Python refparse implementation"""
+	
+	re_hexsha_only = re.compile('^[0-9A-Fa-f]{40}$')
+	re_hexsha_shortened = re.compile('^[0-9A-Fa-f]{4,40}$')
+	
+	def resolve(self, name):
+		return rev_parse(self, name)
+		
+	@property
+	def references(self):
+		raise NotImplementedError()
+		
+	@property
+	def heads(self):
+		raise NotImplementedError()
+		
+	@property
+	def tags(self):
+		raise NotImplementedError()
diff --git a/git/db/py/transport.py b/git/db/py/transport.py
new file mode 100644
index 00000000..783fb8d5
--- /dev/null
+++ b/git/db/py/transport.py
@@ -0,0 +1,89 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Implement a transport compatible database which sends objects using the git protocol"""
+
+from gitdb.db.interface import ( TransportDB, 
+								PushInfo,
+								FetchInfo,
+								RefSpec )
+
+__all__ = ["PureTransportDB"]
+
+class PurePushInfo(PushInfo):
+	"""TODO: Implementation"""
+	__slots__ = tuple()
+	
+		
+		
+class PureFetchInfo(FetchInfo):
+	"""TODO"""
+	__slots__ = tuple()
+	
+
+class PureTransportDB(TransportDB):
+	"""A database which allows to transport objects from and to different locations
+	which are specified by urls (location) and refspecs (what to transport, 
+	see http://www.kernel.org/pub/software/scm/git/docs/git-fetch.html).
+	
+	At the beginning of a transport operation, it will be determined which objects
+	have to be sent (either by this or by the other side).
+	
+	Afterwards a pack with the required objects is sent (or received). If there is 
+	nothing to send, the pack will be empty.
+	
+	The communication itself if implemented using a protocol instance which deals
+	with the actual formatting of the lines sent.
+	
+	As refspecs involve symbolic names for references to be handled, we require
+	RefParse functionality. How this is done is up to the actual implementation."""
+	# The following variables need to be set by the derived class
+	#{Configuration
+	protocol = None
+	#}end configuraiton
+	
+	#{ Interface
+	
+	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
+			name of the remote. The implementation should allow objects as input
+			as well, these are assumed to resovle to a meaningful string though.
+		: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
+		:param kwargs: may be used for additional parameters that the actual implementation could 
+			find useful.
+		:return: List of PureFetchInfo 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 PureFetchInfo instances
+			may still contain errors or failures in only part of the refspecs.
+		:raise: if any issue occours during the transport or if the url is not 
+			supported by the protocol.
+		"""
+		raise NotImplementedError()
+		
+	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()
+		
+	@property
+	def remotes(self):
+		""":return: An IterableList of Remote objects allowing to access and manipulate remotes
+		:note: Remote objects can also be used for the actual push or fetch operation"""
+		raise NotImplementedError()
+		
+	#}end interface
+
diff --git a/git/exc.py b/git/exc.py
index d2cb8d7e..3c69067c 100644
--- a/git/exc.py
+++ b/git/exc.py
@@ -5,7 +5,40 @@
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 """ Module containing all exceptions thrown througout the git package, """
 
-from gitdb.exc import *
+from util import to_hex_sha
+
+class ODBError(Exception):
+	"""All errors thrown by the object database"""
+
+
+class InvalidDBRoot(ODBError):
+	"""Thrown if an object database cannot be initialized at the given path"""
+
+
+class BadObject(ODBError):
+	"""The object with the given SHA does not exist. Instantiate with the 
+	failed sha"""
+	
+	def __str__(self):
+		return "BadObject: %s" % to_hex_sha(self.args[0])
+
+
+class ParseError(ODBError):
+	"""Thrown if the parsing of a file failed due to an invalid format"""
+
+
+class AmbiguousObjectName(ODBError):
+	"""Thrown if a possibly shortened name does not uniquely represent a single object
+	in the database"""
+
+
+class BadObjectType(ODBError):
+	"""The object had an unsupported type"""
+
+
+class UnsupportedOperation(ODBError):
+	"""Thrown if the given operation cannot be supported by the object database"""
+
 
 class InvalidGitRepositoryError(Exception):
 	""" Thrown if the given repository appears to have an invalid format.  """
@@ -53,6 +86,7 @@ class CheckoutError( Exception ):
 class CacheError(Exception):
 	"""Base for all errors related to the git index, which is called cache internally"""
 
+
 class UnmergedEntriesError(CacheError):
 	"""Thrown if an operation cannot proceed as there are still unmerged 
 	entries in the cache"""
diff --git a/git/fun.py b/git/fun.py
new file mode 100644
index 00000000..5bbe8efc
--- /dev/null
+++ b/git/fun.py
@@ -0,0 +1,674 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Contains basic c-functions which usually contain performance critical code
+Keeping this code separate from the beginning makes it easier to out-source
+it into c later, if required"""
+
+from exc import (
+	BadObjectType
+	)
+
+from util import zlib
+decompressobj = zlib.decompressobj
+
+import mmap
+from itertools import islice, izip
+
+from cStringIO import StringIO
+
+# INVARIANTS
+OFS_DELTA = 6
+REF_DELTA = 7
+delta_types = (OFS_DELTA, REF_DELTA)
+
+type_id_to_type_map = 	{
+							0 : "",				# EXT 1
+							1 : "commit",
+							2 : "tree",
+							3 : "blob",
+							4 : "tag",
+							5 : "",				# EXT 2
+							OFS_DELTA : "OFS_DELTA", 	# OFFSET DELTA
+							REF_DELTA : "REF_DELTA"		# REFERENCE DELTA
+						}
+
+type_to_type_id_map = dict(
+							commit=1, 
+							tree=2,
+							blob=3,
+							tag=4,
+							OFS_DELTA=OFS_DELTA,
+							REF_DELTA=REF_DELTA
+						)
+
+# used when dealing with larger streams
+chunk_size = 1000*mmap.PAGESIZE
+
+__all__ = ('is_loose_object', 'loose_object_header_info', 'msb_size', 'pack_object_header_info', 
+			'write_object', 'loose_object_header', 'stream_copy', 'apply_delta_data', 
+			'is_equal_canonical_sha', 'connect_deltas', 'DeltaChunkList', 'create_pack_object_header')
+
+
+#{ Structures
+
+def _set_delta_rbound(d, size):
+	"""Truncate the given delta to the given size
+	:param size: size relative to our target offset, may not be 0, must be smaller or equal
+		to our size
+	:return: d"""
+	d.ts = size
+	
+	# NOTE: data is truncated automatically when applying the delta
+	# MUST NOT DO THIS HERE
+	return d
+			
+def _move_delta_lbound(d, bytes):
+	"""Move the delta by the given amount of bytes, reducing its size so that its
+	right bound stays static
+	:param bytes: amount of bytes to move, must be smaller than delta size
+	:return: d"""
+	if bytes == 0:
+		return
+		
+	d.to += bytes
+	d.so += bytes
+	d.ts -= bytes
+	if d.data is not None:
+		d.data = d.data[bytes:]
+	# END handle data
+	
+	return d
+	
+def delta_duplicate(src):
+	return DeltaChunk(src.to, src.ts, src.so, src.data)
+	
+def delta_chunk_apply(dc, bbuf, write):
+	"""Apply own data to the target buffer
+	:param bbuf: buffer providing source bytes for copy operations
+	:param write: write method to call with data to write"""
+	if dc.data is None:
+		# COPY DATA FROM SOURCE
+		write(buffer(bbuf, dc.so, dc.ts))
+	else:
+		# APPEND DATA
+		# whats faster: if + 4 function calls or just a write with a slice ?
+		# Considering data can be larger than 127 bytes now, it should be worth it
+		if dc.ts < len(dc.data):
+			write(dc.data[:dc.ts])
+		else:
+			write(dc.data)
+		# END handle truncation
+	# END handle chunk mode
+
+
+class DeltaChunk(object):
+	"""Represents a piece of a delta, it can either add new data, or copy existing
+	one from a source buffer"""
+	__slots__ = (
+					'to',		# start offset in the target buffer in bytes 
+					'ts',		# size of this chunk in the target buffer in bytes
+					'so',		# start offset in the source buffer in bytes or None
+					'data',		# chunk of bytes to be added to the target buffer,
+								# DeltaChunkList to use as base, or None
+				)
+	
+	def __init__(self, to, ts, so, data):
+		self.to = to
+		self.ts = ts
+		self.so = so
+		self.data = data
+
+	def __repr__(self):
+		return "DeltaChunk(%i, %i, %s, %s)" % (self.to, self.ts, self.so, self.data or "")
+	
+	#{ Interface
+		
+	def rbound(self):
+		return self.to + self.ts
+		
+	def has_data(self):
+		""":return: True if the instance has data to add to the target stream"""
+		return self.data is not None
+		
+	#} END interface
+
+def _closest_index(dcl, absofs):
+	""":return: index at which the given absofs should be inserted. The index points
+	to the DeltaChunk with a target buffer absofs that equals or is greater than
+	absofs. 
+	:note: global method for performance only, it belongs to DeltaChunkList"""
+	lo = 0
+	hi = len(dcl)
+	while lo < hi:
+		mid = (lo + hi) / 2
+		dc = dcl[mid]
+		if dc.to > absofs:
+			hi = mid
+		elif dc.rbound() > absofs or dc.to == absofs:
+			return mid
+		else:
+			lo = mid + 1
+		# END handle bound
+	# END for each delta absofs
+	return len(dcl)-1
+	
+def delta_list_apply(dcl, bbuf, write):
+	"""Apply the chain's changes and write the final result using the passed
+	write function.
+	:param bbuf: base buffer containing the base of all deltas contained in this
+		list. It will only be used if the chunk in question does not have a base
+		chain.
+	:param write: function taking a string of bytes to write to the output"""
+	for dc in dcl:
+		delta_chunk_apply(dc, bbuf, write)
+	# END for each dc
+
+def delta_list_slice(dcl, absofs, size, ndcl):
+	""":return: Subsection of this  list at the given absolute  offset, with the given 
+		size in bytes.
+	:return: None"""
+	cdi = _closest_index(dcl, absofs)	# delta start index
+	cd = dcl[cdi]
+	slen = len(dcl)
+	lappend = ndcl.append 
+	
+	if cd.to != absofs:
+		tcd = DeltaChunk(cd.to, cd.ts, cd.so, cd.data)
+		_move_delta_lbound(tcd, absofs - cd.to)
+		tcd.ts = min(tcd.ts, size)
+		lappend(tcd)
+		size -= tcd.ts
+		cdi += 1
+	# END lbound overlap handling
+	
+	while cdi < slen and size:
+		# are we larger than the current block
+		cd = dcl[cdi]
+		if cd.ts <= size:
+			lappend(DeltaChunk(cd.to, cd.ts, cd.so, cd.data))
+			size -= cd.ts
+		else:
+			tcd = DeltaChunk(cd.to, cd.ts, cd.so, cd.data)
+			tcd.ts = size
+			lappend(tcd)
+			size -= tcd.ts
+			break
+		# END hadle size
+		cdi += 1
+	# END for each chunk
+	
+	
+class DeltaChunkList(list):
+	"""List with special functionality to deal with DeltaChunks.
+	There are two types of lists we represent. The one was created bottom-up, working
+	towards the latest delta, the other kind was created top-down, working from the 
+	latest delta down to the earliest ancestor. This attribute is queryable 
+	after all processing with is_reversed."""
+	
+	__slots__ = tuple()
+	
+	def rbound(self):
+		""":return: rightmost extend in bytes, absolute"""
+		if len(self) == 0:
+			return 0
+		return self[-1].rbound()
+		
+	def lbound(self):
+		""":return: leftmost byte at which this chunklist starts"""
+		if len(self) == 0:
+			return 0
+		return self[0].to
+		
+	def size(self):
+		""":return: size of bytes as measured by our delta chunks"""
+		return self.rbound() - self.lbound()
+		
+	def apply(self, bbuf, write):
+		"""Only used by public clients, internally we only use the global routines
+		for performance"""
+		return delta_list_apply(self, bbuf, write)
+		
+	def compress(self):
+		"""Alter the list to reduce the amount of nodes. Currently we concatenate
+		add-chunks
+		:return: self"""
+		slen = len(self)
+		if slen < 2:
+			return self
+		i = 0
+		slen_orig = slen
+		
+		first_data_index = None
+		while i < slen:
+			dc = self[i]
+			i += 1
+			if dc.data is None:
+				if first_data_index is not None and i-2-first_data_index > 1:
+				#if first_data_index is not None:
+					nd = StringIO()						# new data
+					so = self[first_data_index].to		# start offset in target buffer
+					for x in xrange(first_data_index, i-1):
+						xdc = self[x]
+						nd.write(xdc.data[:xdc.ts])
+					# END collect data
+					
+					del(self[first_data_index:i-1])
+					buf = nd.getvalue()
+					self.insert(first_data_index, DeltaChunk(so, len(buf), 0, buf)) 
+					
+					slen = len(self)
+					i = first_data_index + 1
+					
+				# END concatenate data
+				first_data_index = None
+				continue
+			# END skip non-data chunks
+			
+			if first_data_index is None:
+				first_data_index = i-1
+		# END iterate list
+		
+		#if slen_orig != len(self):
+		#	print "INFO: Reduced delta list len to %f %% of former size" % ((float(len(self)) / slen_orig) * 100)
+		return self
+		
+	def check_integrity(self, target_size=-1):
+		"""Verify the list has non-overlapping chunks only, and the total size matches
+		target_size
+		:param target_size: if not -1, the total size of the chain must be target_size
+		:raise AssertionError: if the size doen't match"""
+		if target_size > -1:
+			assert self[-1].rbound() == target_size
+			assert reduce(lambda x,y: x+y, (d.ts for d in self), 0) == target_size
+		# END target size verification
+		
+		if len(self) < 2:
+			return
+			
+		# check data
+		for dc in self:
+			assert dc.ts > 0
+			if dc.has_data():
+				assert len(dc.data) >= dc.ts
+		# END for each dc
+			
+		left = islice(self, 0, len(self)-1)
+		right = iter(self)
+		right.next()
+		# this is very pythonic - we might have just use index based access here, 
+		# but this could actually be faster
+		for lft,rgt in izip(left, right):
+			assert lft.rbound() == rgt.to
+			assert lft.to + lft.ts == rgt.to
+		# END for each pair
+		
+
+class TopdownDeltaChunkList(DeltaChunkList):
+	"""Represents a list which is generated by feeding its ancestor streams one by 
+	one"""
+	__slots__ = tuple() 
+	
+	def connect_with_next_base(self, bdcl):
+		"""Connect this chain with the next level of our base delta chunklist.
+		The goal in this game is to mark as many of our chunks rigid, hence they
+		cannot be changed by any of the upcoming bases anymore. Once all our 
+		chunks are marked like that, we can stop all processing
+		:param bdcl: data chunk list being one of our bases. They must be fed in 
+			consequtively and in order, towards the earliest ancestor delta
+		:return: True if processing was done. Use it to abort processing of
+			remaining streams if False is returned"""
+		nfc = 0								# number of frozen chunks
+		dci = 0								# delta chunk index
+		slen = len(self)					# len of self
+		ccl = list()						# temporary list
+		while dci < slen:
+			dc = self[dci]
+			dci += 1
+			
+			# all add-chunks which are already topmost don't need additional processing
+			if dc.data is not None:
+				nfc += 1
+				continue
+			# END skip add chunks
+			
+			# copy chunks
+			# integrate the portion of the base list into ourselves. Lists
+			# dont support efficient insertion ( just one at a time ), but for now
+			# we live with it. Internally, its all just a 32/64bit pointer, and
+			# the portions of moved memory should be smallish. Maybe we just rebuild
+			# ourselves in order to reduce the amount of insertions ...
+			del(ccl[:])
+			delta_list_slice(bdcl, dc.so, dc.ts, ccl)
+			
+			# move the target bounds into place to match with our chunk
+			ofs = dc.to - dc.so
+			for cdc in ccl:
+				cdc.to += ofs
+			# END update target bounds
+			
+			if len(ccl) == 1:
+				self[dci-1] = ccl[0]
+			else:
+				# maybe try to compute the expenses here, and pick the right algorithm
+				# It would normally be faster than copying everything physically though
+				# TODO: Use a deque here, and decide by the index whether to extend
+				# or extend left !
+				post_dci = self[dci:]
+				del(self[dci-1:])			# include deletion of dc
+				self.extend(ccl)
+				self.extend(post_dci)
+				
+				slen = len(self)
+				dci += len(ccl)-1			# deleted dc, added rest
+				
+			# END handle chunk replacement
+		# END for each chunk
+		
+		if nfc == slen:
+			return False
+		# END handle completeness
+		return True
+		
+		
+#} END structures
+
+#{ Routines
+
+def is_loose_object(m):
+	"""
+	:return: True the file contained in memory map m appears to be a loose object.
+		Only the first two bytes are needed"""
+	b0, b1 = map(ord, m[:2])
+	word = (b0 << 8) + b1
+	return b0 == 0x78 and (word % 31) == 0
+
+def loose_object_header_info(m):
+	"""
+	:return: tuple(type_string, uncompressed_size_in_bytes) the type string of the 
+		object as well as its uncompressed size in bytes.
+	:param m: memory map from which to read the compressed object data"""
+	decompress_size = 8192		# is used in cgit as well
+	hdr = decompressobj().decompress(m, decompress_size)
+	type_name, size = hdr[:hdr.find("\0")].split(" ")
+	return type_name, int(size)
+	
+def pack_object_header_info(data):
+	"""
+	:return: tuple(type_id, uncompressed_size_in_bytes, byte_offset)
+		The type_id should be interpreted according to the ``type_id_to_type_map`` map
+		The byte-offset specifies the start of the actual zlib compressed datastream
+	:param m: random-access memory, like a string or memory map"""
+	c = ord(data[0])				# first byte
+	i = 1							# next char to read
+	type_id = (c >> 4) & 7			# numeric type
+	size = c & 15					# starting size
+	s = 4							# starting bit-shift size
+	while c & 0x80:
+		c = ord(data[i])
+		i += 1
+		size += (c & 0x7f) << s
+		s += 7
+	# END character loop
+	return (type_id, size, i)
+
+def create_pack_object_header(obj_type, obj_size):
+	""":return: string defining the pack header comprised of the object type
+	and its incompressed size in bytes
+	:parmam obj_type: pack type_id of the object
+	:param obj_size: uncompressed size in bytes of the following object stream"""
+	c = 0		# 1 byte
+	hdr = str()	# output string
+
+	c = (obj_type << 4) | (obj_size & 0xf)
+	obj_size >>= 4
+	while obj_size:
+		hdr += chr(c | 0x80)
+		c = obj_size & 0x7f
+		obj_size >>= 7
+	#END until size is consumed
+	hdr += chr(c)
+	return hdr
+	
+def msb_size(data, offset=0):
+	"""
+	:return: tuple(read_bytes, size) read the msb size from the given random 
+		access data starting at the given byte offset"""
+	size = 0
+	i = 0
+	l = len(data)
+	hit_msb = False
+	while i < l:
+		c = ord(data[i+offset])
+		size |= (c & 0x7f) << i*7
+		i += 1
+		if not c & 0x80:
+			hit_msb = True
+			break
+		# END check msb bit
+	# END while in range
+	if not hit_msb:
+		raise AssertionError("Could not find terminating MSB byte in data stream")
+	return i+offset, size 
+	
+def loose_object_header(type, size):
+	"""
+	:return: string representing the loose object header, which is immediately
+		followed by the content stream of size 'size'"""
+	return "%s %i\0" % (type, size)
+		
+def write_object(type, size, read, write, chunk_size=chunk_size):
+	"""
+	Write the object as identified by type, size and source_stream into the 
+	target_stream
+	
+	:param type: type string of the object
+	:param size: amount of bytes to write from source_stream
+	:param read: read method of a stream providing the content data
+	:param write: write method of the output stream
+	:param close_target_stream: if True, the target stream will be closed when
+		the routine exits, even if an error is thrown
+	:return: The actual amount of bytes written to stream, which includes the header and a trailing newline"""
+	tbw = 0												# total num bytes written
+	
+	# WRITE HEADER: type SP size NULL
+	tbw += write(loose_object_header(type, size))
+	tbw += stream_copy(read, write, size, chunk_size)
+	
+	return tbw
+
+def stream_copy(read, write, size, chunk_size):
+	"""
+	Copy a stream up to size bytes using the provided read and write methods, 
+	in chunks of chunk_size
+	
+	:note: its much like stream_copy utility, but operates just using methods"""
+	dbw = 0												# num data bytes written
+	
+	# WRITE ALL DATA UP TO SIZE
+	while True:
+		cs = min(chunk_size, size-dbw)
+		# NOTE: not all write methods return the amount of written bytes, like
+		# mmap.write. Its bad, but we just deal with it ... perhaps its not 
+		# even less efficient
+		# data_len = write(read(cs))
+		# dbw += data_len
+		data = read(cs)
+		data_len = len(data)
+		dbw += data_len
+		write(data)
+		if data_len < cs or dbw == size:
+			break
+		# END check for stream end
+	# END duplicate data
+	return dbw
+	
+def connect_deltas(dstreams):
+	"""
+	Read the condensed delta chunk information from dstream and merge its information
+		into a list of existing delta chunks
+	
+	:param dstreams: iterable of delta stream objects, the delta to be applied last
+		comes first, then all its ancestors in order
+	:return: DeltaChunkList, containing all operations to apply"""
+	tdcl = None							# topmost dcl
+	
+	dcl = tdcl = TopdownDeltaChunkList()
+	for dsi, ds in enumerate(dstreams):
+		# print "Stream", dsi
+		db = ds.read()
+		delta_buf_size = ds.size
+		
+		# read header
+		i, base_size = msb_size(db)
+		i, target_size = msb_size(db, i)
+		
+		# interpret opcodes
+		tbw = 0						# amount of target bytes written
+		while i < delta_buf_size:
+			c = ord(db[i])
+			i += 1
+			if c & 0x80:
+				cp_off, cp_size = 0, 0
+				if (c & 0x01):
+					cp_off = ord(db[i])
+					i += 1
+				if (c & 0x02):
+					cp_off |= (ord(db[i]) << 8)
+					i += 1
+				if (c & 0x04):
+					cp_off |= (ord(db[i]) << 16)
+					i += 1
+				if (c & 0x08):
+					cp_off |= (ord(db[i]) << 24)
+					i += 1
+				if (c & 0x10):
+					cp_size = ord(db[i])
+					i += 1
+				if (c & 0x20):
+					cp_size |= (ord(db[i]) << 8)
+					i += 1
+				if (c & 0x40):
+					cp_size |= (ord(db[i]) << 16)
+					i += 1
+					
+				if not cp_size: 
+					cp_size = 0x10000
+				
+				rbound = cp_off + cp_size
+				if (rbound < cp_size or
+					rbound > base_size):
+					break
+				
+				dcl.append(DeltaChunk(tbw, cp_size, cp_off, None))
+				tbw += cp_size
+			elif c:
+				# NOTE: in C, the data chunks should probably be concatenated here.
+				# In python, we do it as a post-process
+				dcl.append(DeltaChunk(tbw, c, 0, db[i:i+c]))
+				i += c
+				tbw += c
+			else:
+				raise ValueError("unexpected delta opcode 0")
+			# END handle command byte
+		# END while processing delta data
+		
+		dcl.compress()
+		
+		# merge the lists !
+		if dsi > 0:
+			if not tdcl.connect_with_next_base(dcl):
+				break
+		# END handle merge
+		
+		# prepare next base
+		dcl = DeltaChunkList()
+	# END for each delta stream
+	
+	return tdcl
+	
+def apply_delta_data(src_buf, src_buf_size, delta_buf, delta_buf_size, write):
+	"""
+	Apply data from a delta buffer using a source buffer to the target file
+	
+	:param src_buf: random access data from which the delta was created
+	:param src_buf_size: size of the source buffer in bytes
+	:param delta_buf_size: size fo the delta buffer in bytes
+	:param delta_buf: random access delta data
+	:param write: write method taking a chunk of bytes
+	:note: transcribed to python from the similar routine in patch-delta.c"""
+	i = 0
+	db = delta_buf
+	while i < delta_buf_size:
+		c = ord(db[i])
+		i += 1
+		if c & 0x80:
+			cp_off, cp_size = 0, 0
+			if (c & 0x01):
+				cp_off = ord(db[i])
+				i += 1
+			if (c & 0x02):
+				cp_off |= (ord(db[i]) << 8)
+				i += 1
+			if (c & 0x04):
+				cp_off |= (ord(db[i]) << 16)
+				i += 1
+			if (c & 0x08):
+				cp_off |= (ord(db[i]) << 24)
+				i += 1
+			if (c & 0x10):
+				cp_size = ord(db[i])
+				i += 1
+			if (c & 0x20):
+				cp_size |= (ord(db[i]) << 8)
+				i += 1
+			if (c & 0x40):
+				cp_size |= (ord(db[i]) << 16)
+				i += 1
+				
+			if not cp_size: 
+				cp_size = 0x10000
+			
+			rbound = cp_off + cp_size
+			if (rbound < cp_size or
+			    rbound > src_buf_size):
+				break
+			write(buffer(src_buf, cp_off, cp_size))
+		elif c:
+			write(db[i:i+c])
+			i += c
+		else:
+			raise ValueError("unexpected delta opcode 0")
+		# END handle command byte
+	# END while processing delta data
+	
+	# yes, lets use the exact same error message that git uses :)
+	assert i == delta_buf_size, "delta replay has gone wild"
+	
+	
+def is_equal_canonical_sha(canonical_length, match, sha1):
+	"""
+	:return: True if the given lhs and rhs 20 byte binary shas
+		The comparison will take the canonical_length of the match sha into account, 
+		hence the comparison will only use the last 4 bytes for uneven canonical representations
+	:param match: less than 20 byte sha
+	:param sha1: 20 byte sha"""
+	binary_length = canonical_length/2
+	if match[:binary_length] != sha1[:binary_length]:
+		return False
+		
+	if canonical_length - binary_length and \
+		(ord(match[-1]) ^ ord(sha1[len(match)-1])) & 0xf0:
+		return False
+	# END handle uneven canonnical length
+	return True
+	
+#} END routines
+
+
+try:
+	# raise ImportError; # DEBUG
+	from _perf import connect_deltas
+except ImportError:
+	pass
diff --git a/git/objects/base.py b/git/objects/base.py
index 42d7b600..24967e7b 100644
--- a/git/objects/base.py
+++ b/git/objects/base.py
@@ -3,6 +3,177 @@
 #
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
-from gitdb.object.base import Object, IndexObject 
+
+from util import get_object_type_by_name
+from git.util import (
+							hex_to_bin,
+							bin_to_hex,
+							dirname,
+							basename, 
+							LazyMixin, 
+							join_path_native, 
+							stream_copy
+						)
+
+from git.typ import ObjectType
+	
+_assertion_msg_format = "Created object %r whose python type %r disagrees with the acutal git object type %r"
+
 __all__ = ("Object", "IndexObject")
 
+class Object(LazyMixin):
+	"""Implements an Object which may be Blobs, Trees, Commits and Tags"""
+	NULL_HEX_SHA = '0'*40
+	NULL_BIN_SHA = '\0'*20
+	
+	TYPES = (ObjectType.blob, ObjectType.tree, ObjectType.commit, ObjectType.tag)
+	__slots__ = ("odb", "binsha", "size" )
+	
+	type = None			# to be set by subclass
+	type_id = None		# to be set by subclass
+	
+	def __init__(self, odb, binsha):
+		"""Initialize an object by identifying it by its binary sha. 
+		All keyword arguments will be set on demand if None.
+		
+		:param odb: repository this object is located in
+			
+		:param binsha: 20 byte SHA1"""
+		super(Object,self).__init__()
+		self.odb = odb
+		self.binsha = binsha
+		assert len(binsha) == 20, "Require 20 byte binary sha, got %r, len = %i" % (binsha, len(binsha))
+
+	@classmethod
+	def new(cls, odb, id):
+		"""
+		:return: New Object instance of a type appropriate to the object type behind 
+			id. The id of the newly created object will be a binsha even though 
+			the input id may have been a Reference or Rev-Spec
+			
+		:param id: reference, rev-spec, or hexsha
+			
+		:note: This cannot be a __new__ method as it would always call __init__
+			with the input id which is not necessarily a binsha."""
+		return odb.rev_parse(str(id))
+		
+	@classmethod
+	def new_from_sha(cls, odb, sha1):
+		"""
+		:return: new object instance of a type appropriate to represent the given 
+			binary sha1
+		:param sha1: 20 byte binary sha1"""
+		if sha1 == cls.NULL_BIN_SHA:
+			# the NULL binsha is always the root commit
+			return get_object_type_by_name('commit')(odb, sha1)
+		#END handle special case
+		oinfo = odb.info(sha1)
+		inst = get_object_type_by_name(oinfo.type)(odb, oinfo.binsha)
+		inst.size = oinfo.size
+		return inst 
+	
+	def _set_cache_(self, attr):
+		"""Retrieve object information"""
+		if attr	 == "size":
+			oinfo = self.odb.info(self.binsha)
+			self.size = oinfo.size
+			# assert oinfo.type == self.type, _assertion_msg_format % (self.binsha, oinfo.type, self.type)
+		else:
+			super(Object,self)._set_cache_(attr)
+		
+	def __eq__(self, other):
+		""":return: True if the objects have the same SHA1"""
+		return self.binsha == other.binsha
+		
+	def __ne__(self, other):
+		""":return: True if the objects do not have the same SHA1 """
+		return self.binsha != other.binsha
+		
+	def __hash__(self):
+		""":return: Hash of our id allowing objects to be used in dicts and sets"""
+		return hash(self.binsha)
+		
+	def __str__(self):
+		""":return: string of our SHA1 as understood by all git commands"""
+		return bin_to_hex(self.binsha)
+		
+	def __repr__(self):
+		""":return: string with pythonic representation of our object"""
+		return '<git.%s "%s">' % (self.__class__.__name__, self.hexsha)
+
+	@property
+	def hexsha(self):
+		""":return: 40 byte hex version of our 20 byte binary sha"""
+		return bin_to_hex(self.binsha)
+
+	@property
+	def data_stream(self):
+		""" :return:  File Object compatible stream to the uncompressed raw data of the object
+		:note: returned streams must be read in order"""
+		return self.odb.stream(self.binsha)
+
+	def stream_data(self, ostream):
+		"""Writes our data directly to the given output stream
+		:param ostream: File object compatible stream object.
+		:return: self"""
+		istream = self.odb.stream(self.binsha)
+		stream_copy(istream, ostream)
+		return self
+		
+
+class IndexObject(Object):
+	"""Base for all objects that can be part of the index file , namely Tree, Blob and
+	SubModule objects"""
+	__slots__ = ("path", "mode")
+	
+	# for compatability with iterable lists
+	_id_attribute_ = 'path'
+	
+	def __init__(self, odb, binsha, mode=None, path=None):
+		"""Initialize a newly instanced IndexObject
+		:param odb: is the object database we are located in
+		:param binsha: 20 byte sha1
+		:param mode: is the stat compatible file mode as int, use the stat module
+			to evaluate the infomration
+		:param path:
+			is the path to the file in the file system, relative to the git repository root, i.e.
+			file.ext or folder/other.ext
+		:note:
+			Path may not be set of the index object has been created directly as it cannot
+			be retrieved without knowing the parent tree."""
+		super(IndexObject, self).__init__(odb, binsha)
+		if mode is not None:
+			self.mode = mode
+		if path is not None:
+			self.path = path
+	
+	def __hash__(self):
+		""":return:
+			Hash of our path as index items are uniquely identifyable by path, not 
+			by their data !"""
+		return hash(self.path)
+	
+	def _set_cache_(self, attr):
+		if attr in IndexObject.__slots__:
+			# they cannot be retrieved lateron ( not without searching for them )
+			raise AttributeError( "path and mode attributes must have been set during %s object creation" % type(self).__name__ )
+		else:
+			super(IndexObject, self)._set_cache_(attr)
+		# END hanlde slot attribute
+	
+	@property
+	def name(self):
+		""":return: Name portion of the path, effectively being the basename"""
+		return basename(self.path)
+		
+	@property
+	def abspath(self):
+		"""
+		:return:
+			Absolute path to this index object in the file system ( as opposed to the 
+			.path field which is a path relative to the git repository ).
+			
+			The returned path will be native to the system and contains '\' on windows. """
+		assert False, "Only works if repository is not bare - provide this check in an interface"
+		return join_path_native(dirname(self.odb.root_path()), self.path)
+		
diff --git a/git/objects/blob.py b/git/objects/blob.py
index 38834436..326c5459 100644
--- a/git/objects/blob.py
+++ b/git/objects/blob.py
@@ -5,9 +5,32 @@
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 
 from git.util import RepoAliasMixin
-from gitdb.object.blob import Blob as GitDB_Blob
+from mimetypes import guess_type
+from gitdb.typ import ObjectType
+
+import base
 
 __all__ = ('Blob', )
 
-class Blob(GitDB_Blob, RepoAliasMixin):
+class Blob(base.IndexObject, RepoAliasMixin):
+	"""A Blob encapsulates a git blob object"""
+	DEFAULT_MIME_TYPE = "text/plain"
+	type = ObjectType.blob
+	type_id = ObjectType.blob_id
+	
+	# valid blob modes
+	executable_mode = 0100755
+	file_mode = 0100644
+	link_mode = 0120000
+
 	__slots__ = tuple()
+
+	@property
+	def mime_type(self):
+		"""
+		:return: String describing the mime type of this file (based on the filename)
+		:note: Defaults to 'text/plain' in case the actual file type is unknown. """
+		guesses = None
+		if self.path:
+			guesses = guess_type(self.path)
+		return guesses and guesses[0] or self.DEFAULT_MIME_TYPE
diff --git a/git/objects/commit.py b/git/objects/commit.py
index d932ab1a..30dcaa0a 100644
--- a/git/objects/commit.py
+++ b/git/objects/commit.py
@@ -3,28 +3,68 @@
 #
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
-from git.util import RepoAliasMixin
-from gitdb.object.commit import Commit as GitDB_Commit
-from git.diff import Diffable
+import base
+
+from gitdb.typ import ObjectType
+from tree import Tree
+from cStringIO import StringIO
+
 from gitdb.util import (
+						hex_to_bin,
+						Actor,
+						RepoAliasMixin,
 						Iterable,
 						Actor
 						)
 
-from gitdb import IStream
+from util import (
+					Traversable,
+					Serializable,
+					altz_to_utctz_str,
+					parse_actor_and_date
+				)
+from git.diff import Diffable
+from gitdb.base import IStream
 from cStringIO import StringIO
 
 from util import parse_date
 from time import altzone
 
 import os
+import sys
 
 __all__ = ('Commit', )
 
-class Commit(GitDB_Commit, Diffable, Iterable, RepoAliasMixin):
-	"""Provides additional git-command based functionality to the default gitdb commit object"""
+class Commit(GitDB_Commit, Diffable, Iterable, RepoAliasMixin, base.Object, Traversable, Serializable):
+	"""Wraps a git Commit object.
+	
+	This class will act lazily on some of its attributes and will query the 
+	value on demand only if it involves calling the git binary."""
 	__slots__ = tuple()
 	
+	# ENVIRONMENT VARIABLES
+	# read when creating new commits
+	env_author_date = "GIT_AUTHOR_DATE"
+	env_committer_date = "GIT_COMMITTER_DATE"
+	
+	# CONFIGURATION KEYS
+	conf_encoding = 'i18n.commitencoding'
+	
+	# INVARIANTS
+	default_encoding = "UTF-8"
+	
+	
+	# object configuration 
+	type = ObjectType.commit
+	type_id = ObjectType.commit_id
+	
+	__slots__ = ("tree",
+				 "author", "authored_date", "author_tz_offset",
+				 "committer", "committed_date", "committer_tz_offset",
+				 "message", "parents", "encoding")
+	_id_attribute_ = "binsha"
+	
+	
 	def count(self, paths='', **kwargs):
 		"""Count the number of commits reachable from this commit
 
@@ -221,4 +261,211 @@ class Commit(GitDB_Commit, Diffable, Iterable, RepoAliasMixin):
 		
 		return new_commit
 		
+	def __init__(self, odb, binsha, tree=None, author=None, authored_date=None, author_tz_offset=None,
+				 committer=None, committed_date=None, committer_tz_offset=None, 
+				 message=None,  parents=None, encoding=None):
+		"""Instantiate a new Commit. All keyword arguments taking None as default will 
+		be implicitly set on first query. 
+		
+		:param binsha: 20 byte sha1
+		:param parents: tuple( Commit, ... ) 
+			is a tuple of commit ids or actual Commits
+		:param tree: Tree
+			Tree object
+		:param author: Actor
+			is the author string ( will be implicitly converted into an Actor object )
+		:param authored_date: int_seconds_since_epoch
+			is the authored DateTime - use time.gmtime() to convert it into a 
+			different format
+		:param author_tz_offset: int_seconds_west_of_utc
+			is the timezone that the authored_date is in
+		:param committer: Actor
+			is the committer string
+		:param committed_date: int_seconds_since_epoch
+			is the committed DateTime - use time.gmtime() to convert it into a 
+			different format
+		:param committer_tz_offset: int_seconds_west_of_utc
+			is the timezone that the authored_date is in
+		:param message: string
+			is the commit message
+		:param encoding: string
+			encoding of the message, defaults to UTF-8
+		:param parents:
+			List or tuple of Commit objects which are our parent(s) in the commit 
+			dependency graph
+		:return: git.Commit
+		
+		:note: Timezone information is in the same format and in the same sign 
+			as what time.altzone returns. The sign is inverted compared to git's 
+			UTC timezone."""
+		super(Commit,self).__init__(odb, binsha)
+		if tree is not None:
+			assert isinstance(tree, Tree), "Tree needs to be a Tree instance, was %s" % type(tree)
+		if tree is not None:
+			self.tree = tree
+		if author is not None:
+			self.author = author
+		if authored_date is not None:
+			self.authored_date = authored_date
+		if author_tz_offset is not None:
+			self.author_tz_offset = author_tz_offset
+		if committer is not None:
+			self.committer = committer
+		if committed_date is not None:
+			self.committed_date = committed_date
+		if committer_tz_offset is not None:
+			self.committer_tz_offset = committer_tz_offset
+		if message is not None:
+			self.message = message
+		if parents is not None:
+			self.parents = parents
+		if encoding is not None:
+			self.encoding = encoding
+		
+	@classmethod
+	def _get_intermediate_items(cls, commit):
+		return commit.parents
+
+	def _set_cache_(self, attr):
+		if attr in Commit.__slots__:
+			# read the data in a chunk, its faster - then provide a file wrapper
+			binsha, typename, self.size, stream = self.odb.stream(self.binsha)
+			self._deserialize(StringIO(stream.read()))
+		else:
+			super(Commit, self)._set_cache_(attr)
+		# END handle attrs
+
+	@property
+	def summary(self):
+		""":return: First line of the commit message"""
+		return self.message.split('\n', 1)[0]
+		
+	@classmethod
+	def _iter_from_process_or_stream(cls, odb, proc_or_stream):
+		"""Parse out commit information into a list of Commit objects
+		We expect one-line per commit, and parse the actual commit information directly
+		from our lighting fast object database
+
+		:param proc: git-rev-list process instance - one sha per line
+		:return: iterator returning Commit objects"""
+		stream = proc_or_stream
+		if not hasattr(stream,'readline'):
+			stream = proc_or_stream.stdout
+			
+		readline = stream.readline
+		while True:
+			line = readline()
+			if not line:
+				break
+			hexsha = line.strip()
+			if len(hexsha) > 40:
+				# split additional information, as returned by bisect for instance
+				hexsha, rest = line.split(None, 1)
+			# END handle extra info
+			
+			assert len(hexsha) == 40, "Invalid line: %s" % hexsha
+			yield cls(odb, hex_to_bin(hexsha))
+		# END for each line in stream
+	
+	#{ Serializable Implementation
+	
+	def _serialize(self, stream):
+		write = stream.write
+		write("tree %s\n" % self.tree)
+		for p in self.parents:
+			write("parent %s\n" % p)
+			
+		a = self.author
+		aname = a.name
+		if isinstance(aname, unicode):
+			aname = aname.encode(self.encoding)
+		# END handle unicode in name
+		
+		c = self.committer
+		fmt = "%s %s <%s> %s %s\n"
+		write(fmt % ("author", aname, a.email, 
+						self.authored_date, 
+						altz_to_utctz_str(self.author_tz_offset)))
+			
+		# encode committer
+		aname = c.name
+		if isinstance(aname, unicode):
+			aname = aname.encode(self.encoding)
+		# END handle unicode in name
+		write(fmt % ("committer", aname, c.email, 
+						self.committed_date,
+						altz_to_utctz_str(self.committer_tz_offset)))
+		
+		if self.encoding != self.default_encoding:
+			write("encoding %s\n" % self.encoding)
+		
+		write("\n")
+		
+		# write plain bytes, be sure its encoded according to our encoding
+		if isinstance(self.message, unicode):
+			write(self.message.encode(self.encoding))
+		else:
+			write(self.message)
+		# END handle encoding
+		return self
+	
+	def _deserialize(self, stream):
+		""":param from_rev_list: if true, the stream format is coming from the rev-list command
+		Otherwise it is assumed to be a plain data stream from our object"""
+		readline = stream.readline
+		self.tree = Tree(self.odb, hex_to_bin(readline().split()[1]), Tree.tree_id<<12, '')
+
+		self.parents = list()
+		next_line = None
+		while True:
+			parent_line = readline()
+			if not parent_line.startswith('parent'):
+				next_line = parent_line
+				break
+			# END abort reading parents
+			self.parents.append(type(self)(self.odb, hex_to_bin(parent_line.split()[-1])))
+		# END for each parent line
+		self.parents = tuple(self.parents)
+		
+		self.author, self.authored_date, self.author_tz_offset = parse_actor_and_date(next_line)
+		self.committer, self.committed_date, self.committer_tz_offset = parse_actor_and_date(readline())
+		
+		
+		# now we can have the encoding line, or an empty line followed by the optional
+		# message.
+		self.encoding = self.default_encoding
+		# read encoding or empty line to separate message
+		enc = readline()
+		enc = enc.strip()
+		if enc:
+			self.encoding = enc[enc.find(' ')+1:]
+			# now comes the message separator 
+			readline()
+		# END handle encoding
+		
+		# decode the authors name
+		try:
+			self.author.name = self.author.name.decode(self.encoding) 
+		except UnicodeDecodeError:
+			print >> sys.stderr, "Failed to decode author name '%s' using encoding %s" % (self.author.name, self.encoding)
+		# END handle author's encoding
+		
+		# decode committer name
+		try:
+			self.committer.name = self.committer.name.decode(self.encoding) 
+		except UnicodeDecodeError:
+			print >> sys.stderr, "Failed to decode committer name '%s' using encoding %s" % (self.committer.name, self.encoding)
+		# END handle author's encoding
+		
+		# a stream from our data simply gives us the plain message
+		# The end of our message stream is marked with a newline that we strip
+		self.message = stream.read()
+		try:
+			self.message = self.message.decode(self.encoding)
+		except UnicodeDecodeError:
+			print >> sys.stderr, "Failed to decode message '%s' using encoding %s" % (self.message, self.encoding)
+		# END exception handling 
+		return self
+	
 	#} END serializable implementation
+
diff --git a/git/objects/fun.py b/git/objects/fun.py
index 2443bad7..6f2eaaad 100644
--- a/git/objects/fun.py
+++ b/git/objects/fun.py
@@ -1,4 +1,201 @@
 """Module with functions which are supposed to be as fast as possible"""
 
-from gitdb.object.fun import *
+from stat import S_ISDIR
+
+__all__ = ('tree_to_stream', 'tree_entries_from_data', 'traverse_trees_recursive',
+			'traverse_tree_recursive')
+
+
+				
+
+def tree_to_stream(entries, write):
+	"""Write the give list of entries into a stream using its write method
+	:param entries: **sorted** list of tuples with (binsha, mode, name)
+	:param write: write method which takes a data string"""
+	ord_zero = ord('0')
+	bit_mask = 7			# 3 bits set
+	
+	for binsha, mode, name in entries:
+		mode_str = ''
+		for i in xrange(6):
+			mode_str = chr(((mode >> (i*3)) & bit_mask) + ord_zero) + mode_str
+		# END for each 8 octal value
+		
+		# git slices away the first octal if its zero
+		if mode_str[0] == '0':
+			mode_str = mode_str[1:]
+		# END save a byte
+
+		# here it comes:  if the name is actually unicode, the replacement below
+		# will not work as the binsha is not part of the ascii unicode encoding - 
+		# hence we must convert to an utf8 string for it to work properly.
+		# According to my tests, this is exactly what git does, that is it just
+		# takes the input literally, which appears to be utf8 on linux.
+		if isinstance(name, unicode):
+			name = name.encode("utf8")
+		write("%s %s\0%s" % (mode_str, name, binsha)) 
+	# END for each item
+
+
+def tree_entries_from_data(data):
+	"""Reads the binary representation of a tree and returns tuples of Tree items
+	:param data: data block with tree data
+	:return: list(tuple(binsha, mode, tree_relative_path), ...)"""
+	ord_zero = ord('0')
+	len_data = len(data)
+	i = 0
+	out = list()
+	while i < len_data:
+		mode = 0
+		
+		# read mode
+		# Some git versions truncate the leading 0, some don't
+		# The type will be extracted from the mode later
+		while data[i] != ' ':
+			# move existing mode integer up one level being 3 bits
+			# and add the actual ordinal value of the character
+			mode = (mode << 3) + (ord(data[i]) - ord_zero)
+			i += 1
+		# END while reading mode
+		
+		# byte is space now, skip it
+		i += 1
+		
+		# parse name, it is NULL separated
+		
+		ns = i
+		while data[i] != '\0':
+			i += 1
+		# END while not reached NULL
+		
+		# default encoding for strings in git is utf8
+		# Only use the respective unicode object if the byte stream was encoded
+		name = data[ns:i]
+		name_enc = name.decode("utf-8")
+		if len(name) > len(name_enc):
+			name = name_enc
+		# END handle encoding
+		
+		# byte is NULL, get next 20
+		i += 1
+		sha = data[i:i+20]
+		i = i + 20
+		out.append((sha, mode, name))
+	# END for each byte in data stream
+	return out
+	
+	
+def _find_by_name(tree_data, name, is_dir, start_at):
+	"""return data entry matching the given name and tree mode
+	or None.
+	Before the item is returned, the respective data item is set 
+	None in the tree_data list to mark it done"""
+	try:
+		item = tree_data[start_at]
+		if item and  item[2] == name and S_ISDIR(item[1]) == is_dir:
+			tree_data[start_at] = None
+			return item
+	except IndexError:
+		pass
+	# END exception handling
+	for index, item in enumerate(tree_data):
+		if item and item[2] == name and S_ISDIR(item[1]) == is_dir:
+			tree_data[index] = None
+			return item
+		# END if item matches
+	# END for each item
+	return None
+
+def _to_full_path(item, path_prefix):
+	"""Rebuild entry with given path prefix"""
+	if not item:
+		return item
+	return (item[0], item[1], path_prefix+item[2])
+	
+def traverse_trees_recursive(odb, tree_shas, path_prefix):
+	"""
+	:return: list with entries according to the given binary tree-shas. 
+		The result is encoded in a list
+		of n tuple|None per blob/commit, (n == len(tree_shas)), where 
+		* [0] == 20 byte sha
+		* [1] == mode as int
+		* [2] == path relative to working tree root
+		The entry tuple is None if the respective blob/commit did not 
+		exist in the given tree.
+	:param tree_shas: iterable of shas pointing to trees. All trees must 
+		be on the same level. A tree-sha may be None in which case None
+	:param path_prefix: a prefix to be added to the returned paths on this level, 
+		set it '' for the first iteration
+	:note: The ordering of the returned items will be partially lost"""
+	trees_data = list()
+	nt = len(tree_shas)
+	for tree_sha in tree_shas:
+		if tree_sha is None:
+			data = list()
+		else:
+			data = tree_entries_from_data(odb.stream(tree_sha).read())
+		# END handle muted trees
+		trees_data.append(data)
+	# END for each sha to get data for
+	
+	out = list()
+	out_append = out.append
+	
+	# find all matching entries and recursively process them together if the match
+	# is a tree. If the match is a non-tree item, put it into the result.
+	# Processed items will be set None
+	for ti, tree_data in enumerate(trees_data):
+		for ii, item in enumerate(tree_data):
+			if not item:
+				continue
+			# END skip already done items
+			entries = [ None for n in range(nt) ]
+			entries[ti] = item
+			sha, mode, name = item							# its faster to unpack
+			is_dir = S_ISDIR(mode)							# type mode bits
+			
+			# find this item in all other tree data items
+			# wrap around, but stop one before our current index, hence 
+			# ti+nt, not ti+1+nt
+			for tio in range(ti+1, ti+nt):
+				tio = tio % nt
+				entries[tio] = _find_by_name(trees_data[tio], name, is_dir, ii)
+			# END for each other item data
+			
+			# if we are a directory, enter recursion
+			if is_dir:
+				out.extend(traverse_trees_recursive(odb, [((ei and ei[0]) or None) for ei in entries], path_prefix+name+'/'))
+			else:
+				out_append(tuple(_to_full_path(e, path_prefix) for e in entries))
+			# END handle recursion
+			
+			# finally mark it done
+			tree_data[ii] = None
+		# END for each item
+		
+		# we are done with one tree, set all its data empty
+		del(tree_data[:])
+	# END for each tree_data chunk
+	return out
+	
+def traverse_tree_recursive(odb, tree_sha, path_prefix):
+	"""
+	:return: list of entries of the tree pointed to by the binary tree_sha. An entry
+		has the following format:
+		* [0] 20 byte sha
+		* [1] mode as int
+		* [2] path relative to the repository
+	:param path_prefix: prefix to prepend to the front of all returned paths"""
+	entries = list()
+	data = tree_entries_from_data(odb.stream(tree_sha).read())
+	
+	# unpacking/packing is faster than accessing individual items
+	for sha, mode, name in data:
+		if S_ISDIR(mode):
+			entries.extend(traverse_tree_recursive(odb, sha, path_prefix+name+'/'))
+		else:
+			entries.append((sha, mode, path_prefix+name))
+	# END for each item
+	
+	return entries
 
diff --git a/git/objects/submodule/base.py b/git/objects/submodule/base.py
index 7997e5e5..9b45d9b6 100644
--- a/git/objects/submodule/base.py
+++ b/git/objects/submodule/base.py
@@ -73,6 +73,9 @@ class Submodule(GitDB_Submodule, Iterable, Traversable, RepoAliasMixin):
 	# this is a bogus type for base class compatability
 	type = 'submodule'
 	
+	# this type doesn't really have a type id
+	type_id = 0
+	
 	__slots__ = ('_parent_commit', '_url', '_branch_path', '_name', '__weakref__')
 	_cache_attrs = ('path', '_url', '_branch_path')
 	
diff --git a/git/objects/tag.py b/git/objects/tag.py
index 59b2362e..0bd1d20c 100644
--- a/git/objects/tag.py
+++ b/git/objects/tag.py
@@ -4,10 +4,77 @@
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 """ Module containing all object based types. """
+import base
 from git.util import RepoAliasMixin
-from gitdb.object.tag import TagObject as GitDB_TagObject
+from gitdb.util import hex_to_bin
+from util import (
+					get_object_type_by_name,
+					parse_actor_and_date
+				)
+from gitdb.typ import ObjectType
+
 __all__ = ("TagObject", )
 
-class TagObject(GitDB_TagObject, RepoAliasMixin):
+class TagObject(base.Object, RepoAliasMixin):
 	"""Non-Lightweight tag carrying additional information about an object we are pointing to."""
-	__slots__ = tuple()
+	type = ObjectType.tag
+	type_id = ObjectType.tag_id
+	
+	__slots__ = ( "object", "tag", "tagger", "tagged_date", "tagger_tz_offset", "message" )
+		
+	def __init__(self, odb, binsha, object=None, tag=None, 
+				tagger=None, tagged_date=None, tagger_tz_offset=None, message=None):
+		"""Initialize a tag object with additional data
+		
+		:param odb: repository this object is located in
+		:param binsha: 20 byte SHA1
+		:param object: Object instance of object we are pointing to
+		:param tag: name of this tag
+		:param tagger: Actor identifying the tagger
+		:param tagged_date: int_seconds_since_epoch
+			is the DateTime of the tag creation - use time.gmtime to convert 
+			it into a different format
+		:param tagged_tz_offset: int_seconds_west_of_utc is the timezone that the 
+			authored_date is in, in a format similar to time.altzone"""
+		super(TagObject, self).__init__(odb, binsha )
+		if object is not None:
+			self.object = object
+		if tag is not None:
+			self.tag = tag
+		if tagger is not None:
+			self.tagger = tagger
+		if tagged_date is not None:
+			self.tagged_date = tagged_date
+		if tagger_tz_offset is not None:
+			self.tagger_tz_offset = tagger_tz_offset
+		if message is not None:
+			self.message = message
+		
+	def _set_cache_(self, attr):
+		"""Cache all our attributes at once"""
+		if attr in TagObject.__slots__:
+			ostream = self.odb.stream(self.binsha)
+			lines = ostream.read().splitlines()
+			
+			obj, hexsha = lines[0].split(" ")		# object <hexsha>
+			type_token, type_name = lines[1].split(" ") # type <type_name>
+			self.object = get_object_type_by_name(type_name)(self.odb, hex_to_bin(hexsha))
+			
+			self.tag = lines[2][4:]	 # tag <tag name>
+			
+			tagger_info = lines[3][7:]# tagger <actor> <date>
+			self.tagger, self.tagged_date, self.tagger_tz_offset = parse_actor_and_date(tagger_info)
+			
+			# line 4 empty - it could mark the beginning of the next header
+			# in case there really is no message, it would not exist. Otherwise 
+			# a newline separates header from message
+			if len(lines) > 5:
+				self.message = "\n".join(lines[5:])
+			else:
+				self.message = ''
+		# END check our attributes
+		else:
+			super(TagObject, self)._set_cache_(attr)
+		
+		
+
diff --git a/git/objects/tree.py b/git/objects/tree.py
index 00ef07fc..1b5f7561 100644
--- a/git/objects/tree.py
+++ b/git/objects/tree.py
@@ -4,26 +4,286 @@
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 from git.util import RepoAliasMixin
-from gitdb.object.tree import Tree as GitDB_Tree
-from gitdb.object.tree import TreeModifier
 import git.diff as diff
-
+from gitdb.typ import ObjectType
+from base import IndexObject
 from blob import Blob
-from submodule.base import Submodule
+from submodule import Submodule
+
+from fun import (
+					tree_entries_from_data, 
+					tree_to_stream
+				 )
+
+from gitdb.util import (
+						to_bin_sha,
+						join_path
+						)
+import util
 
 __all__ = ("TreeModifier", "Tree")
 
-class Tree(GitDB_Tree, diff.Diffable):
-	"""As opposed to the default GitDB tree implementation, this one can be diffed
-	and returns our own types"""
-	__slots__ = tuple()
+class TreeModifier(object):
+	"""A utility class providing methods to alter the underlying cache in a list-like fashion.
+	
+	Once all adjustments are complete, the _cache, which really is a refernce to 
+	the cache of a tree, will be sorted. Assuring it will be in a serializable state"""
+	__slots__ = '_cache'
+	
+	def __init__(self, cache):
+		self._cache = cache
+	
+	def _index_by_name(self, name):
+		""":return: index of an item with name, or -1 if not found"""
+		for i, t in enumerate(self._cache):
+			if t[2] == name:
+				return i
+			# END found item
+		# END for each item in cache
+		return -1
+	
+	#{ Interface 
+	def set_done(self):
+		"""Call this method once you are done modifying the tree information.
+		It may be called several times, but be aware that each call will cause 
+		a sort operation
+		:return self:"""
+		self._cache.sort(key=lambda t: t[2])	# sort by name
+		return self
+	#} END interface
+	
+	#{ Mutators
+	def add(self, sha, mode, name, force=False):
+		"""Add the given item to the tree. If an item with the given name already
+		exists, nothing will be done, but a ValueError will be raised if the 
+		sha and mode of the existing item do not match the one you add, unless 
+		force is True
+		
+		:param sha: The 20 or 40 byte sha of the item to add
+		:param mode: int representing the stat compatible mode of the item
+		:param force: If True, an item with your name and information will overwrite
+			any existing item with the same name, no matter which information it has
+		:return: self"""
+		if '/' in name:
+			raise ValueError("Name must not contain '/' characters")
+		if (mode >> 12) not in Tree._map_id_to_type:
+			raise ValueError("Invalid object type according to mode %o" % mode)
+			
+		sha = to_bin_sha(sha)
+		index = self._index_by_name(name)
+		item = (sha, mode, name)
+		if index == -1:
+			self._cache.append(item)
+		else:
+			if force:
+				self._cache[index] = item
+			else:
+				ex_item = self._cache[index]
+				if ex_item[0] != sha or ex_item[1] != mode:
+					raise ValueError("Item %r existed with different properties" % name)
+				# END handle mismatch
+			# END handle force
+		# END handle name exists
+		return self
+		
+	def add_unchecked(self, binsha, mode, name):
+		"""Add the given item to the tree, its correctness is assumed, which 
+		puts the caller into responsibility to assure the input is correct. 
+		For more information on the parameters, see ``add``
+		:param binsha: 20 byte binary sha"""
+		self._cache.append((binsha, mode, name))
+		
+	def __delitem__(self, name):
+		"""Deletes an item with the given name if it exists"""
+		index = self._index_by_name(name)
+		if index > -1:
+			del(self._cache[index])
+		
+	#} END mutators
+
+
+class Tree(IndexObject, diff.Diffable, util.Traversable, util.Serializable, RepoAliasMixin):
+	"""Tree objects represent an ordered list of Blobs and other Trees.
+	
+	``Tree as a list``::
+		
+		Access a specific blob using the  
+		tree['filename'] notation.
+		
+		You may as well access by index
+		blob = tree[0]
+	"""
+	
+	type = ObjectType.tree
+	type_id = ObjectType.tree_id
+	
+	__slots__ = "_cache"
+	
+	# actual integer ids for comparison 
+	commit_id = 016		# equals stat.S_IFDIR | stat.S_IFLNK - a directory link
+	blob_id = 010
+	symlink_id = 012
+	tree_id = 004
 	
+	#{ Configuration
+	
+	# override in subclass if you would like your own types to be instantiated instead
 	_map_id_to_type = {
-						GitDB_Tree.commit_id : Submodule, 
-						GitDB_Tree.blob_id : Blob, 
-						GitDB_Tree.symlink_id : Blob
+						commit_id : Submodule, 
+						blob_id : Blob, 
+						symlink_id : Blob
 						# tree id added once Tree is defined
 						}
 	
+	#} end configuration
+	
+	
+	def __init__(self, repo, binsha, mode=tree_id<<12, path=None):
+		super(Tree, self).__init__(repo, binsha, mode, path)
+
+	@classmethod
+	def _get_intermediate_items(cls, index_object):
+		if index_object.type == "tree":
+			return tuple(index_object._iter_convert_to_object(index_object._cache))
+		return tuple()
+
+	def _set_cache_(self, attr):
+		if attr == "_cache":
+			# Set the data when we need it
+			ostream = self.odb.stream(self.binsha)
+			self._cache = tree_entries_from_data(ostream.read())
+		else:
+			super(Tree, self)._set_cache_(attr)
+		# END handle attribute 
+
+	def _iter_convert_to_object(self, iterable):
+		"""Iterable yields tuples of (binsha, mode, name), which will be converted
+		to the respective object representation"""
+		for binsha, mode, name in iterable:
+			path = join_path(self.path, name)
+			try:
+				yield self._map_id_to_type[mode >> 12](self.repo, binsha, mode, path)
+			except KeyError:
+				raise TypeError("Unknown mode %o found in tree data for path '%s'" % (mode, path))
+		# END for each item 
+
+	def __div__(self, file):
+		"""Find the named object in this tree's contents
+		:return: ``git.Blob`` or ``git.Tree`` or ``git.Submodule``
+		
+		:raise KeyError: if given file or tree does not exist in tree"""
+		msg = "Blob or Tree named %r not found"
+		if '/' in file:
+			tree = self
+			item = self
+			tokens = file.split('/')
+			for i,token in enumerate(tokens):
+				item = tree[token]
+				if item.type == 'tree':
+					tree = item
+				else:
+					# safety assertion - blobs are at the end of the path
+					if i != len(tokens)-1:
+						raise KeyError(msg % file)
+					return item
+				# END handle item type
+			# END for each token of split path
+			if item == self:
+				raise KeyError(msg % file)
+			return item
+		else:
+			for info in self._cache:
+				if info[2] == file:		# [2] == name
+					return self._map_id_to_type[info[1] >> 12](self.repo, info[0], info[1], join_path(self.path, info[2]))
+			# END for each obj
+			raise KeyError( msg % file )
+		# END handle long paths
+
+
+	@property
+	def trees(self):
+		""":return: list(Tree, ...) list of trees directly below this tree"""
+		return [ i for i in self if i.type == "tree" ]
+		
+	@property
+	def blobs(self):
+		""":return: list(Blob, ...) list of blobs directly below this tree"""
+		return [ i for i in self if i.type == "blob" ]
+
+	@property
+	def cache(self):
+		"""
+		:return: An object allowing to modify the internal cache. This can be used
+			to change the tree's contents. When done, make sure you call ``set_done``
+			on the tree modifier, or serialization behaviour will be incorrect.
+			See the ``TreeModifier`` for more information on how to alter the cache"""
+		return TreeModifier(self._cache)
+
+	def traverse( self, predicate = lambda i,d: True,
+						   prune = lambda i,d: False, depth = -1, branch_first=True,
+						   visit_once = False, ignore_self=1 ):
+		"""For documentation, see util.Traversable.traverse
+		Trees are set to visit_once = False to gain more performance in the traversal"""
+		return super(Tree, self).traverse(predicate, prune, depth, branch_first, visit_once, ignore_self)
+
+	# List protocol
+	def __getslice__(self, i, j):
+		return list(self._iter_convert_to_object(self._cache[i:j]))
+		
+	def __iter__(self):
+		return self._iter_convert_to_object(self._cache)
+		
+	def __len__(self):
+		return len(self._cache)
+		
+	def __getitem__(self, item):
+		if isinstance(item, int):
+			info = self._cache[item]
+			return self._map_id_to_type[info[1] >> 12](self.repo, info[0], info[1], join_path(self.path, info[2]))
+		
+		if isinstance(item, basestring):
+			# compatability
+			return self.__div__(item)
+		# END index is basestring 
+		
+		raise TypeError( "Invalid index type: %r" % item )
+		
+		
+	def __contains__(self, item):
+		if isinstance(item, IndexObject):
+			for info in self._cache:
+				if item.binsha == info[0]:
+					return True
+				# END compare sha
+			# END for each entry
+		# END handle item is index object
+		# compatability
+		
+		# treat item as repo-relative path
+		path = self.path
+		for info in self._cache:
+			if item == join_path(path, info[2]):
+				return True
+		# END for each item
+		return False
+	
+	def __reversed__(self):
+		return reversed(self._iter_convert_to_object(self._cache))
+		
+	def _serialize(self, stream):
+		"""Serialize this tree into the stream. Please note that we will assume 
+		our tree data to be in a sorted state. If this is not the case, serialization
+		will not generate a correct tree representation as these are assumed to be sorted
+		by algorithms"""
+		tree_to_stream(self._cache, stream.write)
+		return self
+		
+	def _deserialize(self, stream):
+		self._cache = tree_entries_from_data(stream.read())
+		return self
+		
+		
+# END tree
+
 # finalize map definition
 Tree._map_id_to_type[Tree.tree_id] = Tree
diff --git a/git/objects/util.py b/git/objects/util.py
index 4c9323b8..8ac590f2 100644
--- a/git/objects/util.py
+++ b/git/objects/util.py
@@ -20,6 +20,7 @@ __all__ = ('get_object_type_by_name', 'parse_date', 'parse_actor_and_date',
 			'ProcessStreamAdapter', 'Traversable', 'altz_to_utctz_str', 'utctz_to_altz', 
 			'verify_utctz', 'Actor')
 
+
 #{ Functions
 
 def mode_str_to_int(modestr):
diff --git a/git/pack.py b/git/pack.py
new file mode 100644
index 00000000..7ae9786e
--- /dev/null
+++ b/git/pack.py
@@ -0,0 +1,1005 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Contains PackIndexFile and PackFile implementations"""
+from gitdb.exc import (
+						BadObject,
+						UnsupportedOperation,
+						ParseError
+						)
+from util import (
+					zlib,
+					LazyMixin,
+					unpack_from,
+					bin_to_hex,
+					file_contents_ro_filepath,
+					)
+
+from fun import (
+					create_pack_object_header,
+					pack_object_header_info,
+					is_equal_canonical_sha,
+					type_id_to_type_map,
+					write_object,
+					stream_copy, 
+					chunk_size,
+					delta_types,
+					OFS_DELTA, 
+					REF_DELTA,
+					msb_size
+				)
+
+try:
+	from _perf import PackIndexFile_sha_to_index
+except ImportError:
+	pass
+# END try c module
+
+from base import (		# Amazing !
+						OInfo,
+						OStream,
+						OPackInfo,
+						OPackStream,
+						ODeltaStream,
+						ODeltaPackInfo,
+						ODeltaPackStream,
+					)
+from stream import (
+						DecompressMemMapReader,
+						DeltaApplyReader,
+						Sha1Writer,
+						NullStream,
+						FlexibleSha1Writer
+					)
+
+from struct import (
+						pack,
+						unpack,
+					)
+
+from binascii import crc32
+
+from itertools import izip
+import tempfile
+import array
+import os
+import sys
+
+__all__ = ('PackIndexFile', 'PackFile', 'PackEntity')
+
+ 
+
+	
+#{ Utilities 
+
+def pack_object_at(data, offset, as_stream):
+	"""
+	:return: Tuple(abs_data_offset, PackInfo|PackStream)
+		an object of the correct type according to the type_id  of the object.
+		If as_stream is True, the object will contain a stream, allowing  the
+		data to be read decompressed.
+	:param data: random accessable data containing all required information
+	:parma offset: offset in to the data at which the object information is located
+	:param as_stream: if True, a stream object will be returned that can read 
+		the data, otherwise you receive an info object only"""
+	data = buffer(data, offset)
+	type_id, uncomp_size, data_rela_offset = pack_object_header_info(data)
+	total_rela_offset = None				# set later, actual offset until data stream begins
+	delta_info = None
+	
+	# OFFSET DELTA
+	if type_id == OFS_DELTA:
+		i = data_rela_offset
+		c = ord(data[i])
+		i += 1
+		delta_offset = c & 0x7f
+		while c & 0x80:
+			c = ord(data[i])
+			i += 1
+			delta_offset += 1
+			delta_offset = (delta_offset << 7) + (c & 0x7f)
+		# END character loop
+		delta_info = delta_offset
+		total_rela_offset = i
+	# REF DELTA
+	elif type_id == REF_DELTA:
+		total_rela_offset = data_rela_offset+20
+		delta_info = data[data_rela_offset:total_rela_offset]
+	# BASE OBJECT
+	else:
+		# assume its a base object
+		total_rela_offset = data_rela_offset
+	# END handle type id
+	
+	abs_data_offset = offset + total_rela_offset
+	if as_stream:
+		stream = DecompressMemMapReader(buffer(data, total_rela_offset), False, uncomp_size)
+		if delta_info is None:
+			return abs_data_offset, OPackStream(offset, type_id, uncomp_size, stream)
+		else:
+			return abs_data_offset, ODeltaPackStream(offset, type_id, uncomp_size, delta_info, stream)
+	else:
+		if delta_info is None:
+			return abs_data_offset, OPackInfo(offset, type_id, uncomp_size)
+		else:
+			return abs_data_offset, ODeltaPackInfo(offset, type_id, uncomp_size, delta_info)
+		# END handle info
+	# END handle stream
+
+def write_stream_to_pack(read, write, zstream, base_crc=None):
+	"""Copy a stream as read from read function, zip it, and write the result.
+	Count the number of written bytes and return it
+	:param base_crc: if not None, the crc will be the base for all compressed data
+		we consecutively write and generate a crc32 from. If None, no crc will be generated
+	:return: tuple(no bytes read, no bytes written, crc32) crc might be 0 if base_crc
+		was false"""
+	br = 0		# bytes read
+	bw = 0		# bytes written
+	want_crc = base_crc is not None
+	crc = 0
+	if want_crc:
+		crc = base_crc
+	#END initialize crc
+	
+	while True:
+		chunk = read(chunk_size)
+		br += len(chunk)
+		compressed = zstream.compress(chunk)
+		bw += len(compressed)
+		write(compressed)			# cannot assume return value
+		
+		if want_crc:
+			crc = crc32(compressed, crc)
+		#END handle crc
+		
+		if len(chunk) != chunk_size:
+			break
+	#END copy loop
+	
+	compressed = zstream.flush()
+	bw += len(compressed)
+	write(compressed)
+	if want_crc:
+		crc = crc32(compressed, crc)
+	#END handle crc
+	
+	return (br, bw, crc)
+
+
+#} END utilities
+
+
+class IndexWriter(object):
+	"""Utility to cache index information, allowing to write all information later
+	in one go to the given stream
+	:note: currently only writes v2 indices"""
+	__slots__ = '_objs'
+	
+	def __init__(self):
+		self._objs = list()
+		
+	def append(self, binsha, crc, offset):
+		"""Append one piece of object information"""
+		self._objs.append((binsha, crc, offset))
+		
+	def write(self, pack_sha, write):
+		"""Write the index file using the given write method
+		:param pack_sha: binary sha over the whole pack that we index
+		:return: sha1 binary sha over all index file contents"""
+		# sort for sha1 hash
+		self._objs.sort(key=lambda o: o[0])
+		
+		sha_writer = FlexibleSha1Writer(write)
+		sha_write = sha_writer.write
+		sha_write(PackIndexFile.index_v2_signature)
+		sha_write(pack(">L", PackIndexFile.index_version_default))
+		
+		# fanout
+		tmplist = list((0,)*256)								# fanout or list with 64 bit offsets
+		for t in self._objs:
+			tmplist[ord(t[0][0])] += 1
+		#END prepare fanout
+		for i in xrange(255):
+			v = tmplist[i]
+			sha_write(pack('>L', v))
+			tmplist[i+1] += v
+		#END write each fanout entry
+		sha_write(pack('>L', tmplist[255]))
+		
+		# sha1 ordered
+		# save calls, that is push them into c
+		sha_write(''.join(t[0] for t in self._objs))
+		
+		# crc32
+		for t in self._objs:
+			sha_write(pack('>L', t[1]&0xffffffff))
+		#END for each crc
+		
+		tmplist = list()
+		# offset 32
+		for t in self._objs:
+			ofs = t[2]
+			if ofs > 0x7fffffff:
+				tmplist.append(ofs)
+				ofs = 0x80000000 + len(tmplist)-1
+			#END hande 64 bit offsets
+			sha_write(pack('>L', ofs&0xffffffff))
+		#END for each offset
+		
+		# offset 64
+		for ofs in tmplist:
+			sha_write(pack(">Q", ofs))
+		#END for each offset
+		
+		# trailer
+		assert(len(pack_sha) == 20)
+		sha_write(pack_sha)
+		sha = sha_writer.sha(as_hex=False)
+		write(sha)
+		return sha
+		
+	
+
+class PackIndexFile(LazyMixin):
+	"""A pack index provides offsets into the corresponding pack, allowing to find
+	locations for offsets faster."""
+	
+	# Dont use slots as we dynamically bind functions for each version, need a dict for this
+	# The slots you see here are just to keep track of our instance variables
+	# __slots__ = ('_indexpath', '_fanout_table', '_data', '_version', 
+	#				'_sha_list_offset', '_crc_list_offset', '_pack_offset', '_pack_64_offset')
+
+	# used in v2 indices
+	_sha_list_offset = 8 + 1024
+	index_v2_signature = '\377tOc'
+	index_version_default = 2
+
+	def __init__(self, indexpath):
+		super(PackIndexFile, self).__init__()
+		self._indexpath = indexpath
+	
+	def _set_cache_(self, attr):
+		if attr == "_packfile_checksum":
+			self._packfile_checksum = self._data[-40:-20]
+		elif attr == "_packfile_checksum":
+			self._packfile_checksum = self._data[-20:]
+		elif attr == "_data":
+			# Note: We don't lock the file when reading as we cannot be sure
+			# that we can actually write to the location - it could be a read-only
+			# alternate for instance
+			self._data = file_contents_ro_filepath(self._indexpath)
+		else:
+			# now its time to initialize everything - if we are here, someone wants
+			# to access the fanout table or related properties
+			
+			# CHECK VERSION
+			self._version = (self._data[:4] == self.index_v2_signature and 2) or 1
+			if self._version == 2:
+				version_id = unpack_from(">L", self._data, 4)[0] 
+				assert version_id == self._version, "Unsupported index version: %i" % version_id
+			# END assert version
+			
+			# SETUP FUNCTIONS
+			# setup our functions according to the actual version
+			for fname in ('entry', 'offset', 'sha', 'crc'):
+				setattr(self, fname, getattr(self, "_%s_v%i" % (fname, self._version)))
+			# END for each function to initialize
+			
+			
+			# INITIALIZE DATA
+			# byte offset is 8 if version is 2, 0 otherwise
+			self._initialize()
+		# END handle attributes
+		
+
+	#{ Access V1
+	
+	def _entry_v1(self, i):
+		""":return: tuple(offset, binsha, 0)"""
+		return unpack_from(">L20s", self._data, 1024 + i*24) + (0, ) 
+	
+	def _offset_v1(self, i):
+		"""see ``_offset_v2``"""
+		return unpack_from(">L", self._data, 1024 + i*24)[0]
+	
+	def _sha_v1(self, i):
+		"""see ``_sha_v2``"""
+		base = 1024 + (i*24)+4
+		return self._data[base:base+20]
+		
+	def _crc_v1(self, i):
+		"""unsupported"""
+		return 0
+		
+	#} END access V1
+	
+	#{ Access V2
+	def _entry_v2(self, i):
+		""":return: tuple(offset, binsha, crc)"""
+		return (self._offset_v2(i), self._sha_v2(i), self._crc_v2(i))
+	
+	def _offset_v2(self, i):
+		""":return: 32 or 64 byte offset into pack files. 64 byte offsets will only 
+			be returned if the pack is larger than 4 GiB, or 2^32"""
+		offset = unpack_from(">L", self._data, self._pack_offset + i * 4)[0]
+		
+		# if the high-bit is set, this indicates that we have to lookup the offset
+		# in the 64 bit region of the file. The current offset ( lower 31 bits )
+		# are the index into it
+		if offset & 0x80000000:
+			offset = unpack_from(">Q", self._data, self._pack_64_offset + (offset & ~0x80000000) * 8)[0]
+		# END handle 64 bit offset
+		
+		return offset
+		
+	def _sha_v2(self, i):
+		""":return: sha at the given index of this file index instance"""
+		base = self._sha_list_offset + i * 20
+		return self._data[base:base+20]
+		
+	def _crc_v2(self, i):
+		""":return: 4 bytes crc for the object at index i"""
+		return unpack_from(">L", self._data, self._crc_list_offset + i * 4)[0] 
+		
+	#} END access V2
+	
+	#{ Initialization
+	
+	def _initialize(self):
+		"""initialize base data"""
+		self._fanout_table = self._read_fanout((self._version == 2) * 8)
+		
+		if self._version == 2:
+			self._crc_list_offset = self._sha_list_offset + self.size() * 20
+			self._pack_offset = self._crc_list_offset + self.size() * 4
+			self._pack_64_offset = self._pack_offset + self.size() * 4
+		# END setup base
+		
+	def _read_fanout(self, byte_offset):
+		"""Generate a fanout table from our data"""
+		d = self._data
+		out = list()
+		append = out.append
+		for i in range(256):
+			append(unpack_from('>L', d, byte_offset + i*4)[0])
+		# END for each entry
+		return out
+	
+	#} END initialization
+		
+	#{ Properties
+	def version(self):
+		return self._version
+		
+	def size(self):
+		""":return: amount of objects referred to by this index"""
+		return self._fanout_table[255]
+		
+	def path(self):
+		""":return: path to the packindexfile"""
+		return self._indexpath
+		
+	def packfile_checksum(self):
+		""":return: 20 byte sha representing the sha1 hash of the pack file"""
+		return self._data[-40:-20]
+		
+	def indexfile_checksum(self):
+		""":return: 20 byte sha representing the sha1 hash of this index file"""
+		return self._data[-20:]
+		
+	def offsets(self):
+		""":return: sequence of all offsets in the order in which they were written
+		:note: return value can be random accessed, but may be immmutable"""
+		if self._version == 2:
+			# read stream to array, convert to tuple
+			a = array.array('I')	# 4 byte unsigned int, long are 8 byte on 64 bit it appears
+			a.fromstring(buffer(self._data, self._pack_offset, self._pack_64_offset - self._pack_offset))
+			
+			# networkbyteorder to something array likes more
+			if sys.byteorder == 'little':
+				a.byteswap()
+			return a
+		else:
+			return tuple(self.offset(index) for index in xrange(self.size()))
+		# END handle version
+		
+	def sha_to_index(self, sha):
+		"""
+		:return: index usable with the ``offset`` or ``entry`` method, or None
+			if the sha was not found in this pack index
+		:param sha: 20 byte sha to lookup"""
+		first_byte = ord(sha[0])
+		get_sha = self.sha
+		lo = 0					# lower index, the left bound of the bisection
+		if first_byte != 0:
+			lo = self._fanout_table[first_byte-1]
+		hi = self._fanout_table[first_byte]		# the upper, right bound of the bisection
+		
+		# bisect until we have the sha
+		while lo < hi:
+			mid = (lo + hi) / 2
+			c = cmp(sha, get_sha(mid))
+			if c < 0:
+				hi = mid
+			elif not c:
+				return mid
+			else:
+				lo = mid + 1
+			# END handle midpoint
+		# END bisect
+		return None
+		
+	def partial_sha_to_index(self, partial_bin_sha, canonical_length):
+		"""
+		:return: index as in `sha_to_index` or None if the sha was not found in this
+			index file
+		:param partial_bin_sha: an at least two bytes of a partial binary sha
+		:param canonical_length: lenght of the original hexadecimal representation of the 
+			given partial binary sha
+		:raise AmbiguousObjectName:"""
+		if len(partial_bin_sha) < 2:
+			raise ValueError("Require at least 2 bytes of partial sha")
+		
+		first_byte = ord(partial_bin_sha[0])
+		get_sha = self.sha
+		lo = 0					# lower index, the left bound of the bisection
+		if first_byte != 0:
+			lo = self._fanout_table[first_byte-1]
+		hi = self._fanout_table[first_byte]		# the upper, right bound of the bisection
+		
+		# fill the partial to full 20 bytes
+		filled_sha = partial_bin_sha + '\0'*(20 - len(partial_bin_sha))
+		
+		# find lowest 
+		while lo < hi:
+			mid = (lo + hi) / 2
+			c = cmp(filled_sha, get_sha(mid))
+			if c < 0:
+				hi = mid
+			elif not c:
+				# perfect match
+				lo = mid
+				break
+			else:
+				lo = mid + 1
+			# END handle midpoint
+		# END bisect
+		
+		if lo < self.size():
+			cur_sha = get_sha(lo)
+			if is_equal_canonical_sha(canonical_length, partial_bin_sha, cur_sha):
+				next_sha = None
+				if lo+1 < self.size():
+					next_sha = get_sha(lo+1)
+				if next_sha and next_sha == cur_sha:
+					raise AmbiguousObjectName(partial_bin_sha)
+				return lo
+			# END if we have a match
+		# END if we found something
+		return None
+		
+	if 'PackIndexFile_sha_to_index' in globals():
+		# NOTE: Its just about 25% faster, the major bottleneck might be the attr 
+		# accesses
+		def sha_to_index(self, sha):
+			return PackIndexFile_sha_to_index(self, sha)
+	# END redefine heavy-hitter with c version  
+	
+	#} END properties
+	
+	
+class PackFile(LazyMixin):
+	"""A pack is a file written according to the Version 2 for git packs
+	
+	As we currently use memory maps, it could be assumed that the maximum size of
+	packs therefor is 32 bit on 32 bit systems. On 64 bit systems, this should be 
+	fine though.
+	
+	:note: at some point, this might be implemented using streams as well, or 
+		streams are an alternate path in the case memory maps cannot be created
+		for some reason - one clearly doesn't want to read 10GB at once in that 
+		case"""
+	
+	__slots__ = ('_packpath', '_data', '_size', '_version')
+	pack_signature = 0x5041434b		# 'PACK'
+	pack_version_default = 2
+	
+	# offset into our data at which the first object starts
+	first_object_offset = 3*4		# header bytes
+	footer_size = 20				# final sha
+	
+	def __init__(self, packpath):
+		self._packpath = packpath
+		
+	def _set_cache_(self, attr):
+		if attr == '_data':
+			self._data = file_contents_ro_filepath(self._packpath)
+			
+			# read the header information
+			type_id, self._version, self._size = unpack_from(">LLL", self._data, 0)
+			
+			# TODO: figure out whether we should better keep the lock, or maybe
+			# add a .keep file instead ?
+		else: # must be '_size' or '_version'
+			# read header info - we do that just with a file stream
+			type_id, self._version, self._size = unpack(">LLL", open(self._packpath).read(12))
+		# END handle header
+		
+		if type_id != self.pack_signature:
+			raise ParseError("Invalid pack signature: %i" % type_id)
+		#END assert type id
+		
+	def _iter_objects(self, start_offset, as_stream=True):
+		"""Handle the actual iteration of objects within this pack"""
+		data = self._data
+		content_size = len(data) - self.footer_size
+		cur_offset = start_offset or self.first_object_offset
+		
+		null = NullStream()
+		while cur_offset < content_size:
+			data_offset, ostream = pack_object_at(data, cur_offset, True)
+			# scrub the stream to the end - this decompresses the object, but yields
+			# the amount of compressed bytes we need to get to the next offset
+				
+			stream_copy(ostream.read, null.write, ostream.size, chunk_size)
+			cur_offset += (data_offset - ostream.pack_offset) + ostream.stream.compressed_bytes_read()
+			
+			
+			# if a stream is requested, reset it beforehand
+			# Otherwise return the Stream object directly, its derived from the 
+			# info object
+			if as_stream:
+				ostream.stream.seek(0)
+			yield ostream
+		# END until we have read everything
+		
+	#{ Pack Information
+	
+	def size(self):
+		""":return: The amount of objects stored in this pack""" 
+		return self._size
+		
+	def version(self):
+		""":return: the version of this pack"""
+		return self._version
+		
+	def data(self):
+		"""
+		:return: read-only data of this pack. It provides random access and usually
+			is a memory map"""
+		return self._data
+		
+	def checksum(self):
+		""":return: 20 byte sha1 hash on all object sha's contained in this file"""
+		return self._data[-20:]
+	
+	def path(self):
+		""":return: path to the packfile"""
+		return self._packpath
+	#} END pack information
+	
+	#{ Pack Specific
+	
+	def collect_streams(self, offset):
+		"""
+		:return: list of pack streams which are required to build the object
+			at the given offset. The first entry of the list is the object at offset, 
+			the last one is either a full object, or a REF_Delta stream. The latter
+			type needs its reference object to be locked up in an ODB to form a valid
+			delta chain.
+			If the object at offset is no delta, the size of the list is 1.
+		:param offset: specifies the first byte of the object within this pack"""
+		out = list()
+		while True:
+			ostream = pack_object_at(self._data, offset, True)[1]
+			out.append(ostream)
+			if ostream.type_id == OFS_DELTA:
+				offset = ostream.pack_offset - ostream.delta_info
+			else:
+				# the only thing we can lookup are OFFSET deltas. Everything
+				# else is either an object, or a ref delta, in the latter 
+				# case someone else has to find it
+				break
+			# END handle type
+		# END while chaining streams
+		return out
+
+	#} END pack specific
+	
+	#{ Read-Database like Interface
+	
+	def info(self, offset):
+		"""Retrieve information about the object at the given file-absolute offset
+		
+		:param offset: byte offset
+		:return: OPackInfo instance, the actual type differs depending on the type_id attribute"""
+		return pack_object_at(self._data, offset or self.first_object_offset, False)[1]
+		
+	def stream(self, offset):
+		"""Retrieve an object at the given file-relative offset as stream along with its information
+		
+		:param offset: byte offset
+		:return: OPackStream instance, the actual type differs depending on the type_id attribute"""
+		return pack_object_at(self._data, offset or self.first_object_offset, True)[1]
+		
+	def stream_iter(self, start_offset=0):
+		"""
+		:return: iterator yielding OPackStream compatible instances, allowing 
+			to access the data in the pack directly.
+		:param start_offset: offset to the first object to iterate. If 0, iteration 
+			starts at the very first object in the pack.
+		:note: Iterating a pack directly is costly as the datastream has to be decompressed
+			to determine the bounds between the objects"""
+		return self._iter_objects(start_offset, as_stream=True)
+		
+	#} END Read-Database like Interface
+	
+	
+class PackEntity(LazyMixin):
+	"""Combines the PackIndexFile and the PackFile into one, allowing the 
+	actual objects to be resolved and iterated"""
+	
+	__slots__ = (	'_index',			# our index file 
+					'_pack', 			# our pack file
+					'_offset_map'		# on demand dict mapping one offset to the next consecutive one
+					)
+	
+	IndexFileCls = PackIndexFile
+	PackFileCls = PackFile
+	
+	def __init__(self, pack_or_index_path):
+		"""Initialize ourselves with the path to the respective pack or index file"""
+		basename, ext = os.path.splitext(pack_or_index_path)
+		self._index = self.IndexFileCls("%s.idx" % basename)			# PackIndexFile instance
+		self._pack = self.PackFileCls("%s.pack" % basename)			# corresponding PackFile instance
+		
+	def _set_cache_(self, attr):
+		# currently this can only be _offset_map
+		# TODO: make this a simple sorted offset array which can be bisected
+		# to find the respective entry, from which we can take a +1 easily
+		# This might be slower, but should also be much lighter in memory !
+		offsets_sorted = sorted(self._index.offsets())
+		last_offset = len(self._pack.data()) - self._pack.footer_size
+		assert offsets_sorted, "Cannot handle empty indices"
+		
+		offset_map = None
+		if len(offsets_sorted) == 1:
+			offset_map = { offsets_sorted[0] : last_offset }
+		else:
+			iter_offsets = iter(offsets_sorted)
+			iter_offsets_plus_one = iter(offsets_sorted)
+			iter_offsets_plus_one.next()
+			consecutive = izip(iter_offsets, iter_offsets_plus_one)
+			
+			offset_map = dict(consecutive)
+			
+			# the last offset is not yet set
+			offset_map[offsets_sorted[-1]] = last_offset
+		# END handle offset amount
+		self._offset_map = offset_map
+	
+	def _sha_to_index(self, sha):
+		""":return: index for the given sha, or raise"""
+		index = self._index.sha_to_index(sha)
+		if index is None:
+			raise BadObject(sha)
+		return index
+	
+	def _iter_objects(self, as_stream):
+		"""Iterate over all objects in our index and yield their OInfo or OStream instences"""
+		_sha = self._index.sha
+		_object = self._object
+		for index in xrange(self._index.size()):
+			yield _object(_sha(index), as_stream, index)
+		# END for each index
+	
+	def _object(self, sha, as_stream, index=-1):
+		""":return: OInfo or OStream object providing information about the given sha
+		:param index: if not -1, its assumed to be the sha's index in the IndexFile"""
+		# its a little bit redundant here, but it needs to be efficient
+		if index < 0:
+			index = self._sha_to_index(sha)
+		if sha is None:
+			sha = self._index.sha(index)
+		# END assure sha is present ( in output )
+		offset = self._index.offset(index)
+		type_id, uncomp_size, data_rela_offset = pack_object_header_info(buffer(self._pack._data, offset))
+		if as_stream:
+			if type_id not in delta_types:
+				packstream = self._pack.stream(offset)
+				return OStream(sha, packstream.type, packstream.size, packstream.stream)
+			# END handle non-deltas
+			
+			# produce a delta stream containing all info
+			# To prevent it from applying the deltas when querying the size, 
+			# we extract it from the delta stream ourselves
+			streams = self.collect_streams_at_offset(offset)
+			dstream = DeltaApplyReader.new(streams)
+			
+			return ODeltaStream(sha, dstream.type, None, dstream) 
+		else:
+			if type_id not in delta_types:
+				return OInfo(sha, type_id_to_type_map[type_id], uncomp_size)
+			# END handle non-deltas
+			
+			# deltas are a little tougher - unpack the first bytes to obtain
+			# the actual target size, as opposed to the size of the delta data
+			streams = self.collect_streams_at_offset(offset)
+			buf = streams[0].read(512)
+			offset, src_size = msb_size(buf)
+			offset, target_size = msb_size(buf, offset)
+			
+			# collect the streams to obtain the actual object type
+			if streams[-1].type_id in delta_types:
+				raise BadObject(sha, "Could not resolve delta object")
+			return OInfo(sha, streams[-1].type, target_size) 
+		# END handle stream
+	
+	#{ Read-Database like Interface
+	
+	def info(self, sha):
+		"""Retrieve information about the object identified by the given sha
+		
+		:param sha: 20 byte sha1
+		:raise BadObject:
+		:return: OInfo instance, with 20 byte sha"""
+		return self._object(sha, False)
+		
+	def stream(self, sha):
+		"""Retrieve an object stream along with its information as identified by the given sha
+		
+		:param sha: 20 byte sha1
+		:raise BadObject: 
+		:return: OStream instance, with 20 byte sha"""
+		return self._object(sha, True)
+
+	def info_at_index(self, index):
+		"""As ``info``, but uses a PackIndexFile compatible index to refer to the object"""
+		return self._object(None, False, index)
+	
+	def stream_at_index(self, index):
+		"""As ``stream``, but uses a PackIndexFile compatible index to refer to the 
+		object"""
+		return self._object(None, True, index)
+		
+	#} END Read-Database like Interface
+	
+	#{ Interface 
+
+	def pack(self):
+		""":return: the underlying pack file instance"""
+		return self._pack
+		
+	def index(self):
+		""":return: the underlying pack index file instance"""
+		return self._index
+		
+	def is_valid_stream(self, sha, use_crc=False):
+		"""
+		Verify that the stream at the given sha is valid.
+		
+		:param use_crc: if True, the index' crc is run over the compressed stream of 
+			the object, which is much faster than checking the sha1. It is also
+			more prone to unnoticed corruption or manipulation.
+		:param sha: 20 byte sha1 of the object whose stream to verify
+			whether the compressed stream of the object is valid. If it is 
+			a delta, this only verifies that the delta's data is valid, not the 
+			data of the actual undeltified object, as it depends on more than 
+			just this stream.
+			If False, the object will be decompressed and the sha generated. It must
+			match the given sha
+			
+		:return: True if the stream is valid
+		:raise UnsupportedOperation: If the index is version 1 only
+		:raise BadObject: sha was not found"""
+		if use_crc:
+			if self._index.version() < 2:
+				raise UnsupportedOperation("Version 1 indices do not contain crc's, verify by sha instead")
+			# END handle index version
+			
+			index = self._sha_to_index(sha)
+			offset = self._index.offset(index)
+			next_offset = self._offset_map[offset]
+			crc_value = self._index.crc(index)
+			
+			# create the current crc value, on the compressed object data
+			# Read it in chunks, without copying the data
+			crc_update = zlib.crc32
+			pack_data = self._pack.data()
+			cur_pos = offset
+			this_crc_value = 0
+			while cur_pos < next_offset:
+				rbound = min(cur_pos + chunk_size, next_offset)
+				size = rbound - cur_pos
+				this_crc_value = crc_update(buffer(pack_data, cur_pos, size), this_crc_value)
+				cur_pos += size
+			# END window size loop
+			
+			# crc returns signed 32 bit numbers, the AND op forces it into unsigned
+			# mode ... wow, sneaky, from dulwich.
+			return (this_crc_value & 0xffffffff) == crc_value
+		else:
+			shawriter = Sha1Writer()
+			stream = self._object(sha, as_stream=True)
+			# write a loose object, which is the basis for the sha
+			write_object(stream.type, stream.size, stream.read, shawriter.write)
+			
+			assert shawriter.sha(as_hex=False) == sha
+			return shawriter.sha(as_hex=False) == sha
+		# END handle crc/sha verification
+		return True
+
+	def info_iter(self):
+		"""
+		:return: Iterator over all objects in this pack. The iterator yields
+			OInfo instances"""
+		return self._iter_objects(as_stream=False)
+		
+	def stream_iter(self):
+		"""
+		:return: iterator over all objects in this pack. The iterator yields
+			OStream instances"""
+		return self._iter_objects(as_stream=True)
+		
+	def collect_streams_at_offset(self, offset):
+		"""
+		As the version in the PackFile, but can resolve REF deltas within this pack
+		For more info, see ``collect_streams``
+		
+		:param offset: offset into the pack file at which the object can be found"""
+		streams = self._pack.collect_streams(offset)
+		
+		# try to resolve the last one if needed. It is assumed to be either
+		# a REF delta, or a base object, as OFFSET deltas are resolved by the pack
+		if streams[-1].type_id == REF_DELTA:
+			stream = streams[-1]
+			while stream.type_id in delta_types:
+				if stream.type_id == REF_DELTA:
+					sindex = self._index.sha_to_index(stream.delta_info)
+					if sindex is None:
+						break
+					stream = self._pack.stream(self._index.offset(sindex))
+					streams.append(stream)
+				else:
+					# must be another OFS DELTA - this could happen if a REF 
+					# delta we resolve previously points to an OFS delta. Who 
+					# would do that ;) ? We can handle it though
+					stream = self._pack.stream(stream.delta_info)
+					streams.append(stream)
+				# END handle ref delta
+			# END resolve ref streams
+		# END resolve streams
+		
+		return streams
+		
+	def collect_streams(self, sha):
+		"""
+		As ``PackFile.collect_streams``, but takes a sha instead of an offset.
+		Additionally, ref_delta streams will be resolved within this pack.
+		If this is not possible, the stream will be left alone, hence it is adivsed
+		to check for unresolved ref-deltas and resolve them before attempting to 
+		construct a delta stream.
+		
+		:param sha: 20 byte sha1 specifying the object whose related streams you want to collect
+		:return: list of streams, first being the actual object delta, the last being 
+			a possibly unresolved base object.
+		:raise BadObject:"""
+		return self.collect_streams_at_offset(self._index.offset(self._sha_to_index(sha)))
+		
+		
+	@classmethod
+	def write_pack(cls, object_iter, pack_write, index_write=None, 
+					object_count = None, zlib_compression = zlib.Z_BEST_SPEED):
+		"""
+		Create a new pack by putting all objects obtained by the object_iterator
+		into a pack which is written using the pack_write method.
+		The respective index is produced as well if index_write is not Non.
+		
+		:param object_iter: iterator yielding odb output objects
+		:param pack_write: function to receive strings to write into the pack stream
+		:param indx_write: if not None, the function writes the index file corresponding
+			to the pack.
+		:param object_count: if you can provide the amount of objects in your iteration, 
+			this would be the place to put it. Otherwise we have to pre-iterate and store 
+			all items into a list to get the number, which uses more memory than necessary.
+		:param zlib_compression: the zlib compression level to use
+		:return: tuple(pack_sha, index_binsha) binary sha over all the contents of the pack
+			and over all contents of the index. If index_write was None, index_binsha will be None
+		:note: The destination of the write functions is up to the user. It could
+			be a socket, or a file for instance
+		:note: writes only undeltified objects"""
+		objs = object_iter
+		if not object_count:
+			if not isinstance(object_iter, (tuple, list)):
+				objs = list(object_iter)
+			#END handle list type
+			object_count = len(objs)
+		#END handle object
+		
+		pack_writer = FlexibleSha1Writer(pack_write)
+		pwrite = pack_writer.write
+		ofs = 0											# current offset into the pack file
+		index = None
+		wants_index = index_write is not None
+		
+		# write header
+		pwrite(pack('>LLL', PackFile.pack_signature, PackFile.pack_version_default, object_count))
+		ofs += 12
+		
+		if wants_index:
+			index = IndexWriter()
+		#END handle index header
+		
+		actual_count = 0
+		for obj in objs:
+			actual_count += 1
+			crc = 0
+			
+			# object header
+			hdr = create_pack_object_header(obj.type_id, obj.size)
+			if index_write:
+				crc = crc32(hdr)
+			else:
+				crc = None
+			#END handle crc
+			pwrite(hdr)
+			
+			# data stream
+			zstream = zlib.compressobj(zlib_compression)
+			ostream = obj.stream
+			br, bw, crc = write_stream_to_pack(ostream.read, pwrite, zstream, base_crc = crc)
+			assert(br == obj.size)
+			if wants_index:
+				index.append(obj.binsha, crc, ofs)
+			#END handle index
+			
+			ofs += len(hdr) + bw
+			if actual_count == object_count:
+				break
+			#END abort once we are done
+		#END for each object
+		
+		if actual_count != object_count:
+			raise ValueError("Expected to write %i objects into pack, but received only %i from iterators" % (object_count, actual_count))
+		#END count assertion
+		
+		# write footer
+		pack_sha = pack_writer.sha(as_hex = False)
+		assert len(pack_sha) == 20
+		pack_write(pack_sha)
+		ofs += len(pack_sha)							# just for completeness ;)
+		
+		index_sha = None
+		if wants_index:
+			index_sha = index.write(pack_sha, index_write)
+		#END handle index
+		
+		return pack_sha, index_sha
+	
+	@classmethod
+	def create(cls, object_iter, base_dir, object_count = None, zlib_compression = zlib.Z_BEST_SPEED):
+		"""Create a new on-disk entity comprised of a properly named pack file and a properly named
+		and corresponding index file. The pack contains all OStream objects contained in object iter.
+		:param base_dir: directory which is to contain the files
+		:return: PackEntity instance initialized with the new pack
+		:note: for more information on the other parameters see the write_pack method"""
+		pack_fd, pack_path = tempfile.mkstemp('', 'pack', base_dir)
+		index_fd, index_path = tempfile.mkstemp('', 'index', base_dir)
+		pack_write = lambda d: os.write(pack_fd, d)
+		index_write = lambda d: os.write(index_fd, d)
+		
+		pack_binsha, index_binsha = cls.write_pack(object_iter, pack_write, index_write, object_count, zlib_compression)
+		os.close(pack_fd)
+		os.close(index_fd)
+		
+		fmt = "pack-%s.%s"
+		new_pack_path = os.path.join(base_dir, fmt % (bin_to_hex(pack_binsha), 'pack'))
+		new_index_path = os.path.join(base_dir, fmt % (bin_to_hex(pack_binsha), 'idx'))
+		os.rename(pack_path, new_pack_path)
+		os.rename(index_path, new_index_path)
+		
+		return cls(new_pack_path)
+		
+		
+	#} END interface
diff --git a/git/refs/__init__.py b/git/refs/__init__.py
index 2130a087..35b69fca 100644
--- a/git/refs/__init__.py
+++ b/git/refs/__init__.py
@@ -2,14 +2,15 @@
 # import all modules in order, fix the names they require
 from symbolic import *
 from reference import *
+from headref import *
 from head import *
 from tag import *
 from remote import *
 
 # name fixes
-import head
-head.Head.RemoteReferenceCls = RemoteReference
-del(head)
+import headref
+headref.Head.RemoteReferenceCls = RemoteReference
+del(headref)
 
 
 import symbolic
diff --git a/git/refs/head.py b/git/refs/head.py
index 8ebb409c..702ce468 100644
--- a/git/refs/head.py
+++ b/git/refs/head.py
@@ -1,14 +1,28 @@
 
-from gitdb.ref.head import HEAD as GitDB_HEAD
-from gitdb.ref.headref import Head as GitDB_Head
+from symbolic import SymbolicReference
 from git.exc import GitCommandError
 
 __all__ = ["HEAD", "Head"]
 
 	
-class HEAD(GitDB_HEAD):
+class HEAD(SymbolicReference):
 	"""Provides additional functionality using the git command"""
 	__slots__ = tuple()
+	
+	_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)
 		
 	def reset(self, commit='HEAD', index=True, working_tree = False, 
 				paths=None, **kwargs):
@@ -71,95 +85,3 @@ class HEAD(GitDB_HEAD):
 		
 		return self
 	
-
-class Head(GitDB_Head):
-	"""The GitPyhton Head implementation provides more git-command based features
-	
-	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.hexsha
-		'1c09f116cbc2cb4100fb6935bb162daa4723f455'"""
-	__slots__ = tuple()
-	
-	_common_path_default = "refs/heads"
-	k_config_remote = "remote"
-	k_config_remote_ref = "merge"			# branch to merge from remote
-	
-	@classmethod
-	def delete(cls, repo, *heads, **kwargs):
-		"""Delete the given heads
-		:param force:
-			If True, the heads will be deleted even if they are not yet merged into
-			the main development stream.
-			Default False"""
-		force = kwargs.get("force", False)
-		flag = "-d"
-		if force:
-			flag = "-D"
-		repo.git.branch(flag, *heads)
-		
-		
-	def rename(self, new_path, force=False):
-		"""Rename self to a new path
-		
-		:param new_path:
-			Either a simple name or a path, i.e. new_name or features/new_name.
-			The prefix refs/heads is implied
-			
-		:param force:
-			If True, the rename will succeed even if a head with the target name
-			already exists.
-			
-		:return: self
-		:note: respects the ref log as git commands are used"""
-		flag = "-m"
-		if force:
-			flag = "-M"
-			
-		self.repo.git.branch(flag, self, new_path)
-		self.path  = "%s/%s" % (self._common_path_default, new_path)
-		return self
-		
-	def checkout(self, force=False, **kwargs):
-		"""Checkout this head by setting the HEAD to this reference, by updating the index
-		to reflect the tree we point to and by updating the working tree to reflect 
-		the latest index.
-		
-		The command will fail if changed working tree files would be overwritten.
-		
-		:param force:
-			If True, changes to the index and the working tree will be discarded.
-			If False, GitCommandError will be raised in that situation.
-			
-		:param kwargs:
-			Additional keyword arguments to be passed to git checkout, i.e.
-			b='new_branch' to create a new branch at the given spot.
-		
-		:return:
-			The active branch after the checkout operation, usually self unless
-			a new branch has been created.
-		
-		:note:
-			By default it is only allowed to checkout heads - everything else
-			will leave the HEAD detached which is allowed and possible, but remains
-			a special state that some tools might not be able to handle."""
-		args = list()
-		kwargs['f'] = force
-		if kwargs['f'] == False:
-			kwargs.pop('f')
-		
-		self.repo.git.checkout(self, **kwargs)
-		return self.repo.active_branch
-
diff --git a/git/refs/headref.py b/git/refs/headref.py
new file mode 100644
index 00000000..6fb7fea1
--- /dev/null
+++ b/git/refs/headref.py
@@ -0,0 +1,170 @@
+from reference import Reference
+from gitdb.config import SectionConstraint
+from gitdb.util import join_path
+
+__all__ = ["Head"]
+
+class Head(Reference):
+	"""The GitPyhton Head implementation provides more git-command based features
+	
+	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.hexsha
+		'1c09f116cbc2cb4100fb6935bb162daa4723f455'"""
+	__slots__ = tuple()
+	
+	_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
+	
+	@classmethod
+	def delete(cls, repo, *heads, **kwargs):
+		"""Delete the given heads
+		:param force:
+			If True, the heads will be deleted even if they are not yet merged into
+			the main development stream.
+			Default False"""
+		force = kwargs.get("force", False)
+		flag = "-d"
+		if force:
+			flag = "-D"
+		repo.git.branch(flag, *heads)
+		
+		
+	def rename(self, new_path, force=False):
+		"""Rename self to a new path
+		
+		:param new_path:
+			Either a simple name or a path, i.e. new_name or features/new_name.
+			The prefix refs/heads is implied
+			
+		:param force:
+			If True, the rename will succeed even if a head with the target name
+			already exists.
+			
+		:return: self
+		:note: respects the ref log as git commands are used"""
+		flag = "-m"
+		if force:
+			flag = "-M"
+			
+		self.repo.git.branch(flag, self, new_path)
+		self.path  = "%s/%s" % (self._common_path_default, new_path)
+		return self
+		
+	def checkout(self, force=False, **kwargs):
+		"""Checkout this head by setting the HEAD to this reference, by updating the index
+		to reflect the tree we point to and by updating the working tree to reflect 
+		the latest index.
+		
+		The command will fail if changed working tree files would be overwritten.
+		
+		:param force:
+			If True, changes to the index and the working tree will be discarded.
+			If False, GitCommandError will be raised in that situation.
+			
+		:param kwargs:
+			Additional keyword arguments to be passed to git checkout, i.e.
+			b='new_branch' to create a new branch at the given spot.
+		
+		:return:
+			The active branch after the checkout operation, usually self unless
+			a new branch has been created.
+		
+		:note:
+			By default it is only allowed to checkout heads - everything else
+			will leave the HEAD detached which is allowed and possible, but remains
+			a special state that some tools might not be able to handle."""
+		args = list()
+		kwargs['f'] = force
+		if kwargs['f'] == False:
+			kwargs.pop('f')
+		
+		self.repo.git.checkout(self, **kwargs)
+		return self.repo.active_branch
+
+		
+
diff --git a/git/refs/log.py b/git/refs/log.py
index c67c0714..3aa0b4a3 100644
--- a/git/refs/log.py
+++ b/git/refs/log.py
@@ -1,6 +1,279 @@
-from gitdb.ref.log import (
-							RefLog,
-							RefLogEntry
-						)
+from gitdb.util import (
+						join_path,
+						Actor,
+						LockedFD,
+						LockFile,
+						assure_directory_exists,
+						to_native_path,
+						bin_to_hex,
+						join,
+						file_contents_ro_filepath
+					)
+
+from gitdb.object.util import (
+								parse_date,
+								Serializable, 
+								utctz_to_altz,
+								altz_to_utctz_str,
+							)
+
+import time
+import os
+import re
+
 __all__ = ["RefLog", "RefLogEntry"]
 
+
+class RefLogEntry(tuple):
+	"""Named tuple allowing easy access to the revlog data fields"""
+	_fmt = "%s %s %s <%s> %i %s\t%s\n"
+	_re_hexsha_only = re.compile('^[0-9A-Fa-f]{40}$')
+	__slots__ = tuple()
+	
+	def __repr__(self):
+		"""Representation of ourselves in git reflog format"""
+		act = self.actor
+		time = self.time
+		return self._fmt % (self.oldhexsha, self.newhexsha, act.name, act.email, 
+							time[0], altz_to_utctz_str(time[1]), self.message)
+	
+	@property
+	def oldhexsha(self):
+		"""The hexsha to the commit the ref pointed to before the change""" 
+		return self[0]
+		
+	@property
+	def newhexsha(self):
+		"""The hexsha to the commit the ref now points to, after the change"""
+		return self[1]
+		
+	@property
+	def actor(self):
+		"""Actor instance, providing access"""
+		return self[2]
+		
+	@property
+	def time(self):
+		"""time as tuple:
+		
+		* [0] = int(time)
+		* [1] = int(timezone_offset) in time.altzone format """
+		return self[3]
+		
+	@property
+	def message(self):
+		"""Message describing the operation that acted on the reference"""
+		return self[4]
+	
+	@classmethod
+	def new(self, oldhexsha, newhexsha, actor, time, tz_offset, message):
+		""":return: New instance of a RefLogEntry"""
+		if not isinstance(actor, Actor):
+			raise ValueError("Need actor instance, got %s" % actor)
+		# END check types 
+		return RefLogEntry((oldhexsha, newhexsha, actor, (time, tz_offset), message))
+		
+	@classmethod
+	def from_line(cls, line):
+		""":return: New RefLogEntry instance from the given revlog line.
+		:param line: line without trailing newline
+		:raise ValueError: If line could not be parsed"""
+		try:
+			info, msg = line.split('\t', 2)
+		except ValueError:
+			raise ValueError("line is missing tab separator")
+		#END handle first plit
+		oldhexsha = info[:40]
+		newhexsha = info[41:81]
+		for hexsha in (oldhexsha, newhexsha):
+			if not cls._re_hexsha_only.match(hexsha):
+				raise ValueError("Invalid hexsha: %s" % hexsha)
+			# END if hexsha re doesn't match
+		#END for each hexsha
+		
+		email_end = info.find('>', 82)
+		if email_end == -1:
+			raise ValueError("Missing token: >")
+		#END handle missing end brace
+		
+		actor = Actor._from_string(info[82:email_end+1])
+		time, tz_offset = parse_date(info[email_end+2:])
+		
+		return RefLogEntry((oldhexsha, newhexsha, actor, (time, tz_offset), msg))
+		
+
+class RefLog(list, Serializable):
+	"""A reflog contains reflog entries, each of which defines a certain state
+	of the head in question. Custom query methods allow to retrieve log entries 
+	by date or by other criteria.
+	
+	Reflog entries are orded, the first added entry is first in the list, the last
+	entry, i.e. the last change of the head or reference, is last in the list."""
+	
+	__slots__ = ('_path', )
+	
+	def __new__(cls, filepath=None):
+		inst = super(RefLog, cls).__new__(cls)
+		return inst
+		
+	def __init__(self, filepath=None):
+		"""Initialize this instance with an optional filepath, from which we will
+		initialize our data. The path is also used to write changes back using 
+		the write() method"""
+		self._path = filepath
+		if filepath is not None:
+			self._read_from_file()
+		# END handle filepath
+	
+	def _read_from_file(self):
+		fmap = file_contents_ro_filepath(self._path, stream=False, allow_mmap=True)
+		try:
+			self._deserialize(fmap)
+		finally:
+			fmap.close()
+		#END handle closing of handle
+	
+	#{ Interface
+	
+	@classmethod
+	def from_file(cls, filepath):
+		"""
+		:return: a new RefLog instance containing all entries from the reflog 
+			at the given filepath
+		:param filepath: path to reflog 
+		:raise ValueError: If the file could not be read or was corrupted in some way"""
+		return cls(filepath)
+	
+	@classmethod
+	def path(cls, ref):
+		"""
+		:return: string to absolute path at which the reflog of the given ref 
+			instance would be found. The path is not guaranteed to point to a valid 
+			file though.
+		:param ref: SymbolicReference instance"""
+		return join(ref.repo.git_path(), "logs", to_native_path(ref.path))
+		
+	@classmethod
+	def iter_entries(cls, stream):
+		"""
+		:return: Iterator yielding RefLogEntry instances, one for each line read 
+			sfrom the given stream.
+		:param stream: file-like object containing the revlog in its native format
+			or basestring instance pointing to a file to read"""
+		new_entry = RefLogEntry.from_line
+		if isinstance(stream, basestring):
+			stream = file_contents_ro_filepath(stream)
+		#END handle stream type
+		while True:
+			line = stream.readline()
+			if not line:
+				return
+			yield new_entry(line.strip())
+		#END endless loop
+		
+	@classmethod
+	def entry_at(cls, filepath, index):
+		""":return: RefLogEntry at the given index
+		:param filepath: full path to the index file from which to read the entry
+		:param index: python list compatible index, i.e. it may be negative to 
+			specifiy an entry counted from the end of the list
+			
+		:raise IndexError: If the entry didn't exist
+		
+		.. note:: This method is faster as it only parses the entry at index, skipping
+			all other lines. Nonetheless, the whole file has to be read if 
+			the index is negative
+		"""
+		fp = open(filepath, 'rb')
+		if index < 0:
+			return RefLogEntry.from_line(fp.readlines()[index].strip())
+		else:
+			# read until index is reached
+			for i in xrange(index+1):
+				line = fp.readline()
+				if not line:
+					break
+				#END abort on eof
+			#END handle runup
+			
+			if i != index or not line:
+				raise IndexError
+			#END handle exception
+			
+			return RefLogEntry.from_line(line.strip())
+		#END handle index
+	
+	def to_file(self, filepath):
+		"""Write the contents of the reflog instance to a file at the given filepath.
+		:param filepath: path to file, parent directories are assumed to exist"""
+		lfd = LockedFD(filepath)
+		assure_directory_exists(filepath, is_file=True)
+		
+		fp = lfd.open(write=True, stream=True)
+		try:
+			self._serialize(fp)
+			lfd.commit()
+		except:
+			# on failure it rolls back automatically, but we make it clear
+			lfd.rollback()
+			raise
+		#END handle change
+		
+	@classmethod
+	def append_entry(cls, config_reader, filepath, oldbinsha, newbinsha, message):
+		"""Append a new log entry to the revlog at filepath.
+		
+		:param config_reader: configuration reader of the repository - used to obtain
+			user information. May be None
+		:param filepath: full path to the log file
+		:param oldbinsha: binary sha of the previous commit
+		:param newbinsha: binary sha of the current commit
+		:param message: message describing the change to the reference
+		:param write: If True, the changes will be written right away. Otherwise
+			the change will not be written
+		:return: RefLogEntry objects which was appended to the log
+		:note: As we are append-only, concurrent access is not a problem as we 
+			do not interfere with readers."""
+		if len(oldbinsha) != 20 or len(newbinsha) != 20:
+			raise ValueError("Shas need to be given in binary format")
+		#END handle sha type
+		assure_directory_exists(filepath, is_file=True)
+		entry = RefLogEntry((bin_to_hex(oldbinsha), bin_to_hex(newbinsha), Actor.committer(config_reader), (int(time.time()), time.altzone), message))
+		
+		lf = LockFile(filepath)
+		lf._obtain_lock_or_raise()
+		
+		fd = open(filepath, 'a')
+		try:
+			fd.write(repr(entry))
+		finally:
+			fd.close()
+			lf._release_lock()
+		#END handle write operation
+		
+		return entry
+		
+	def write(self):
+		"""Write this instance's data to the file we are originating from
+		:return: self"""
+		if self._path is None:
+			raise ValueError("Instance was not initialized with a path, use to_file(...) instead")
+		#END assert path
+		self.to_file(self._path)
+		return self
+	
+	#} END interface
+	
+	#{ Serializable Interface
+	def _serialize(self, stream):
+		lm1 = len(self) - 1
+		write = stream.write
+		
+		# write all entries
+		for e in self:
+			write(repr(e))
+		#END for each entry
+	
+	def _deserialize(self, stream):
+		self.extend(self.iter_entries(stream))
+	#} END serializable interface
diff --git a/git/refs/reference.py b/git/refs/reference.py
index cead66ce..6373cb3e 100644
--- a/git/refs/reference.py
+++ b/git/refs/reference.py
@@ -1,7 +1,82 @@
+import os
+
+from symbolic import SymbolicReference
+from head import HEAD
+from gitdb.util import (
+							LazyMixin, 
+							Iterable,
+							isfile,
+							hex_to_bin
+						)
 
-from gitdb.ref.reference import Reference as GitDB_Reference
 __all__ = ["Reference"]
 
-class Reference(GitDB_Reference):
+
+class Reference(SymbolicReference, LazyMixin, Iterable):
+	"""Represents a named reference to any object. Subclasses may apply restrictions though, 
+	i.e. Heads can only point to commits."""
 	__slots__ = tuple()
-	pass
+	_points_to_commits_only = False
+	_resolve_ref_on_create = True
+	_common_path_default = "refs"
+	
+	def __init__(self, repo, path):
+		"""Initialize this instance
+		:param repo: Our parent repository
+		
+		:param path:
+			Path relative to the .git/ directory pointing to the ref in question, i.e.
+			refs/heads/master"""
+		if not path.startswith(self._common_path_default+'/'):
+			raise ValueError("Cannot instantiate %r from path %s" % ( self.__class__.__name__, path ))
+		super(Reference, self).__init__(repo, path)
+		
+
+	def __str__(self):
+		return self.name
+
+	def set_object(self, object, logmsg = None):
+		"""Special version which checks if the head-log needs an update as well"""
+		oldbinsha = None
+		head = HEAD(self.repo)
+		if logmsg is not None:
+			if not head.is_detached and head.ref == self:
+				oldbinsha = self.commit.binsha
+			#END handle commit retrieval
+		#END handle message is set
+		
+		super(Reference, self).set_object(object, logmsg)
+		
+		if oldbinsha is not None:
+			# /* from refs.c in git-source
+			# * Special hack: If a branch is updated directly and HEAD
+			# * points to it (may happen on the remote side of a push
+			# * for example) then logically the HEAD reflog should be
+			# * updated too.
+			# * A generic solution implies reverse symref information,
+			# * but finding all symrefs pointing to the given branch
+			# * would be rather costly for this rare event (the direct
+			# * update of a branch) to be worth it.  So let's cheat and
+			# * check with HEAD only which should cover 99% of all usage
+			# * scenarios (even 100% of the default ones).
+			# */
+			head.log_append(oldbinsha, logmsg)
+		#END check if the head
+
+	# NOTE: Don't have to overwrite properties as the will only work without a the log
+
+	@property
+	def name(self):
+		""":return: (shortest) Name of this reference - it may contain path components"""
+		# first two path tokens are can be removed as they are 
+		# refs/heads or refs/tags or refs/remotes
+		tokens = self.path.split('/')
+		if len(tokens) < 3:
+			return self.path		   # could be refs/HEAD
+		return '/'.join(tokens[2:])
+	
+	@classmethod
+	def iter_items(cls, repo, common_path = None):
+		"""Equivalent to SymbolicReference.iter_items, but will return non-detached
+		references as well."""
+		return cls._iter_items(repo, common_path)
diff --git a/git/refs/remote.py b/git/refs/remote.py
index 04d0d5dd..bfe80e62 100644
--- a/git/refs/remote.py
+++ b/git/refs/remote.py
@@ -1,5 +1,9 @@
 import os
-from gitdb.ref.remote import RemoteReference as GitDB_RemoteReference
+from headref import Head
+from gitdb.util import (
+						join, 
+						join_path
+						)
 
 __all__ = ["RemoteReference"]
 
@@ -8,6 +12,41 @@ class RemoteReference(GitDB_RemoteReference):
 	"""Represents a reference pointing to a remote head."""
 	__slots__ = tuple()
 	
+	_common_path_default = "refs/remotes"
+	
+	
+	@classmethod
+	def iter_items(cls, repo, common_path = None, remote=None):
+		"""Iterate remote references, and if given, constrain them to the given remote"""
+		common_path = common_path or cls._common_path_default
+		if remote is not None:
+			common_path = join_path(common_path, str(remote))
+		# END handle remote constraint
+		return super(RemoteReference, cls).iter_items(repo, common_path)
+	
+	@property
+	def remote_name(self):
+		"""
+		:return:
+			Name of the remote we are a reference of, such as 'origin' for a reference
+			named 'origin/master'"""
+		tokens = self.path.split('/')
+		# /refs/remotes/<remote name>/<branch_name>
+		return tokens[2]
+		
+	@property
+	def remote_head(self):
+		""":return: Name of the remote head itself, i.e. master.
+		:note: The returned name is usually not qualified enough to uniquely identify
+			a branch"""
+		tokens = self.path.split('/')
+		return '/'.join(tokens[3:])
+		
+	@classmethod
+	def create(cls, *args, **kwargs):
+		"""Used to disable this method"""
+		raise TypeError("Cannot explicitly create remote references")
+	
 	@classmethod
 	def delete(cls, repo, *refs, **kwargs):
 		"""Delete the given remote references.
diff --git a/git/refs/symbolic.py b/git/refs/symbolic.py
index 90bfaec2..70cfc7d6 100644
--- a/git/refs/symbolic.py
+++ b/git/refs/symbolic.py
@@ -1,6 +1,653 @@
-from gitdb.ref.symbolic import SymbolicReference as GitDB_SymbolicReference
+import os
+import re
+
+from gitdb.object import (
+						Object, 
+						Commit
+						)
+from gitdb.util import (
+					join_path, 
+					join_path_native, 
+					to_native_path_linux,
+					assure_directory_exists,
+					join, 
+					dirname,
+					isdir,
+					exists,
+					isfile,
+					rename,
+					hex_to_bin,
+					LockedFD
+					)
+
+from gitdb.exc import BadObject
+from log import RefLog
+
 __all__ = ["SymbolicReference"]
 
-class SymbolicReference(GitDB_SymbolicReference):
-	__slots__ = tuple()
-	pass
+class SymbolicReference(object):
+	"""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."""
+	__slots__ = ("repo", "path")
+	
+	_resolve_ref_on_create = False
+	_points_to_commits_only = True
+	_common_path_default = ""
+	_id_attribute_ = "name"
+	
+	re_hexsha_only = re.compile('^[0-9A-Fa-f]{40}$')
+	
+	#{ Configuration
+	# Object class to be used when instantiating objects
+	ObjectCls = Object
+	CommitCls = Commit
+	
+	# all of the following are set by the package initializer
+	HEADCls = None
+	HeadCls = None
+	RemoteReferenceCls = None
+	TagReferenceCls = None
+	ReferenceCls = None
+	#}END configuration
+	
+	def __init__(self, repo, path):
+		self.repo = repo
+		self.path = path
+		
+	def __str__(self):
+		return self.path
+		
+	def __repr__(self):
+		return '<git.%s "%s">' % (self.__class__.__name__, self.path)
+		
+	def __eq__(self, other):
+		return self.path == other.path
+		
+	def __ne__(self, other):
+		return not ( self == other )
+		
+	def __hash__(self):
+		return hash(self.path)
+		
+	@property
+	def name(self):
+		"""
+		:return:
+			In case of symbolic references, the shortest assumable name 
+			is the path itself."""
+		return self.path
+	
+	@property
+	def abspath(self):
+		return join_path_native(self.repo.git_path(), self.path)
+		
+	@classmethod
+	def _get_packed_refs_path(cls, repo):
+		return join(repo.git_path(), 'packed-refs')
+		
+	@classmethod
+	def _iter_packed_refs(cls, repo):
+		"""Returns an iterator yielding pairs of sha1/path pairs for the corresponding refs.
+		:note: The packed refs file will be kept open as long as we iterate"""
+		try:
+			fp = open(cls._get_packed_refs_path(repo), 'r')
+			for line in fp:
+				line = line.strip()
+				if not line:
+					continue
+				if line.startswith('#'):
+					if line.startswith('# pack-refs with:') and not line.endswith('peeled'):
+						raise TypeError("PackingType of packed-Refs not understood: %r" % line)
+					# END abort if we do not understand the packing scheme
+					continue
+				# END parse comment
+				
+				# skip dereferenced tag object entries - previous line was actual
+				# tag reference for it
+				if line[0] == '^':
+					continue
+				
+				yield tuple(line.split(' ', 1))
+			# END for each line
+		except (OSError,IOError):
+			raise StopIteration
+		# END no packed-refs file handling 
+		# NOTE: Had try-finally block around here to close the fp, 
+		# but some python version woudn't allow yields within that.
+		# I believe files are closing themselves on destruction, so it is 
+		# alright.
+		
+	@classmethod
+	def dereference_recursive(cls, repo, ref_path):
+		"""
+		:return: hexsha stored in the reference at the given ref_path, recursively dereferencing all
+			intermediate references as required
+		:param repo: the repository containing the reference at ref_path"""
+		while True:
+			hexsha, ref_path = cls._get_ref_info(repo, ref_path)
+			if hexsha is not None:
+				return hexsha
+		# END recursive dereferencing
+		
+	@classmethod
+	def _get_ref_info(cls, repo, ref_path):
+		"""Return: (sha, target_ref_path) if available, the sha the file at 
+		rela_path points to, or None. target_ref_path is the reference we 
+		point to, or None"""
+		tokens = None
+		try:
+			fp = open(join(repo.git_path(), ref_path), 'r')
+			value = fp.read().rstrip()
+			fp.close()
+			tokens = value.split(" ")
+		except (OSError,IOError):
+			# Probably we are just packed, find our entry in the packed refs file
+			# NOTE: We are not a symbolic ref if we are in a packed file, as these
+			# are excluded explictly
+			for sha, path in cls._iter_packed_refs(repo):
+				if path != ref_path: continue
+				tokens = (sha, path)
+				break
+			# END for each packed ref
+		# END handle packed refs
+		if tokens is None:
+			raise ValueError("Reference at %r does not exist" % ref_path)
+		
+		# is it a reference ?
+		if tokens[0] == 'ref:':
+			return (None, tokens[1])
+			
+		# its a commit
+		if cls.re_hexsha_only.match(tokens[0]):
+			return (tokens[0], None)
+			
+		raise ValueError("Failed to parse reference information from %r" % ref_path)
+	
+	def _get_object_sha(self):
+		"""
+		:return:
+			The binary sha to the object our ref currently refers to. Refs can be cached, they will 
+			always point to the actual object as it gets re-created on each query"""
+		return hex_to_bin(self.dereference_recursive(self.repo, self.path))
+	
+	def _get_object(self):
+		"""
+		:return:
+			The object our ref currently refers to."""
+		# 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 self.ObjectCls.new_from_sha(self.repo, self._get_object_sha())
+	
+	def set_object(self, object_id, logmsg = None):
+		"""Set the object we point to, possibly dereference our symbolic reference first.
+		If the reference does not exist, it will be created
+		
+		:param object: a reference specifier string, a SymbolicReference or an object hex sha. 
+			SymbolicReferences will be dereferenced beforehand to obtain the object they point to
+		:param logmsg: If not None, the message will be used in the reflog entry to be 
+			written. Otherwise the reflog is not altered
+		:note: plain SymbolicReferences may not actually point to objects by convention
+		:return: self"""
+		if isinstance(object_id, SymbolicReference):
+			object = object.object
+		#END resolve references
+		
+		is_detached = True
+		try:
+			is_detached = self.is_detached
+		except ValueError:
+			pass
+		# END handle non-existing ones
+		
+		if is_detached:
+			return self.set_reference(object_id, logmsg)
+			
+		# set the commit on our reference
+		return self._get_reference().set_object(object_id, logmsg)
+		
+	def _get_commit(self):
+		"""
+		:return:
+			Commit object we point to, works for detached and non-detached 
+			SymbolicReferences. The symbolic reference will be dereferenced recursively."""
+		obj = self._get_object()
+		if obj.type == 'tag':
+			obj = obj.object
+		#END dereference tag
+		
+		if obj.type != self.CommitCls.type:
+			raise TypeError("Symbolic Reference pointed to object %r, commit was required" % obj)
+		#END handle type
+		return obj
+		
+	def set_commit(self, commit, logmsg = None):
+		"""As set_object, but restricts the type of object to be a Commit
+		
+		:raise ValueError: If commit is not a Commit object or doesn't point to 
+			a commit
+		:return: self"""
+		# check the type - assume the best if it is a base-string
+		is_invalid_type = False
+		if isinstance(commit, self.ObjectCls):
+			is_invalid_type = commit.type != self.CommitCls.type
+		elif isinstance(commit, SymbolicReference):
+			is_invalid_type = commit.object.type != self.CommitCls.type
+		else:
+			try:
+				is_invalid_type = self.repo.resolve(commit).type != self.CommitCls.type
+			except BadObject:
+				raise ValueError("Invalid object: %s" % commit)
+			#END handle exception
+		# END verify type
+		
+		if is_invalid_type:
+			raise ValueError("Need commit, got %r" % commit)
+		#END handle raise
+		
+		# we leave strings to the rev-parse method below
+		self.set_object(commit, logmsg)
+		
+		return self
+		
+	
+	commit = property(_get_commit, set_commit, doc="Query or set commits directly")
+	object = property(_get_object, set_object, doc="Return the object our ref currently refers to")
+	object_binsha = property(_get_object_sha, set_object, doc="Return the object our ref currently refers to")
+		
+	def _get_reference(self):
+		""":return: Reference Object we point to
+		:raise TypeError: If this symbolic reference is detached, hence it doesn't point
+			to a reference, but to a commit"""
+		sha, target_ref_path = self._get_ref_info(self.repo, self.path)
+		if target_ref_path is None:
+			raise TypeError("%s is a detached symbolic reference as it points to %r" % (self, sha))
+		return self.from_path(self.repo, target_ref_path)
+		
+	def set_reference(self, ref, logmsg = None):
+		"""Set ourselves to the given ref. It will stay a symbol if the ref is a Reference.
+		Otherwise an Object, given as Object instance or refspec, is assumed and if valid, 
+		will be set which effectively detaches the refererence if it was a purely 
+		symbolic one.
+		
+		:param ref: SymbolicReference instance, hexadecimal sha string or refspec string
+			Only if the ref is a SymbolicRef instance, we will point to it. Everthiny
+			else is dereferenced to obtain the actual object.
+		:param logmsg: If set to a string, the message will be used in the reflog.
+			Otherwise, a reflog entry is not written for the changed reference.
+			The previous commit of the entry will be the commit we point to now.
+			
+			See also: log_append()
+		
+		:return: self
+		:note: This symbolic reference will not be dereferenced. For that, see 
+			``set_object(...)``"""
+		write_value = None
+		obj = None
+		if isinstance(ref, SymbolicReference):
+			write_value = "ref: %s" % ref.path
+		elif isinstance(ref, self.ObjectCls):
+			obj = ref
+			write_value = ref.hexsha
+		elif isinstance(ref, basestring):
+			try:
+				obj = self.repo.resolve(ref+"^{}")	# optionally deref tags
+				write_value = obj.hexsha
+			except BadObject:
+				raise ValueError("Could not extract object from %s" % ref)
+			# END end try string
+		else:
+			raise ValueError("Unrecognized Value: %r" % ref)
+		# END try commit attribute
+		
+		# typecheck
+		if obj is not None and self._points_to_commits_only and obj.type != Commit.type:
+			raise TypeError("Require commit, got %r" % obj)
+		#END verify type
+		
+		oldbinsha = None
+		if logmsg is not None:
+			try:
+				oldbinsha = self.commit.binsha
+			except ValueError:
+				oldbinsha = Commit.NULL_BIN_SHA
+			#END handle non-existing
+		#END retrieve old hexsha
+		
+		fpath = self.abspath
+		assure_directory_exists(fpath, is_file=True)
+		
+		lfd = LockedFD(fpath)
+		fd = lfd.open(write=True, stream=True)
+		fd.write(write_value)
+		lfd.commit()
+		
+		# Adjust the reflog
+		if logmsg is not None:
+			self.log_append(oldbinsha, logmsg)
+		#END handle reflog
+		
+		return self
+		
+
+	# aliased reference
+	reference = property(_get_reference, set_reference, doc="Returns the Reference we point to")
+	ref = reference
+	
+	def is_valid(self):
+		"""
+		:return:
+			True if the reference is valid, hence it can be read and points to 
+			a valid object or reference."""
+		try:
+			self.object
+		except (OSError, ValueError, BadObject):
+			return False
+		else:
+			return True
+		
+	@property
+	def is_detached(self):
+		"""
+		:return:
+			True if we are a detached reference, hence we point to a specific commit
+			instead to another reference"""
+		try:
+			self.ref
+			return False
+		except TypeError:
+			return True
+	
+	def log(self):
+		"""
+		:return: RefLog for this reference. Its last entry reflects the latest change
+			applied to this reference
+			
+		.. note:: As the log is parsed every time, its recommended to cache it for use
+			instead of calling this method repeatedly. It should be considered read-only."""
+		return RefLog.from_file(RefLog.path(self))
+		
+	def log_append(self, oldbinsha, message, newbinsha=None):
+		"""Append a logentry to the logfile of this ref
+		
+		:param oldbinsha: binary sha this ref used to point to
+		:param message: A message describing the change
+		:param newbinsha: The sha the ref points to now. If None, our current commit sha
+			will be used
+		:return: added RefLogEntry instance"""
+		return RefLog.append_entry(self.repo.config_reader(), RefLog.path(self), oldbinsha, 
+									(newbinsha is None and self.commit.binsha) or newbinsha, 
+									message) 
+
+	def log_entry(self, index):
+		""":return: RefLogEntry at the given index
+		:param index: python list compatible positive or negative index
+		
+		.. note:: This method must read part of the reflog during execution, hence 
+			it should be used sparringly, or only if you need just one index.
+			In that case, it will be faster than the ``log()`` method"""
+		return RefLog.entry_at(RefLog.path(self), index)
+
+	@classmethod
+	def to_full_path(cls, path):
+		"""
+		:return: string with a full repository-relative path which can be used to initialize 
+			a Reference instance, for instance by using ``Reference.from_path``"""
+		if isinstance(path, SymbolicReference):
+			path = path.path
+		full_ref_path = path
+		if not cls._common_path_default:
+			return full_ref_path
+		if not path.startswith(cls._common_path_default+"/"):
+			full_ref_path = '%s/%s' % (cls._common_path_default, path)
+		return full_ref_path
+	
+	@classmethod
+	def delete(cls, repo, path):
+		"""Delete the reference at the given path
+		
+		:param repo:
+			Repository to delete the reference from
+		
+		:param path:
+			Short or full path pointing to the reference, i.e. refs/myreference
+			or just "myreference", hence 'refs/' is implied.
+			Alternatively the symbolic reference to be deleted"""
+		full_ref_path = cls.to_full_path(path)
+		abs_path = join(repo.git_path(), full_ref_path)
+		if exists(abs_path):
+			os.remove(abs_path)
+		else:
+			# check packed refs
+			pack_file_path = cls._get_packed_refs_path(repo)
+			try:
+				reader = open(pack_file_path)
+			except (OSError,IOError):
+				pass # it didnt exist at all
+			else:
+				new_lines = list()
+				made_change = False
+				dropped_last_line = False
+				for line in reader:
+					# keep line if it is a comment or if the ref to delete is not 
+					# in the line
+					# If we deleted the last line and this one is a tag-reference object, 
+					# we drop it as well
+					if ( line.startswith('#') or full_ref_path not in line ) and \
+						( not dropped_last_line or dropped_last_line and not line.startswith('^') ):
+						new_lines.append(line)
+						dropped_last_line = False
+						continue
+					# END skip comments and lines without our path
+					
+					# drop this line
+					made_change = True
+					dropped_last_line = True
+				# END for each line in packed refs
+				reader.close()
+				
+				# write the new lines
+				if made_change:
+					open(pack_file_path, 'w').writelines(new_lines)
+			# END open exception handling
+		# END handle deletion
+		
+		# delete the reflog
+		reflog_path = RefLog.path(cls(repo, full_ref_path))
+		if os.path.isfile(reflog_path):
+			os.remove(reflog_path)
+		#END remove reflog
+		
+			
+	@classmethod
+	def _create(cls, repo, path, resolve, reference, force, logmsg=None):
+		"""internal method used to create a new symbolic reference.
+		If resolve is False, the reference will be taken as is, creating 
+		a proper symbolic reference. Otherwise it will be resolved to the 
+		corresponding object and a detached symbolic reference will be created
+		instead"""
+		full_ref_path = cls.to_full_path(path)
+		abs_ref_path = join(repo.git_path(), full_ref_path)
+		
+		# figure out target data
+		target = reference
+		if resolve:
+			# could just use the resolve method, but it could be expensive
+			# so we handle most common cases ourselves
+			if isinstance(reference, cls.ObjectCls):
+				target = reference.hexsha
+			elif isinstance(reference, SymbolicReference):
+				target = reference.object.hexsha
+			else:
+				target = repo.resolve(str(reference))
+			#END handle resoltion
+		#END need resolution
+			
+		if not force and isfile(abs_ref_path):
+			target_data = str(target)
+			if isinstance(target, SymbolicReference):
+				target_data = target.path
+			if not resolve:
+				target_data = "ref: " + target_data
+			existing_data = open(abs_ref_path, 'rb').read().strip() 
+			if existing_data != target_data:
+				raise OSError("Reference at %r does already exist, pointing to %r, requested was %r" % (full_ref_path, existing_data, target_data))
+		# END no force handling
+		
+		ref = cls(repo, full_ref_path)
+		ref.set_reference(target, logmsg)
+		return ref
+		
+	@classmethod
+	def create(cls, repo, path, reference='HEAD', force=False, logmsg=None):
+		"""Create a new symbolic reference, hence a reference pointing to another reference.
+		
+		:param repo:
+			Repository to create the reference in 
+			
+		:param path:
+			full path at which the new symbolic reference is supposed to be 
+			created at, i.e. "NEW_HEAD" or "symrefs/my_new_symref"
+			
+		:param reference:
+			The reference to which the new symbolic reference should point to.
+			If it is a commit'ish, the symbolic ref will be detached.
+		
+		:param force:
+			if True, force creation even if a symbolic reference with that name already exists.
+			Raise OSError otherwise
+			
+		:param logmsg:
+			If not None, the message to append to the reflog. Otherwise no reflog
+			entry is written.
+			
+		:return: Newly created symbolic Reference
+			
+		:raise OSError:
+			If a (Symbolic)Reference with the same name but different contents
+			already exists.
+		
+		:note: This does not alter the current HEAD, index or Working Tree"""
+		return cls._create(repo, path, cls._resolve_ref_on_create, reference, force, logmsg)
+	
+	def rename(self, new_path, force=False):
+		"""Rename self to a new path
+		
+		:param new_path:
+			Either a simple name or a full path, i.e. new_name or features/new_name.
+			The prefix refs/ is implied for references and will be set as needed.
+			In case this is a symbolic ref, there is no implied prefix
+			
+		:param force:
+			If True, the rename will succeed even if a head with the target name
+			already exists. It will be overwritten in that case
+			
+		:return: self
+		:raise OSError: In case a file at path but a different contents already exists """
+		new_path = self.to_full_path(new_path)
+		if self.path == new_path:
+			return self
+		
+		new_abs_path = join(self.repo.git_path(), new_path)
+		cur_abs_path = join(self.repo.git_path(), self.path)
+		if isfile(new_abs_path):
+			if not force:
+				# if they point to the same file, its not an error
+				if open(new_abs_path,'rb').read().strip() != open(cur_abs_path,'rb').read().strip():
+					raise OSError("File at path %r already exists" % new_abs_path)
+				# else: we could remove ourselves and use the otherone, but 
+				# but clarity we just continue as usual
+			# END not force handling
+			os.remove(new_abs_path)
+		# END handle existing target file
+		
+		dname = dirname(new_abs_path)
+		if not isdir(dname):
+			os.makedirs(dname)
+		# END create directory
+		
+		rename(cur_abs_path, new_abs_path)
+		self.path = new_path
+		
+		return self
+		
+	@classmethod
+	def _iter_items(cls, repo, common_path = None):
+		if common_path is None:
+			common_path = cls._common_path_default
+		rela_paths = set()
+		
+		# walk loose refs
+		# Currently we do not follow links 
+		for root, dirs, files in os.walk(join_path_native(repo.git_path(), common_path)):
+			if 'refs/' not in root: # skip non-refs subfolders
+				refs_id = [ i for i,d in enumerate(dirs) if d == 'refs' ]
+				if refs_id:
+					dirs[0:] = ['refs']
+			# END prune non-refs folders
+			
+			for f in files:
+				abs_path = to_native_path_linux(join_path(root, f))
+				rela_paths.add(abs_path.replace(to_native_path_linux(repo.git_path()) + '/', ""))
+			# END for each file in root directory
+		# END for each directory to walk
+		
+		# read packed refs
+		for sha, rela_path in cls._iter_packed_refs(repo):
+			if rela_path.startswith(common_path):
+				rela_paths.add(rela_path)
+			# END relative path matches common path
+		# END packed refs reading
+		
+		# return paths in sorted order
+		for path in sorted(rela_paths):
+			try:
+				yield cls.from_path(repo, path)
+			except ValueError:
+				continue
+		# END for each sorted relative refpath
+		
+	@classmethod
+	def iter_items(cls, repo, common_path = None):
+		"""Find all refs in the repository
+
+		:param repo: is the repo
+
+		:param common_path:
+			Optional keyword argument to the path which is to be shared by all
+			returned Ref objects.
+			Defaults to class specific portion if None assuring that only 
+			refs suitable for the actual class are returned.
+
+		:return:
+			git.SymbolicReference[], each of them is guaranteed to be a *only* a symbolic
+			ref, or a derived class which is not detached
+			
+			List is lexigraphically sorted
+			The returned objects represent actual subclasses, such as Head or TagReference"""
+		return ( r for r in cls._iter_items(repo, common_path) if r.__class__ == cls or not r.is_detached )
+		
+	@classmethod
+	def from_path(cls, repo, path):
+		"""
+		:param path: full .git-directory-relative path name to the Reference to instantiate
+		:note: use to_full_path() if you only have a partial path of a known Reference Type
+		:return:
+			Instance of type Reference, Head, or Tag
+			depending on the given path"""
+		if not path:
+			raise ValueError("Cannot create Reference from %r" % path)
+		
+		for ref_type in (cls.HEADCls, cls.HeadCls, cls.RemoteReferenceCls, cls.TagReferenceCls, cls.ReferenceCls, cls):
+			try:
+				instance = ref_type(repo, path)
+				if instance.__class__ == SymbolicReference and instance.is_detached:
+					raise ValueError("SymbolRef was detached, we drop it")
+				return instance
+			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)
diff --git a/git/refs/tag.py b/git/refs/tag.py
index 47c9ea4d..24a8e768 100644
--- a/git/refs/tag.py
+++ b/git/refs/tag.py
@@ -3,7 +3,45 @@ from gitdb.ref.tag import TagReference as GitDB_TagReference
 __all__ = ["TagReference", "Tag"]
 
 class TagReference(GitDB_TagReference):
+	"""Class representing a lightweight tag reference which either points to a commit 
+	,a tag object or any other object. In the latter case additional information, 
+	like the signature or the tag-creator, is available.
+	
+	This tag object will always point to a commit object, but may carray additional
+	information in a tag object::
+	
+	 tagref = TagReference.list_items(repo)[0]
+	 print tagref.commit.message
+	 if tagref.tag is not None:
+		print tagref.tag.message"""
 	__slots__ = tuple()
+	_common_path_default = "refs/tags"
+	
+	@property
+	def commit(self):
+		""":return: Commit object the tag ref points to"""
+		obj = self.object
+		if obj.type == "commit":
+			return obj
+		elif obj.type == "tag":
+			# it is a tag object which carries the commit as an object - we can point to anything
+			return obj.object
+		else:
+			raise ValueError( "Tag %s points to a Blob or Tree - have never seen that before" % self )	
+
+	@property
+	def tag(self):
+		"""
+		:return: Tag object this tag ref points to or None in case 
+			we are a light weight tag"""
+		obj = self.object
+		if obj.type == "tag":
+			return obj
+		return None
+		
+	# make object read-only
+	# It should be reasonably hard to adjust an existing tag
+	object = property(Reference._get_object)
 	
 	@classmethod
 	def create(cls, repo, path, ref='HEAD', message=None, force=False, **kwargs):
diff --git a/git/stream.py b/git/stream.py
new file mode 100644
index 00000000..8010a055
--- /dev/null
+++ b/git/stream.py
@@ -0,0 +1,694 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+
+from cStringIO import StringIO
+import errno
+import mmap
+import os
+
+from fun import (
+					msb_size,
+					stream_copy, 
+					apply_delta_data,
+					connect_deltas,
+					DeltaChunkList,
+					delta_types
+				)
+
+from util import (
+		allocate_memory,
+		LazyMixin,
+		make_sha,
+		write, 
+		close,
+		zlib
+	)
+
+has_perf_mod = False
+try:
+	from _perf import apply_delta as c_apply_delta
+	has_perf_mod = True
+except ImportError:
+	pass
+
+__all__ = (	'DecompressMemMapReader', 'FDCompressedSha1Writer', 'DeltaApplyReader', 
+			'Sha1Writer', 'FlexibleSha1Writer', 'ZippedStoreShaWriter', 'FDCompressedSha1Writer',
+			'FDStream', 'NullStream')
+
+
+#{ RO Streams
+
+class DecompressMemMapReader(LazyMixin):
+	"""Reads data in chunks from a memory map and decompresses it. The client sees 
+	only the uncompressed data, respective file-like read calls are handling on-demand
+	buffered decompression accordingly
+	
+	A constraint on the total size of bytes is activated, simulating 
+	a logical file within a possibly larger physical memory area
+	
+	To read efficiently, you clearly don't want to read individual bytes, instead, 
+	read a few kilobytes at least.
+	
+	:note: The chunk-size should be carefully selected as it will involve quite a bit 
+		of string copying due to the way the zlib is implemented. Its very wasteful, 
+		hence we try to find a good tradeoff between allocation time and number of 
+		times we actually allocate. An own zlib implementation would be good here
+		to better support streamed reading - it would only need to keep the mmap
+		and decompress it into chunks, thats all ... """
+	__slots__ = ('_m', '_zip', '_buf', '_buflen', '_br', '_cws', '_cwe', '_s', '_close', 
+				'_cbr', '_phi')
+	
+	max_read_size = 512*1024		# currently unused
+	
+	def __init__(self, m, close_on_deletion, size=None):
+		"""Initialize with mmap for stream reading
+		:param m: must be content data - use new if you have object data and no size"""
+		self._m = m
+		self._zip = zlib.decompressobj()
+		self._buf = None						# buffer of decompressed bytes
+		self._buflen = 0						# length of bytes in buffer
+		if size is not None:
+			self._s = size						# size of uncompressed data to read in total
+		self._br = 0							# num uncompressed bytes read
+		self._cws = 0							# start byte of compression window
+		self._cwe = 0							# end byte of compression window
+		self._cbr = 0							# number of compressed bytes read
+		self._phi = False						# is True if we parsed the header info
+		self._close = close_on_deletion			# close the memmap on deletion ?
+		
+	def _set_cache_(self, attr):
+		assert attr == '_s'
+		# only happens for size, which is a marker to indicate we still 
+		# have to parse the header from the stream
+		self._parse_header_info()
+		
+	def __del__(self):
+		if self._close:
+			self._m.close()
+		# END handle resource freeing
+		
+	def _parse_header_info(self):
+		"""If this stream contains object data, parse the header info and skip the 
+		stream to a point where each read will yield object content
+		
+		:return: parsed type_string, size"""
+		# read header
+		maxb = 512				# should really be enough, cgit uses 8192 I believe
+		self._s = maxb
+		hdr = self.read(maxb)
+		hdrend = hdr.find("\0")
+		type, size = hdr[:hdrend].split(" ")
+		size = int(size)
+		self._s = size
+		
+		# adjust internal state to match actual header length that we ignore
+		# The buffer will be depleted first on future reads
+		self._br = 0
+		hdrend += 1									# count terminating \0
+		self._buf = StringIO(hdr[hdrend:])
+		self._buflen = len(hdr) - hdrend
+		
+		self._phi = True
+		
+		return type, size
+		
+	#{ Interface 
+	
+	@classmethod
+	def new(self, m, close_on_deletion=False):
+		"""Create a new DecompressMemMapReader instance for acting as a read-only stream
+		This method parses the object header from m and returns the parsed 
+		type and size, as well as the created stream instance.
+		
+		:param m: memory map on which to oparate. It must be object data ( header + contents )
+		:param close_on_deletion: if True, the memory map will be closed once we are 
+			being deleted"""
+		inst = DecompressMemMapReader(m, close_on_deletion, 0)
+		type, size = inst._parse_header_info()
+		return type, size, inst
+
+	def data(self):
+		""":return: random access compatible data we are working on"""
+		return self._m 
+	
+	def compressed_bytes_read(self):
+		"""
+		:return: number of compressed bytes read. This includes the bytes it 
+			took to decompress the header ( if there was one )"""
+		# ABSTRACT: When decompressing a byte stream, it can be that the first
+		# x bytes which were requested match the first x bytes in the loosely 
+		# compressed datastream. This is the worst-case assumption that the reader
+		# does, it assumes that it will get at least X bytes from X compressed bytes
+		# in call cases.
+		# The caveat is that the object, according to our known uncompressed size, 
+		# is already complete, but there are still some bytes left in the compressed
+		# stream that contribute to the amount of compressed bytes.
+		# How can we know that we are truly done, and have read all bytes we need
+		# to read ? 
+		# Without help, we cannot know, as we need to obtain the status of the 
+		# decompression. If it is not finished, we need to decompress more data
+		# until it is finished, to yield the actual number of compressed bytes
+		# belonging to the decompressed object
+		# We are using a custom zlib module for this, if its not present, 
+		# we try to put in additional bytes up for decompression if feasible
+		# and check for the unused_data.
+		
+		# Only scrub the stream forward if we are officially done with the
+		# bytes we were to have.
+		if self._br == self._s and not self._zip.unused_data:
+			# manipulate the bytes-read to allow our own read method to coninute
+			# but keep the window at its current position
+			self._br = 0
+			if hasattr(self._zip, 'status'):
+				while self._zip.status == zlib.Z_OK:
+					self.read(mmap.PAGESIZE)
+				# END scrub-loop custom zlib
+			else:
+				# pass in additional pages, until we have unused data
+				while not self._zip.unused_data and self._cbr != len(self._m):
+					self.read(mmap.PAGESIZE)
+				# END scrub-loop default zlib
+			# END handle stream scrubbing
+			
+			# reset bytes read, just to be sure
+			self._br = self._s
+		# END handle stream scrubbing
+		
+		# unused data ends up in the unconsumed tail, which was removed
+		# from the count already
+		return self._cbr
+		
+	#} END interface 
+		
+	def seek(self, offset, whence=getattr(os, 'SEEK_SET', 0)):
+		"""Allows to reset the stream to restart reading
+		:raise ValueError: If offset and whence are not 0"""
+		if offset != 0 or whence != getattr(os, 'SEEK_SET', 0):
+			raise ValueError("Can only seek to position 0")
+		# END handle offset
+		
+		self._zip = zlib.decompressobj()
+		self._br = self._cws = self._cwe = self._cbr = 0
+		if self._phi:
+			self._phi = False
+			del(self._s)		# trigger header parsing on first access
+		# END skip header
+	
+	def read(self, size=-1):
+		if size < 1:
+			size = self._s - self._br
+		else:
+			size = min(size, self._s - self._br)
+		# END clamp size
+		
+		if size == 0:
+			return str()
+		# END handle depletion
+	
+	
+		# deplete the buffer, then just continue using the decompress object 
+		# which has an own buffer. We just need this to transparently parse the 
+		# header from the zlib stream
+		dat = str()
+		if self._buf:
+			if self._buflen >= size:
+				# have enough data
+				dat = self._buf.read(size)
+				self._buflen -= size
+				self._br += size
+				return dat
+			else:
+				dat = self._buf.read()		# ouch, duplicates data
+				size -= self._buflen
+				self._br += self._buflen
+				
+				self._buflen = 0
+				self._buf = None
+			# END handle buffer len
+		# END handle buffer
+		
+		# decompress some data
+		# Abstract: zlib needs to operate on chunks of our memory map ( which may 
+		# be large ), as it will otherwise and always fill in the 'unconsumed_tail'
+		# attribute which possible reads our whole map to the end, forcing 
+		# everything to be read from disk even though just a portion was requested.
+		# As this would be a nogo, we workaround it by passing only chunks of data, 
+		# moving the window into the memory map along as we decompress, which keeps 
+		# the tail smaller than our chunk-size. This causes 'only' the chunk to be
+		# copied once, and another copy of a part of it when it creates the unconsumed
+		# tail. We have to use it to hand in the appropriate amount of bytes durin g
+		# the next read.
+		tail = self._zip.unconsumed_tail
+		if tail:
+			# move the window, make it as large as size demands. For code-clarity, 
+			# we just take the chunk from our map again instead of reusing the unconsumed
+			# tail. The latter one would safe some memory copying, but we could end up
+			# with not getting enough data uncompressed, so we had to sort that out as well.
+			# Now we just assume the worst case, hence the data is uncompressed and the window
+			# needs to be as large as the uncompressed bytes we want to read.
+			self._cws = self._cwe - len(tail)
+			self._cwe = self._cws + size
+		else:
+			cws = self._cws
+			self._cws = self._cwe
+			self._cwe = cws + size 
+		# END handle tail
+		
+		
+		# if window is too small, make it larger so zip can decompress something
+		if self._cwe - self._cws < 8:
+			self._cwe = self._cws + 8
+		# END adjust winsize
+		
+		# takes a slice, but doesn't copy the data, it says ... 
+		indata = buffer(self._m, self._cws, self._cwe - self._cws)
+		
+		# get the actual window end to be sure we don't use it for computations
+		self._cwe = self._cws + len(indata)
+		dcompdat = self._zip.decompress(indata, size)
+		# update the amount of compressed bytes read
+		# We feed possibly overlapping chunks, which is why the unconsumed tail
+		# has to be taken into consideration, as well as the unused data
+		# if we hit the end of the stream
+		self._cbr += len(indata) - len(self._zip.unconsumed_tail)
+		self._br += len(dcompdat)
+		
+		if dat:
+			dcompdat = dat + dcompdat
+		# END prepend our cached data
+			
+		# it can happen, depending on the compression, that we get less bytes 
+		# than ordered as it needs the final portion of the data as well. 
+		# Recursively resolve that.
+		# Note: dcompdat can be empty even though we still appear to have bytes
+		# to read, if we are called by compressed_bytes_read - it manipulates
+		# us to empty the stream
+		if dcompdat and (len(dcompdat) - len(dat)) < size and self._br < self._s:
+			dcompdat += self.read(size-len(dcompdat))
+		# END handle special case
+		return dcompdat
+
+	
+class DeltaApplyReader(LazyMixin):
+	"""A reader which dynamically applies pack deltas to a base object, keeping the 
+	memory demands to a minimum.
+	
+	The size of the final object is only obtainable once all deltas have been 
+	applied, unless it is retrieved from a pack index.
+	
+	The uncompressed Delta has the following layout (MSB being a most significant
+	bit encoded dynamic size):
+	
+	* MSB Source Size - the size of the base against which the delta was created
+	* MSB Target Size - the size of the resulting data after the delta was applied
+	* A list of one byte commands (cmd) which are followed by a specific protocol:
+	
+	 * cmd & 0x80 - copy delta_data[offset:offset+size]
+	 
+	  * Followed by an encoded offset into the delta data
+	  * Followed by an encoded size of the chunk to copy
+	  
+	 *  cmd & 0x7f - insert
+	 
+	  * insert cmd bytes from the delta buffer into the output stream
+	  
+	 * cmd == 0 - invalid operation ( or error in delta stream )
+	"""
+	__slots__ = (
+					"_bstream",				# base stream to which to apply the deltas
+					"_dstreams",			# tuple of delta stream readers
+					"_mm_target",			# memory map of the delta-applied data
+					"_size",				# actual number of bytes in _mm_target
+					"_br"					# number of bytes read 
+				)
+	
+	#{ Configuration
+	k_max_memory_move = 250*1000*1000
+	#} END configuration
+	
+	def __init__(self, stream_list):
+		"""Initialize this instance with a list of streams, the first stream being 
+		the delta to apply on top of all following deltas, the last stream being the
+		base object onto which to apply the deltas"""
+		assert len(stream_list) > 1, "Need at least one delta and one base stream"
+		
+		self._bstream = stream_list[-1]
+		self._dstreams = tuple(stream_list[:-1])
+		self._br = 0
+		
+	def _set_cache_too_slow_without_c(self, attr):
+		# the direct algorithm is fastest and most direct if there is only one 
+		# delta. Also, the extra overhead might not be worth it for items smaller
+		# than X - definitely the case in python, every function call costs 
+		# huge amounts of time
+		# if len(self._dstreams) * self._bstream.size < self.k_max_memory_move:
+		if len(self._dstreams) == 1:
+			return self._set_cache_brute_(attr)
+		
+		# Aggregate all deltas into one delta in reverse order. Hence we take 
+		# the last delta, and reverse-merge its ancestor delta, until we receive
+		# the final delta data stream.
+		# print "Handling %i delta streams, sizes: %s" % (len(self._dstreams), [ds.size for ds in self._dstreams])
+		dcl = connect_deltas(self._dstreams)
+		
+		# call len directly, as the (optional) c version doesn't implement the sequence
+		# protocol
+		if dcl.rbound() == 0:
+			self._size = 0
+			self._mm_target = allocate_memory(0)
+			return
+		# END handle empty list
+		
+		self._size = dcl.rbound()
+		self._mm_target = allocate_memory(self._size)
+		
+		bbuf = allocate_memory(self._bstream.size)
+		stream_copy(self._bstream.read, bbuf.write, self._bstream.size, 256 * mmap.PAGESIZE)
+		
+		# APPLY CHUNKS
+		write = self._mm_target.write
+		dcl.apply(bbuf, write)
+		
+		self._mm_target.seek(0)
+		
+	def _set_cache_brute_(self, attr):
+		"""If we are here, we apply the actual deltas"""
+		
+		# TODO: There should be a special case if there is only one stream
+		# Then the default-git algorithm should perform a tad faster, as the
+		# delta is not peaked into, causing less overhead.
+		buffer_info_list = list()
+		max_target_size = 0
+		for dstream in self._dstreams:
+			buf = dstream.read(512)			# read the header information + X
+			offset, src_size = msb_size(buf)
+			offset, target_size = msb_size(buf, offset)
+			buffer_info_list.append((buffer(buf, offset), offset, src_size, target_size))
+			max_target_size = max(max_target_size, target_size)
+		# END for each delta stream
+		
+		# sanity check - the first delta to apply should have the same source
+		# size as our actual base stream
+		base_size = self._bstream.size
+		target_size = max_target_size
+		
+		# if we have more than 1 delta to apply, we will swap buffers, hence we must
+		# assure that all buffers we use are large enough to hold all the results
+		if len(self._dstreams) > 1:
+			base_size = target_size = max(base_size, max_target_size)
+		# END adjust buffer sizes
+			
+		
+		# Allocate private memory map big enough to hold the first base buffer
+		# We need random access to it
+		bbuf = allocate_memory(base_size)
+		stream_copy(self._bstream.read, bbuf.write, base_size, 256 * mmap.PAGESIZE)
+		
+		# allocate memory map large enough for the largest (intermediate) target
+		# We will use it as scratch space for all delta ops. If the final 
+		# target buffer is smaller than our allocated space, we just use parts
+		# of it upon return.
+		tbuf = allocate_memory(target_size)
+		
+		# for each delta to apply, memory map the decompressed delta and 
+		# work on the op-codes to reconstruct everything.
+		# For the actual copying, we use a seek and write pattern of buffer
+		# slices.
+		final_target_size = None
+		for (dbuf, offset, src_size, target_size), dstream in reversed(zip(buffer_info_list, self._dstreams)):
+			# allocate a buffer to hold all delta data - fill in the data for 
+			# fast access. We do this as we know that reading individual bytes
+			# from our stream would be slower than necessary ( although possible )
+			# The dbuf buffer contains commands after the first two MSB sizes, the
+			# offset specifies the amount of bytes read to get the sizes.
+			ddata = allocate_memory(dstream.size - offset)
+			ddata.write(dbuf)
+			# read the rest from the stream. The size we give is larger than necessary
+			stream_copy(dstream.read, ddata.write, dstream.size, 256*mmap.PAGESIZE)
+			
+			#######################################################################
+			if 'c_apply_delta' in globals():
+				c_apply_delta(bbuf, ddata, tbuf);
+			else:
+				apply_delta_data(bbuf, src_size, ddata, len(ddata), tbuf.write)
+			#######################################################################
+			
+			# finally, swap out source and target buffers. The target is now the 
+			# base for the next delta to apply
+			bbuf, tbuf = tbuf, bbuf
+			bbuf.seek(0)
+			tbuf.seek(0)
+			final_target_size = target_size
+		# END for each delta to apply
+		
+		# its already seeked to 0, constrain it to the actual size
+		# NOTE: in the end of the loop, it swaps buffers, hence our target buffer
+		# is not tbuf, but bbuf !
+		self._mm_target = bbuf
+		self._size = final_target_size
+		
+	
+	#{ Configuration
+	if not has_perf_mod:
+		_set_cache_ = _set_cache_brute_
+	else:
+		_set_cache_ = _set_cache_too_slow_without_c
+	
+	#} END configuration
+		
+	def read(self, count=0):
+		bl = self._size - self._br		# bytes left
+		if count < 1 or count > bl:
+			count = bl
+		# NOTE: we could check for certain size limits, and possibly
+		# return buffers instead of strings to prevent byte copying
+		data = self._mm_target.read(count)
+		self._br += len(data)
+		return data
+		
+	def seek(self, offset, whence=getattr(os, 'SEEK_SET', 0)):
+		"""Allows to reset the stream to restart reading
+		
+		:raise ValueError: If offset and whence are not 0"""
+		if offset != 0 or whence != getattr(os, 'SEEK_SET', 0):
+			raise ValueError("Can only seek to position 0")
+		# END handle offset
+		self._br = 0
+		self._mm_target.seek(0)
+		
+	#{ Interface 
+	
+	@classmethod
+	def new(cls, stream_list):
+		"""
+		Convert the given list of streams into a stream which resolves deltas
+		when reading from it.
+		
+		:param stream_list: two or more stream objects, first stream is a Delta
+			to the object that you want to resolve, followed by N additional delta
+			streams. The list's last stream must be a non-delta stream.
+			
+		:return: Non-Delta OPackStream object whose stream can be used to obtain 
+			the decompressed resolved data
+		:raise ValueError: if the stream list cannot be handled"""
+		if len(stream_list) < 2:
+			raise ValueError("Need at least two streams")
+		# END single object special handling
+		
+		if stream_list[-1].type_id in delta_types:
+			raise ValueError("Cannot resolve deltas if there is no base object stream, last one was type: %s" % stream_list[-1].type)
+		# END check stream
+		
+		return cls(stream_list)
+		
+	#} END interface
+	
+	
+	#{ OInfo like Interface
+	
+	@property
+	def type(self):
+		return self._bstream.type
+		
+	@property
+	def type_id(self):
+		return self._bstream.type_id
+		
+	@property
+	def size(self):
+		""":return: number of uncompressed bytes in the stream"""
+		return self._size
+		
+	#} END oinfo like interface 
+	
+	
+#} END RO streams
+
+
+#{ W Streams
+
+class Sha1Writer(object):
+	"""Simple stream writer which produces a sha whenever you like as it degests
+	everything it is supposed to write"""
+	__slots__ = "sha1"
+	
+	def __init__(self):
+		self.sha1 = make_sha()
+
+	#{ Stream Interface
+
+	def write(self, data):
+		""":raise IOError: If not all bytes could be written
+		:return: lenght of incoming data"""
+		self.sha1.update(data)
+		return len(data)
+
+	# END stream interface 
+
+	#{ Interface
+	
+	def sha(self, as_hex = False):
+		""":return: sha so far
+		:param as_hex: if True, sha will be hex-encoded, binary otherwise"""
+		if as_hex:
+			return self.sha1.hexdigest()
+		return self.sha1.digest()
+	
+	#} END interface 
+
+
+class FlexibleSha1Writer(Sha1Writer):
+	"""Writer producing a sha1 while passing on the written bytes to the given 
+	write function"""
+	__slots__ = 'writer'
+	
+	def __init__(self, writer):
+		Sha1Writer.__init__(self)
+		self.writer = writer
+	
+	def write(self, data):
+		Sha1Writer.write(self, data)
+		self.writer(data)
+
+
+class ZippedStoreShaWriter(Sha1Writer):
+	"""Remembers everything someone writes to it and generates a sha"""
+	__slots__ = ('buf', 'zip')
+	def __init__(self):
+		Sha1Writer.__init__(self)
+		self.buf = StringIO()
+		self.zip = zlib.compressobj(zlib.Z_BEST_SPEED)
+	
+	def __getattr__(self, attr):
+		return getattr(self.buf, attr)
+	
+	def write(self, data):
+		alen = Sha1Writer.write(self, data)
+		self.buf.write(self.zip.compress(data))
+		return alen
+		
+	def close(self):
+		self.buf.write(self.zip.flush())
+		
+	def seek(self, offset, whence=getattr(os, 'SEEK_SET', 0)):
+		"""Seeking currently only supports to rewind written data
+		Multiple writes are not supported"""
+		if offset != 0 or whence != getattr(os, 'SEEK_SET', 0):
+			raise ValueError("Can only seek to position 0")
+		# END handle offset
+		self.buf.seek(0)
+		
+	def getvalue(self):
+		""":return: string value from the current stream position to the end"""
+		return self.buf.getvalue()
+
+
+class FDCompressedSha1Writer(Sha1Writer):
+	"""Digests data written to it, making the sha available, then compress the 
+	data and write it to the file descriptor
+	
+	:note: operates on raw file descriptors
+	:note: for this to work, you have to use the close-method of this instance"""
+	__slots__ = ("fd", "sha1", "zip")
+	
+	# default exception
+	exc = IOError("Failed to write all bytes to filedescriptor")
+	
+	def __init__(self, fd):
+		super(FDCompressedSha1Writer, self).__init__()
+		self.fd = fd
+		self.zip = zlib.compressobj(zlib.Z_BEST_SPEED)
+
+	#{ Stream Interface
+
+	def write(self, data):
+		""":raise IOError: If not all bytes could be written
+		:return: lenght of incoming data"""
+		self.sha1.update(data)
+		cdata = self.zip.compress(data)
+		bytes_written = write(self.fd, cdata)
+		if bytes_written != len(cdata):
+			raise self.exc
+		return len(data)
+
+	def close(self):
+		remainder = self.zip.flush()
+		if write(self.fd, remainder) != len(remainder):
+			raise self.exc
+		return close(self.fd)
+
+	#} END stream interface
+
+
+class FDStream(object):
+	"""A simple wrapper providing the most basic functions on a file descriptor 
+	with the fileobject interface. Cannot use os.fdopen as the resulting stream
+	takes ownership"""
+	__slots__ = ("_fd", '_pos')
+	def __init__(self, fd):
+		self._fd = fd
+		self._pos = 0
+		
+	def write(self, data):
+		self._pos += len(data)
+		os.write(self._fd, data)
+	
+	def read(self, count=0):
+		if count == 0:
+			count = os.path.getsize(self._filepath)
+		# END handle read everything
+			
+		bytes = os.read(self._fd, count)
+		self._pos += len(bytes)
+		return bytes
+		
+	def fileno(self):
+		return self._fd
+		
+	def tell(self):
+		return self._pos
+		
+	def close(self):
+		close(self._fd)
+
+
+class NullStream(object):
+	"""A stream that does nothing but providing a stream interface.
+	Use it like /dev/null"""
+	__slots__ = tuple()
+		
+	def read(self, size=0):
+		return ''
+		
+	def close(self):
+		pass
+		
+	def write(self, data):
+		return len(data)
+
+
+#} END W streams
+
+
diff --git a/git/test/__init__.py b/git/test/__init__.py
index 757cbad1..63d25743 100644
--- a/git/test/__init__.py
+++ b/git/test/__init__.py
@@ -3,3 +3,12 @@
 #
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
+
+import gitdb.util
+
+def _init_pool():
+	"""Assure the pool is actually threaded"""
+	size = 2
+	print "Setting ThreadPool to %i" % size
+	gitdb.util.pool.set_size(size)
+
diff --git a/git/test/db/__init__.py b/git/test/db/__init__.py
new file mode 100644
index 00000000..8a681e42
--- /dev/null
+++ b/git/test/db/__init__.py
@@ -0,0 +1,4 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
diff --git a/git/test/db/lib.py b/git/test/db/lib.py
new file mode 100644
index 00000000..5f4f9c36
--- /dev/null
+++ b/git/test/db/lib.py
@@ -0,0 +1,215 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Base classes for object db testing"""
+from gitdb.test.lib import (
+	with_rw_directory,
+	with_packs_rw,
+	ZippedStoreShaWriter,
+	fixture_path,
+	TestBase
+	)
+
+from gitdb.stream import Sha1Writer
+
+# import database types we want to support
+# they will be set to None if the respective library could not be loaded
+from gitdb.db.py import PureGitDB
+
+from gitdb.base import (
+							IStream,
+							OStream,
+							OInfo
+						)
+				
+from gitdb.exc import BadObject
+from gitdb.typ import str_blob_type
+
+from async import IteratorReader
+from cStringIO import StringIO
+from struct import pack
+
+
+__all__ = ('TestDBBase', 'with_rw_directory', 'with_packs_rw', 'fixture_path')
+		
+class TestDBBase(TestBase):
+	"""Base class providing testing routines on databases"""
+	
+	# data
+	two_lines = "1234\nhello world"
+	all_data = (two_lines, )
+	
+	# all supported database types. Add your own type 
+	ref_db_types = (PureGitDB, )
+	
+	def _assert_object_writing_simple(self, db):
+		# write a bunch of objects and query their streams and info
+		null_objs = db.size()
+		ni = 250
+		for i in xrange(ni):
+			data = pack(">L", i)
+			istream = IStream(str_blob_type, len(data), StringIO(data))
+			new_istream = db.store(istream)
+			assert new_istream is istream
+			assert db.has_object(istream.binsha)
+			
+			info = db.info(istream.binsha)
+			assert isinstance(info, OInfo)
+			assert info.type == istream.type and info.size == istream.size
+			
+			stream = db.stream(istream.binsha)
+			assert isinstance(stream, OStream)
+			assert stream.binsha == info.binsha and stream.type == info.type
+			assert stream.read() == data
+		# END for each item
+		
+		assert db.size() == null_objs + ni
+		shas = list(db.sha_iter())
+		assert len(shas) == db.size()
+		assert len(shas[0]) == 20
+		
+	
+	def _assert_object_writing(self, db):
+		"""General tests to verify object writing, compatible to ObjectDBW
+		:note: requires write access to the database"""
+		# start in 'dry-run' mode, using a simple sha1 writer
+		ostreams = (ZippedStoreShaWriter, None)
+		for ostreamcls in ostreams:
+			for data in self.all_data:
+				dry_run = ostreamcls is not None
+				ostream = None
+				if ostreamcls is not None:
+					ostream = ostreamcls()
+					assert isinstance(ostream, Sha1Writer)
+				# END create ostream
+				
+				prev_ostream = db.set_ostream(ostream)
+				assert type(prev_ostream) in ostreams or prev_ostream in ostreams 
+					
+				istream = IStream(str_blob_type, len(data), StringIO(data))
+				
+				# store returns same istream instance, with new sha set
+				my_istream = db.store(istream)
+				sha = istream.binsha
+				assert my_istream is istream
+				assert db.has_object(sha) != dry_run
+				assert len(sha) == 20	
+				
+				# verify data - the slow way, we want to run code
+				if not dry_run:
+					info = db.info(sha)
+					assert str_blob_type == info.type
+					assert info.size == len(data)
+					
+					ostream = db.stream(sha)
+					assert ostream.read() == data
+					assert ostream.type == str_blob_type
+					assert ostream.size == len(data)
+				else:
+					self.failUnlessRaises(BadObject, db.info, sha)
+					self.failUnlessRaises(BadObject, db.stream, sha)
+					
+					# DIRECT STREAM COPY
+					# our data hase been written in object format to the StringIO
+					# we pasesd as output stream. No physical database representation
+					# was created.
+					# Test direct stream copy of object streams, the result must be 
+					# identical to what we fed in
+					ostream.seek(0)
+					istream.stream = ostream
+					assert istream.binsha is not None
+					prev_sha = istream.binsha
+					
+					db.set_ostream(ZippedStoreShaWriter())
+					db.store(istream)
+					assert istream.binsha == prev_sha
+					new_ostream = db.ostream()
+					
+					# note: only works as long our store write uses the same compression
+					# level, which is zip_best
+					assert ostream.getvalue() == new_ostream.getvalue()
+			# END for each data set
+		# END for each dry_run mode
+		
+	def _assert_object_writing_async(self, db):
+		"""Test generic object writing using asynchronous access"""
+		ni = 5000
+		def istream_generator(offset=0, ni=ni):
+			for data_src in xrange(ni):
+				data = str(data_src + offset)
+				yield IStream(str_blob_type, len(data), StringIO(data))
+			# END for each item
+		# END generator utility
+		
+		# for now, we are very trusty here as we expect it to work if it worked
+		# in the single-stream case
+		
+		# write objects
+		reader = IteratorReader(istream_generator())
+		istream_reader = db.store_async(reader)
+		istreams = istream_reader.read()		# read all
+		assert istream_reader.task().error() is None
+		assert len(istreams) == ni
+		
+		for stream in istreams:
+			assert stream.error is None
+			assert len(stream.binsha) == 20
+			assert isinstance(stream, IStream)
+		# END assert each stream
+		
+		# test has-object-async - we must have all previously added ones
+		reader = IteratorReader( istream.binsha for istream in istreams )
+		hasobject_reader = db.has_object_async(reader)
+		count = 0
+		for sha, has_object in hasobject_reader:
+			assert has_object
+			count += 1
+		# END for each sha
+		assert count == ni
+		
+		# read the objects we have just written
+		reader = IteratorReader( istream.binsha for istream in istreams )
+		ostream_reader = db.stream_async(reader)
+		
+		# read items individually to prevent hitting possible sys-limits
+		count = 0
+		for ostream in ostream_reader:
+			assert isinstance(ostream, OStream)
+			count += 1
+		# END for each ostream
+		assert ostream_reader.task().error() is None
+		assert count == ni
+		
+		# get info about our items
+		reader = IteratorReader( istream.binsha for istream in istreams )
+		info_reader = db.info_async(reader)
+		
+		count = 0
+		for oinfo in info_reader:
+			assert isinstance(oinfo, OInfo)
+			count += 1
+		# END for each oinfo instance
+		assert count == ni
+		
+		  
+		# combined read-write using a converter
+		# add 2500 items, and obtain their output streams
+		nni = 2500
+		reader = IteratorReader(istream_generator(offset=ni, ni=nni))
+		istream_to_sha = lambda istreams: [ istream.binsha for istream in istreams ]
+		
+		istream_reader = db.store_async(reader)
+		istream_reader.set_post_cb(istream_to_sha)
+		
+		ostream_reader = db.stream_async(istream_reader)
+		
+		count = 0
+		# read it individually, otherwise we might run into the ulimit
+		for ostream in ostream_reader:
+			assert isinstance(ostream, OStream)
+			count += 1
+		# END for each ostream
+		assert count == nni
+		
+		
diff --git a/git/test/db/test_base.py b/git/test/db/test_base.py
new file mode 100644
index 00000000..0a381beb
--- /dev/null
+++ b/git/test/db/test_base.py
@@ -0,0 +1,18 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from lib import *
+from gitdb.db import RefSpec
+
+class TestBase(TestDBBase):
+	
+	@with_rw_directory
+	def test_basics(self, path):
+		self.failUnlessRaises(ValueError, RefSpec, None, None)
+		rs = RefSpec(None, "something")
+		assert rs.force == False
+		assert rs.delete_destination()
+		assert rs.source is None
+		assert rs.destination == "something"
+		
diff --git a/git/test/db/test_git.py b/git/test/db/test_git.py
new file mode 100644
index 00000000..62f33bb1
--- /dev/null
+++ b/git/test/db/test_git.py
@@ -0,0 +1,47 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from lib import *
+from gitdb.exc import BadObject
+from gitdb.db.py import PureGitODB
+from gitdb.base import OStream, OInfo
+from gitdb.util import hex_to_bin, bin_to_hex
+		
+class TestGitDB(TestDBBase):
+	
+	def test_reading(self):
+		gdb = PureGitODB(fixture_path('../../../.git/objects'))
+		
+		# we have packs and loose objects, alternates doesn't necessarily exist
+		assert 1 < len(gdb.databases()) < 4
+		
+		# access should be possible
+		gitdb_sha = hex_to_bin("5690fd0d3304f378754b23b098bd7cb5f4aa1976")
+		assert isinstance(gdb.info(gitdb_sha), OInfo)
+		assert isinstance(gdb.stream(gitdb_sha), OStream)
+		assert gdb.size() > 200
+		sha_list = list(gdb.sha_iter())
+		assert len(sha_list) == gdb.size()
+		
+		
+		# This is actually a test for compound functionality, but it doesn't 
+		# have a separate test module
+		# test partial shas
+		# this one as uneven and quite short
+		assert gdb.partial_to_complete_sha_hex('155b6') == hex_to_bin("155b62a9af0aa7677078331e111d0f7aa6eb4afc")
+		
+		# mix even/uneven hexshas
+		for i, binsha in enumerate(sha_list):
+			assert gdb.partial_to_complete_sha_hex(bin_to_hex(binsha)[:8-(i%2)]) == binsha
+		# END for each sha
+		
+		self.failUnlessRaises(BadObject, gdb.partial_to_complete_sha_hex, "0000")
+		
+	@with_rw_directory
+	def test_writing(self, path):
+		gdb = PureGitODB(path)
+		
+		# its possible to write objects
+		self._assert_object_writing(gdb)
+		self._assert_object_writing_async(gdb)
diff --git a/git/test/db/test_loose.py b/git/test/db/test_loose.py
new file mode 100644
index 00000000..b1d33fd6
--- /dev/null
+++ b/git/test/db/test_loose.py
@@ -0,0 +1,34 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from lib import *
+from gitdb.db.py import PureLooseObjectODB
+from gitdb.exc import BadObject
+from gitdb.util import bin_to_hex
+		
+class TestLooseDB(TestDBBase):
+	
+	@with_rw_directory
+	def test_basics(self, path):
+		ldb = PureLooseObjectODB(path)
+		
+		# write data
+		self._assert_object_writing(ldb)
+		self._assert_object_writing_async(ldb)
+	
+		# verify sha iteration and size
+		shas = list(ldb.sha_iter())
+		assert shas and len(shas[0]) == 20
+		
+		assert len(shas) == ldb.size()
+		
+		# verify find short object
+		long_sha = bin_to_hex(shas[-1])
+		for short_sha in (long_sha[:20], long_sha[:5]):
+			assert bin_to_hex(ldb.partial_to_complete_sha_hex(short_sha)) == long_sha
+		# END for each sha
+		
+		self.failUnlessRaises(BadObject, ldb.partial_to_complete_sha_hex, '0000')
+		# raises if no object could be foudn
+		
diff --git a/git/test/db/test_mem.py b/git/test/db/test_mem.py
new file mode 100644
index 00000000..79005b50
--- /dev/null
+++ b/git/test/db/test_mem.py
@@ -0,0 +1,30 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from lib import *
+from gitdb.db.py import (
+						PureMemoryDB,
+						PureLooseObjectODB
+					)
+		
+class TestPureMemoryDB(TestDBBase):
+	
+	@with_rw_directory
+	def test_writing(self, path):
+		mdb = PureMemoryDB()
+		
+		# write data
+		self._assert_object_writing_simple(mdb)
+		
+		# test stream copy
+		ldb = PureLooseObjectODB(path)
+		assert ldb.size() == 0
+		num_streams_copied = mdb.stream_copy(mdb.sha_iter(), ldb)
+		assert num_streams_copied == mdb.size()
+		
+		assert ldb.size() == mdb.size()
+		for sha in mdb.sha_iter():
+			assert ldb.has_object(sha)
+			assert ldb.stream(sha).read() == mdb.stream(sha).read() 
+		# END verify objects where copied and are equal
diff --git a/git/test/db/test_pack.py b/git/test/db/test_pack.py
new file mode 100644
index 00000000..5456df41
--- /dev/null
+++ b/git/test/db/test_pack.py
@@ -0,0 +1,72 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from lib import *
+from gitdb.db.py import PurePackedODB
+from gitdb.test.lib import fixture_path
+
+from gitdb.exc import BadObject, AmbiguousObjectName
+
+import os
+import random
+
+class TestPackDB(TestDBBase):
+	
+	@with_packs_rw
+	def test_writing(self, path):
+		pdb = PurePackedODB(path)
+		
+		# on demand, we init our pack cache
+		num_packs = len(pdb.entities())
+		assert pdb._st_mtime != 0
+		
+		# test pack directory changed: 
+		# packs removed - rename a file, should affect the glob
+		pack_path = pdb.entities()[0].pack().path()
+		new_pack_path = pack_path + "renamed"
+		os.rename(pack_path, new_pack_path)
+		
+		pdb.update_cache(force=True)
+		assert len(pdb.entities()) == num_packs - 1
+		
+		# packs added
+		os.rename(new_pack_path, pack_path)
+		pdb.update_cache(force=True)
+		assert len(pdb.entities()) == num_packs
+	
+		# bang on the cache
+		# access the Entities directly, as there is no iteration interface
+		# yet ( or required for now )
+		sha_list = list(pdb.sha_iter())
+		assert len(sha_list) == pdb.size()
+		
+		# hit all packs in random order
+		random.shuffle(sha_list)
+		
+		for sha in sha_list:
+			info = pdb.info(sha)
+			stream = pdb.stream(sha)
+		# END for each sha to query
+		
+		
+		# test short finding - be a bit more brutal here
+		max_bytes = 19
+		min_bytes = 2
+		num_ambiguous = 0
+		for i, sha in enumerate(sha_list):
+			short_sha = sha[:max((i % max_bytes), min_bytes)]
+			try:
+				assert pdb.partial_to_complete_sha(short_sha, len(short_sha)*2) == sha
+			except AmbiguousObjectName:
+				num_ambiguous += 1
+				pass # valid, we can have short objects
+			# END exception handling
+		# END for each sha to find
+		
+		# we should have at least one ambiguous, considering the small sizes
+		# but in our pack, there is no ambigious ... 
+		# assert num_ambiguous
+		
+		# non-existing
+		self.failUnlessRaises(BadObject, pdb.partial_to_complete_sha, "\0\0", 4)
diff --git a/git/test/db/test_ref.py b/git/test/db/test_ref.py
new file mode 100644
index 00000000..330dab70
--- /dev/null
+++ b/git/test/db/test_ref.py
@@ -0,0 +1,60 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+from lib import *
+from gitdb.db.py import PureReferenceDB
+
+from gitdb.util import (
+						NULL_BIN_SHA,
+						hex_to_bin
+						)
+
+import os
+		
+class TestPureReferenceDB(TestDBBase):
+	
+	def make_alt_file(self, alt_path, alt_list):
+		"""Create an alternates file which contains the given alternates.
+		The list can be empty"""
+		alt_file = open(alt_path, "wb")
+		for alt in alt_list:
+			alt_file.write(alt + "\n")
+		alt_file.close()
+	
+	@with_rw_directory
+	def test_writing(self, path):
+		NULL_BIN_SHA = '\0'  * 20
+		
+		alt_path = os.path.join(path, 'alternates')
+		rdb = PureReferenceDB(alt_path)
+		assert len(rdb.databases()) == 0
+		assert rdb.size() == 0
+		assert len(list(rdb.sha_iter())) == 0
+		
+		# try empty, non-existing
+		assert not rdb.has_object(NULL_BIN_SHA)
+		
+		
+		# setup alternate file
+		# add two, one is invalid
+		own_repo_path = fixture_path('../../../.git/objects')		# use own repo
+		self.make_alt_file(alt_path, [own_repo_path, "invalid/path"])
+		rdb.update_cache()
+		assert len(rdb.databases()) == 1
+		
+		# we should now find a default revision of ours
+		gitdb_sha = hex_to_bin("5690fd0d3304f378754b23b098bd7cb5f4aa1976")
+		assert rdb.has_object(gitdb_sha)
+		
+		# remove valid
+		self.make_alt_file(alt_path, ["just/one/invalid/path"])
+		rdb.update_cache()
+		assert len(rdb.databases()) == 0
+		
+		# add valid
+		self.make_alt_file(alt_path, [own_repo_path])
+		rdb.update_cache()
+		assert len(rdb.databases()) == 1
+		
+		
diff --git a/git/test/fixtures/objects/7b/b839852ed5e3a069966281bb08d50012fb309b b/git/test/fixtures/objects/7b/b839852ed5e3a069966281bb08d50012fb309b
new file mode 100644
index 00000000..021c2db3
--- /dev/null
+++ b/git/test/fixtures/objects/7b/b839852ed5e3a069966281bb08d50012fb309b
diff --git a/git/test/fixtures/packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.idx b/git/test/fixtures/packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.idx
new file mode 100644
index 00000000..fda5969b
--- /dev/null
+++ b/git/test/fixtures/packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.idx
diff --git a/git/test/fixtures/packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.pack b/git/test/fixtures/packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.pack
new file mode 100644
index 00000000..a3209d2b
--- /dev/null
+++ b/git/test/fixtures/packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.pack
diff --git a/git/test/fixtures/packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.idx b/git/test/fixtures/packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.idx
new file mode 100644
index 00000000..a7d6c717
--- /dev/null
+++ b/git/test/fixtures/packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.idx
diff --git a/git/test/fixtures/packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.pack b/git/test/fixtures/packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.pack
new file mode 100644
index 00000000..955c424c
--- /dev/null
+++ b/git/test/fixtures/packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.pack
diff --git a/git/test/fixtures/packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.idx b/git/test/fixtures/packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.idx
new file mode 100644
index 00000000..87c635f4
--- /dev/null
+++ b/git/test/fixtures/packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.idx
diff --git a/git/test/fixtures/packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.pack b/git/test/fixtures/packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.pack
new file mode 100644
index 00000000..a69b28ac
--- /dev/null
+++ b/git/test/fixtures/packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.pack
diff --git a/git/test/lib/__init__.py b/git/test/lib/__init__.py
index 77512794..b09a86b1 100644
--- a/git/test/lib/__init__.py
+++ b/git/test/lib/__init__.py
@@ -8,6 +8,7 @@ import inspect
 from mock import *
 from asserts import *
 from helper import *
+from base import *
 
 __all__ = [ name for name, obj in locals().items()
             if not (name.startswith('_') or inspect.ismodule(obj)) ]
diff --git a/git/test/lib/base.py b/git/test/lib/base.py
new file mode 100644
index 00000000..9224f5f6
--- /dev/null
+++ b/git/test/lib/base.py
@@ -0,0 +1,200 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of PureGitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Utilities used in ODB testing"""
+from gitdb import OStream
+from gitdb.db.py import PureGitDB
+from gitdb.stream import ( 
+							Sha1Writer, 
+							ZippedStoreShaWriter
+						)
+
+from gitdb.util import zlib
+
+import sys
+import random
+from array import array
+from cStringIO import StringIO
+
+import glob
+import unittest
+import tempfile
+import shutil
+import os
+import gc
+
+
+#{ Decorators
+
+def with_rw_directory(func):
+	"""Create a temporary directory which can be written to, remove it if the 
+	test suceeds, but leave it otherwise to aid additional debugging"""
+	def wrapper(self):
+		path = tempfile.mktemp(prefix=func.__name__)
+		os.mkdir(path)
+		keep = False
+		try:
+			try:
+				return func(self, path)
+			except Exception:
+				print >> sys.stderr, "Test %s.%s failed, output is at %r" % (type(self).__name__, func.__name__, path)
+				keep = True
+				raise
+		finally:
+			# Need to collect here to be sure all handles have been closed. It appears
+			# a windows-only issue. In fact things should be deleted, as well as 
+			# memory maps closed, once objects go out of scope. For some reason
+			# though this is not the case here unless we collect explicitly.
+			if not keep:
+				gc.collect()
+				shutil.rmtree(path)
+		# END handle exception
+	# END wrapper
+	
+	wrapper.__name__ = func.__name__
+	return wrapper
+
+
+def with_rw_repo(func):
+	"""Create a copy of our repository and put it into a writable location. It will 
+	be removed if the test doesn't result in an error.
+	As we can currently only copy the fully working tree, tests must not rely on 
+	being on a certain branch or on anything really except for the default tags
+	that should exist
+	Wrapped function obtains a git repository """
+	def wrapper(self, path):
+		src_dir = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+		assert(os.path.isdir(path))
+		os.rmdir(path)		# created by wrapper, but must not exist for copy operation
+		shutil.copytree(src_dir, path)
+		target_gitdir = os.path.join(path, '.git')
+		assert os.path.isdir(target_gitdir)
+		return func(self, PureGitDB(target_gitdir))
+	#END wrapper
+	wrapper.__name__ = func.__name__
+	return with_rw_directory(wrapper)
+	
+
+
+def with_packs_rw(func):
+	"""Function that provides a path into which the packs for testing should be 
+	copied. Will pass on the path to the actual function afterwards
+	
+	:note: needs with_rw_directory wrapped around it"""
+	def wrapper(self, path):
+		src_pack_glob = fixture_path('packs/*')
+		copy_files_globbed(src_pack_glob, path, hard_link_ok=True)
+		return func(self, path)
+	# END wrapper
+	
+	wrapper.__name__ = func.__name__
+	return with_rw_directory(wrapper)
+
+#} END decorators
+
+#{ Routines
+
+def repo_dir():
+	""":return: path to our own repository, being our own .git directory.
+	:note: doesn't work in bare repositories"""
+	base = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), '.git')
+	assert os.path.isdir(base)
+	return base
+	
+
+def maketemp(*args):
+	"""Wrapper around default tempfile.mktemp to fix an osx issue"""
+	tdir = tempfile.mktemp(*args)
+	if sys.platform == 'darwin':
+		tdir = '/private' + tdir
+	return tdir
+
+def fixture_path(relapath=''):
+	""":return: absolute path into the fixture directory
+	:param relapath: relative path into the fixtures directory, or ''
+		to obtain the fixture directory itself"""
+	return os.path.join(os.path.dirname(__file__), 'fixtures', relapath)
+	
+def copy_files_globbed(source_glob, target_dir, hard_link_ok=False):
+	"""Copy all files found according to the given source glob into the target directory
+	:param hard_link_ok: if True, hard links will be created if possible. Otherwise 
+		the files will be copied"""
+	for src_file in glob.glob(source_glob):
+		if hard_link_ok and hasattr(os, 'link'):
+			target = os.path.join(target_dir, os.path.basename(src_file))
+			try:
+				os.link(src_file, target)
+			except OSError:
+				shutil.copy(src_file, target_dir)
+			# END handle cross device links ( and resulting failure )
+		else:
+			shutil.copy(src_file, target_dir)
+		# END try hard link
+	# END for each file to copy
+	
+
+def make_bytes(size_in_bytes, randomize=False):
+	""":return: string with given size in bytes
+	:param randomize: try to produce a very random stream"""
+	actual_size = size_in_bytes / 4
+	producer = xrange(actual_size)
+	if randomize:
+		producer = list(producer)
+		random.shuffle(producer)
+	# END randomize
+	a = array('i', producer)
+	return a.tostring()
+
+def make_object(type, data):
+	""":return: bytes resembling an uncompressed object"""
+	odata = "blob %i\0" % len(data)
+	return odata + data
+	
+def make_memory_file(size_in_bytes, randomize=False):
+	""":return: tuple(size_of_stream, stream)
+	:param randomize: try to produce a very random stream"""
+	d = make_bytes(size_in_bytes, randomize)
+	return len(d), StringIO(d)
+
+#} END routines
+
+#{ Stream Utilities
+
+class DummyStream(object):
+		def __init__(self):
+			self.was_read = False
+			self.bytes = 0
+			self.closed = False
+			
+		def read(self, size):
+			self.was_read = True
+			self.bytes = size
+			
+		def close(self):
+			self.closed = True
+			
+		def _assert(self):
+			assert self.was_read
+
+
+class DeriveTest(OStream):
+	def __init__(self, sha, type, size, stream, *args, **kwargs):
+		self.myarg = kwargs.pop('myarg')
+		self.args = args
+		
+	def _assert(self):
+		assert self.args
+		assert self.myarg
+
+#} END stream utilitiess
+
+#{ Bases
+
+class TestBase(unittest.TestCase):
+	"""Base class for all tests"""
+	# The non-database specific tests just provides a default pure git database
+	rorepo = PureGitDB(repo_dir())
+
+#} END bases
+
diff --git a/git/test/performance/test_pack.py b/git/test/performance/test_pack.py
new file mode 100644
index 00000000..da952b17
--- /dev/null
+++ b/git/test/performance/test_pack.py
@@ -0,0 +1,90 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Performance tests for object store"""
+from lib import (
+	TestBigRepoR 
+	)
+
+from gitdb.exc import UnsupportedOperation
+from gitdb.db.pack import PackedDB
+
+import sys
+import os
+from time import time
+import random
+
+class TestPackedDBPerformance(TestBigRepoR):
+	
+	def _test_pack_random_access(self):
+		pdb = PackedDB(os.path.join(self.gitrepopath, "objects/pack"))
+		
+		# sha lookup
+		st = time()
+		sha_list = list(pdb.sha_iter())
+		elapsed = time() - st
+		ns = len(sha_list)
+		print >> sys.stderr, "PDB: looked up %i shas by index in %f s ( %f shas/s )" % (ns, elapsed, ns / elapsed)
+		
+		# sha lookup: best-case and worst case access
+		pdb_pack_info = pdb._pack_info
+		# END shuffle shas
+		st = time()
+		for sha in sha_list:
+			pdb_pack_info(sha)
+		# END for each sha to look up
+		elapsed = time() - st
+		
+		# discard cache
+		del(pdb._entities)
+		pdb.entities()
+		print >> sys.stderr, "PDB: looked up %i sha in %i packs in %f s ( %f shas/s )" % (ns, len(pdb.entities()), elapsed, ns / elapsed)
+		# END for each random mode
+		
+		# query info and streams only
+		max_items = 10000			# can wait longer when testing memory
+		for pdb_fun in (pdb.info, pdb.stream):
+			st = time()
+			for sha in sha_list[:max_items]:
+				pdb_fun(sha)
+			elapsed = time() - st
+			print >> sys.stderr, "PDB: Obtained %i object %s by sha in %f s ( %f items/s )" % (max_items, pdb_fun.__name__.upper(), elapsed, max_items / elapsed)
+		# END for each function
+		
+		# retrieve stream and read all
+		max_items = 5000
+		pdb_stream = pdb.stream
+		total_size = 0
+		st = time()
+		for sha in sha_list[:max_items]:
+			stream = pdb_stream(sha)
+			stream.read()
+			total_size += stream.size
+		elapsed = time() - st
+		total_kib = total_size / 1000
+		print >> sys.stderr, "PDB: Obtained %i streams by sha and read all bytes totallying %i KiB ( %f KiB / s ) in %f s ( %f streams/s )" % (max_items, total_kib, total_kib/elapsed , elapsed, max_items / elapsed)
+		
+	def test_correctness(self):
+		pdb = PackedDB(os.path.join(self.gitrepopath, "objects/pack"))
+		# disabled for now as it used to work perfectly, checking big repositories takes a long time
+		print >> sys.stderr, "Endurance run: verify streaming of objects (crc and sha)"
+		for crc in range(2):
+			count = 0
+			st = time()
+			for entity in pdb.entities():
+				pack_verify = entity.is_valid_stream
+				sha_by_index = entity.index().sha
+				for index in xrange(entity.index().size()):
+					try:
+						assert pack_verify(sha_by_index(index), use_crc=crc)
+						count += 1
+					except UnsupportedOperation:
+						pass
+					# END ignore old indices
+				# END for each index
+			# END for each entity
+			elapsed = time() - st
+			print >> sys.stderr, "PDB: verified %i objects (crc=%i) in %f s ( %f objects/s )" % (count, crc, elapsed, count / elapsed)
+		# END for each verify mode
+		
diff --git a/git/test/performance/test_pack_streaming.py b/git/test/performance/test_pack_streaming.py
new file mode 100644
index 00000000..795ed1e2
--- /dev/null
+++ b/git/test/performance/test_pack_streaming.py
@@ -0,0 +1,80 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Specific test for pack streams only"""
+from lib import (
+	TestBigRepoR 
+	)
+
+from gitdb.db.pack import PackedDB
+from gitdb.stream import NullStream
+from gitdb.pack import PackEntity
+
+import os
+import sys
+from time import time
+from nose import SkipTest
+
+class CountedNullStream(NullStream):
+	__slots__ = '_bw'
+	def __init__(self):
+		self._bw = 0
+		
+	def bytes_written(self):
+		return self._bw
+		
+	def write(self, d):
+		self._bw += NullStream.write(self, d)
+	
+
+class TestPackStreamingPerformance(TestBigRepoR):
+	
+	def test_pack_writing(self):
+		# see how fast we can write a pack from object streams.
+		# This will not be fast, as we take time for decompressing the streams as well
+		ostream = CountedNullStream()
+		pdb = PackedDB(os.path.join(self.gitrepopath, "objects/pack"))
+		
+		ni = 5000
+		count = 0
+		total_size = 0
+		st = time()
+		objs = list()
+		for sha in pdb.sha_iter():
+			count += 1
+			objs.append(pdb.stream(sha))
+			if count == ni:
+				break
+		#END gather objects for pack-writing
+		elapsed = time() - st
+		print >> sys.stderr, "PDB Streaming: Got %i streams by sha in in %f s ( %f streams/s )" % (ni, elapsed, ni / elapsed)
+		
+		st = time()
+		PackEntity.write_pack(objs, ostream.write)
+		elapsed = time() - st
+		total_kb = ostream.bytes_written() / 1000
+		print >> sys.stderr, "PDB Streaming: Wrote pack of size %i kb in %f s (%f kb/s)" % (total_kb, elapsed, total_kb/elapsed)
+		
+	
+	def test_stream_reading(self):
+		raise SkipTest()
+		pdb = PackedDB(os.path.join(self.gitrepopath, "objects/pack"))
+		
+		# streaming only, meant for --with-profile runs
+		ni = 5000
+		count = 0
+		pdb_stream = pdb.stream
+		total_size = 0
+		st = time()
+		for sha in pdb.sha_iter():
+			if count == ni:
+				break
+			stream = pdb_stream(sha)
+			stream.read()
+			total_size += stream.size
+			count += 1
+		elapsed = time() - st
+		total_kib = total_size / 1000
+		print >> sys.stderr, "PDB Streaming: Got %i streams by sha and read all bytes totallying %i KiB ( %f KiB / s ) in %f s ( %f streams/s )" % (ni, total_kib, total_kib/elapsed , elapsed, ni / elapsed)
+		
diff --git a/git/test/performance/test_streams.py b/git/test/performance/test_streams.py
index 7f17d722..196e9003 100644
--- a/git/test/performance/test_streams.py
+++ b/git/test/performance/test_streams.py
@@ -1,9 +1,17 @@
 """Performance data streaming performance"""
+from gitdb.db.py import *
+from gitdb.base import *
+from gitdb.stream import *
+from gitdb.util import (
+							pool,
+							bin_to_hex
+						)
 
 from git.test.lib import *
 from gitdb import *
 from gitdb.util import bin_to_hex
 
+from cStringIO import StringIO
 from time import time
 import os
 import sys
@@ -14,9 +22,35 @@ from gitdb.test.lib import make_memory_file
 
 from lib import (
 	TestBigRepoR
+	make_memory_file,
+	with_rw_directory
 	)
 
 
+#{ Utilities
+def read_chunked_stream(stream):
+	total = 0
+	while True:
+		chunk = stream.read(chunk_size)
+		total += len(chunk)
+		if len(chunk) < chunk_size:
+			break
+	# END read stream loop
+	assert total == stream.size
+	return stream
+	
+	
+class TestStreamReader(ChannelThreadTask):
+	"""Expects input streams and reads them in chunks. It will read one at a time, 
+	requireing a queue chunk of size 1"""
+	def __init__(self, *args):
+		super(TestStreamReader, self).__init__(*args)
+		self.fun = read_chunked_stream
+		self.max_chunksize = 1
+	
+
+#} END utilities
+
 class TestObjDBPerformance(TestBigRepoR):
 	
 	large_data_size_bytes = 1000*1000*10		# some MiB should do it
@@ -129,3 +163,134 @@ class TestObjDBPerformance(TestBigRepoR):
 			# compare 
 			print >> sys.stderr, "Git-Python is %f %% faster than git when reading big %s files in chunks" % (100.0 - (elapsed_readchunks / gelapsed_readchunks) * 100, desc)
 		# END for each randomization factor
+		
+	@with_rw_directory
+	def test_large_data_streaming(self, path):
+		ldb = PureLooseObjectODB(path)
+		string_ios = list()			# list of streams we previously created
+		
+		# serial mode 
+		for randomize in range(2):
+			desc = (randomize and 'random ') or ''
+			print >> sys.stderr, "Creating %s data ..." % desc
+			st = time()
+			size, stream = make_memory_file(self.large_data_size_bytes, randomize)
+			elapsed = time() - st
+			print >> sys.stderr, "Done (in %f s)" % elapsed
+			string_ios.append(stream)
+			
+			# writing - due to the compression it will seem faster than it is 
+			st = time()
+			sha = ldb.store(IStream('blob', size, stream)).binsha
+			elapsed_add = time() - st
+			assert ldb.has_object(sha)
+			db_file = ldb.readable_db_object_path(bin_to_hex(sha))
+			fsize_kib = os.path.getsize(db_file) / 1000
+			
+			
+			size_kib = size / 1000
+			print >> sys.stderr, "Added %i KiB (filesize = %i KiB) of %s data to loose odb in %f s ( %f Write KiB / s)" % (size_kib, fsize_kib, desc, elapsed_add, size_kib / elapsed_add)
+			
+			# reading all at once
+			st = time()
+			ostream = ldb.stream(sha)
+			shadata = ostream.read()
+			elapsed_readall = time() - st
+			
+			stream.seek(0)
+			assert shadata == stream.getvalue()
+			print >> sys.stderr, "Read %i KiB of %s data at once from loose odb in %f s ( %f Read KiB / s)" % (size_kib, desc, elapsed_readall, size_kib / elapsed_readall)
+			
+			
+			# reading in chunks of 1 MiB
+			cs = 512*1000
+			chunks = list()
+			st = time()
+			ostream = ldb.stream(sha)
+			while True:
+				data = ostream.read(cs)
+				chunks.append(data)
+				if len(data) < cs:
+					break
+			# END read in chunks
+			elapsed_readchunks = time() - st
+			
+			stream.seek(0)
+			assert ''.join(chunks) == stream.getvalue()
+			
+			cs_kib = cs / 1000
+			print >> sys.stderr, "Read %i KiB of %s data in %i KiB chunks from loose odb in %f s ( %f Read KiB / s)" % (size_kib, desc, cs_kib, elapsed_readchunks, size_kib / elapsed_readchunks)
+			
+			# del db file so we keep something to do
+			os.remove(db_file)
+		# END for each randomization factor
+		
+		
+		# multi-threaded mode
+		# want two, should be supported by most of todays cpus
+		pool.set_size(2)
+		total_kib = 0
+		nsios = len(string_ios)
+		for stream in string_ios:
+			stream.seek(0)
+			total_kib += len(stream.getvalue()) / 1000
+		# END rewind
+		
+		def istream_iter():
+			for stream in string_ios:
+				stream.seek(0)
+				yield IStream(str_blob_type, len(stream.getvalue()), stream)
+			# END for each stream
+		# END util
+		
+		# write multiple objects at once, involving concurrent compression
+		reader = IteratorReader(istream_iter())
+		istream_reader = ldb.store_async(reader)
+		istream_reader.task().max_chunksize = 1
+		
+		st = time()
+		istreams = istream_reader.read(nsios)
+		assert len(istreams) == nsios
+		elapsed = time() - st
+		
+		print >> sys.stderr, "Threads(%i): Compressed %i KiB of data in loose odb in %f s ( %f Write KiB / s)" % (pool.size(), total_kib, elapsed, total_kib / elapsed)
+		
+		# decompress multiple at once, by reading them
+		# chunk size is not important as the stream will not really be decompressed
+		
+		# until its read
+		istream_reader = IteratorReader(iter([ i.binsha for i in istreams ]))
+		ostream_reader = ldb.stream_async(istream_reader)
+		
+		chunk_task = TestStreamReader(ostream_reader, "chunker", None)
+		output_reader = pool.add_task(chunk_task)
+		output_reader.task().max_chunksize = 1
+		
+		st = time()
+		assert len(output_reader.read(nsios)) == nsios
+		elapsed = time() - st
+		
+		print >> sys.stderr, "Threads(%i): Decompressed %i KiB of data in loose odb in %f s ( %f Read KiB / s)" % (pool.size(), total_kib, elapsed, total_kib / elapsed)
+		
+		# store the files, and read them back. For the reading, we use a task 
+		# as well which is chunked into one item per task. Reading all will
+		# very quickly result in two threads handling two bytestreams of 
+		# chained compression/decompression streams
+		reader = IteratorReader(istream_iter())
+		istream_reader = ldb.store_async(reader)
+		istream_reader.task().max_chunksize = 1
+		
+		istream_to_sha = lambda items: [ i.binsha for i in items ]
+		istream_reader.set_post_cb(istream_to_sha)
+		
+		ostream_reader = ldb.stream_async(istream_reader)
+		
+		chunk_task = TestStreamReader(ostream_reader, "chunker", None)
+		output_reader = pool.add_task(chunk_task)
+		output_reader.max_chunksize = 1
+		
+		st = time()
+		assert len(output_reader.read(nsios)) == nsios
+		elapsed = time() - st
+		
+		print >> sys.stderr, "Threads(%i): Compressed and decompressed and read %i KiB of data in loose odb in %f s ( %f Combined KiB / s)" % (pool.size(), total_kib, elapsed, total_kib / elapsed)
diff --git a/git/test/test_base.py b/git/test/test_base.py
index e630d151..408b9833 100644
--- a/git/test/test_base.py
+++ b/git/test/test_base.py
@@ -15,6 +15,22 @@ from git.objects.util import get_object_type_by_name
 from gitdb.util import hex_to_bin
 import tempfile
 
+##################
+from lib import (
+		TestBase,
+		DummyStream,
+		DeriveTest, 
+	)
+
+from gitdb import *
+from gitdb.util import (
+	NULL_BIN_SHA
+	)
+
+from gitdb.typ import (
+	str_blob_type
+	)
+
 class TestBase(TestBase):
 	
 	type_tuples = (	 ("blob", "8741fc1d09d61f02ffd8cded15ff603eff1ec070", "blob.py"), 
@@ -98,3 +114,85 @@ class TestBase(TestBase):
 		assert not rw_repo.config_reader("repository").getboolean("core", "bare")
 		assert rw_remote_repo.config_reader("repository").getboolean("core", "bare")
 		assert os.path.isdir(os.path.join(rw_repo.working_tree_dir,'lib'))
+		
+		
+
+class TestBaseTypes(TestBase):
+	
+	def test_streams(self):
+		# test info
+		sha = NULL_BIN_SHA
+		s = 20
+		blob_id = 3
+		
+		info = OInfo(sha, str_blob_type, s)
+		assert info.binsha == sha
+		assert info.type == str_blob_type
+		assert info.type_id == blob_id
+		assert info.size == s
+		
+		# test pack info
+		# provides type_id
+		pinfo = OPackInfo(0, blob_id, s)
+		assert pinfo.type == str_blob_type
+		assert pinfo.type_id == blob_id
+		assert pinfo.pack_offset == 0
+		
+		dpinfo = ODeltaPackInfo(0, blob_id, s, sha)
+		assert dpinfo.type == str_blob_type
+		assert dpinfo.type_id == blob_id
+		assert dpinfo.delta_info == sha
+		assert dpinfo.pack_offset == 0
+		
+		
+		# test ostream
+		stream = DummyStream()
+		ostream = OStream(*(info + (stream, )))
+		assert ostream.stream is stream
+		ostream.read(15)
+		stream._assert()
+		assert stream.bytes == 15
+		ostream.read(20)
+		assert stream.bytes == 20
+		
+		# test packstream
+		postream = OPackStream(*(pinfo + (stream, )))
+		assert postream.stream is stream
+		postream.read(10)
+		stream._assert()
+		assert stream.bytes == 10
+		
+		# test deltapackstream
+		dpostream = ODeltaPackStream(*(dpinfo + (stream, )))
+		dpostream.stream is stream
+		dpostream.read(5)
+		stream._assert()
+		assert stream.bytes == 5
+		
+		# derive with own args
+		DeriveTest(sha, str_blob_type, s, stream, 'mine',myarg = 3)._assert()
+		
+		# test istream
+		istream = IStream(str_blob_type, s, stream)
+		assert istream.binsha == None
+		istream.binsha = sha
+		assert istream.binsha == sha
+		
+		assert len(istream.binsha) == 20
+		assert len(istream.hexsha) == 40
+		
+		assert istream.size == s
+		istream.size = s * 2
+		istream.size == s * 2
+		assert istream.type == str_blob_type
+		istream.type = "something"
+		assert istream.type == "something"
+		assert istream.stream is stream
+		istream.stream = None
+		assert istream.stream is None
+		
+		assert istream.error is None
+		istream.error = Exception()
+		assert isinstance(istream.error, Exception)
+
+
diff --git a/git/test/test_example.py b/git/test/test_example.py
new file mode 100644
index 00000000..c2e78407
--- /dev/null
+++ b/git/test/test_example.py
@@ -0,0 +1,64 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Module with examples from the tutorial section of the docs"""
+from lib import *
+from gitdb import IStream
+from gitdb.db.py import PureLooseObjectODB
+from gitdb.util import pool
+		
+from cStringIO import StringIO
+
+from async import IteratorReader
+		
+class TestExamples(TestBase):
+	
+	def test_base(self):
+		ldb = PureLooseObjectODB(fixture_path("../../../.git/objects"))
+		
+		for sha1 in ldb.sha_iter():
+			oinfo = ldb.info(sha1)
+			ostream = ldb.stream(sha1)
+			assert oinfo[:3] == ostream[:3]
+			
+			assert len(ostream.read()) == ostream.size
+			assert ldb.has_object(oinfo.binsha)
+		# END for each sha in database
+		# assure we close all files
+		try:
+			del(ostream)
+			del(oinfo)
+		except UnboundLocalError:
+			pass
+		# END ignore exception if there are no loose objects
+			
+		data = "my data"
+		istream = IStream("blob", len(data), StringIO(data))
+		
+		# the object does not yet have a sha
+		assert istream.binsha is None
+		ldb.store(istream)
+		# now the sha is set
+		assert len(istream.binsha) == 20
+		assert ldb.has_object(istream.binsha)
+		
+		
+		# async operation
+		# Create a reader from an iterator
+		reader = IteratorReader(ldb.sha_iter())
+		
+		# get reader for object streams
+		info_reader = ldb.stream_async(reader)
+		
+		# read one
+		info = info_reader.read(1)[0]
+		
+		# read all the rest until depletion
+		ostreams = info_reader.read()
+		
+		# set the pool to use two threads
+		pool.set_size(2)
+		
+		# synchronize the mode of operation
+		pool.set_size(0)
diff --git a/git/test/test_pack.py b/git/test/test_pack.py
new file mode 100644
index 00000000..4a7f1caf
--- /dev/null
+++ b/git/test/test_pack.py
@@ -0,0 +1,247 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Test everything about packs reading and writing"""
+from lib import (
+					TestBase,
+					with_rw_directory, 
+					with_packs_rw,
+					fixture_path
+				)
+from gitdb.stream import DeltaApplyReader
+
+from gitdb.pack import (
+							PackEntity,
+							PackIndexFile,
+							PackFile
+						)
+
+from gitdb.base import (
+							OInfo, 
+							OStream,
+						)
+
+from gitdb.fun import delta_types
+from gitdb.exc import UnsupportedOperation
+from gitdb.util import to_bin_sha
+from itertools import izip, chain
+from nose import SkipTest
+
+import os
+import sys
+import tempfile
+
+
+#{ Utilities
+def bin_sha_from_filename(filename):
+	return to_bin_sha(os.path.splitext(os.path.basename(filename))[0][5:])
+#} END utilities
+
+class TestPack(TestBase):
+	
+	packindexfile_v1 = (fixture_path('packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.idx'), 1, 67)
+	packindexfile_v2 = (fixture_path('packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.idx'), 2, 30)
+	packindexfile_v2_3_ascii = (fixture_path('packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.idx'), 2, 42)
+	packfile_v2_1 = (fixture_path('packs/pack-c0438c19fb16422b6bbcce24387b3264416d485b.pack'), 2, packindexfile_v1[2])
+	packfile_v2_2 = (fixture_path('packs/pack-11fdfa9e156ab73caae3b6da867192221f2089c2.pack'), 2, packindexfile_v2[2])
+	packfile_v2_3_ascii = (fixture_path('packs/pack-a2bf8e71d8c18879e499335762dd95119d93d9f1.pack'), 2, packindexfile_v2_3_ascii[2])
+	
+	
+	def _assert_index_file(self, index, version, size):
+		assert index.packfile_checksum() != index.indexfile_checksum()
+		assert len(index.packfile_checksum()) == 20
+		assert len(index.indexfile_checksum()) == 20
+		assert index.version() == version
+		assert index.size() == size
+		assert len(index.offsets()) == size
+		
+		# get all data of all objects
+		for oidx in xrange(index.size()):
+			sha = index.sha(oidx)
+			assert oidx == index.sha_to_index(sha)
+			
+			entry = index.entry(oidx)
+			assert len(entry) == 3
+			
+			assert entry[0] == index.offset(oidx)
+			assert entry[1] == sha
+			assert entry[2] == index.crc(oidx)
+			
+			# verify partial sha
+			for l in (4,8,11,17,20):
+				assert index.partial_sha_to_index(sha[:l], l*2) == oidx
+			
+		# END for each object index in indexfile
+		self.failUnlessRaises(ValueError, index.partial_sha_to_index, "\0", 2)
+		
+		
+	def _assert_pack_file(self, pack, version, size):
+		assert pack.version() == 2
+		assert pack.size() == size
+		assert len(pack.checksum()) == 20
+		
+		num_obj = 0
+		for obj in pack.stream_iter():
+			num_obj += 1
+			info = pack.info(obj.pack_offset)
+			stream = pack.stream(obj.pack_offset)
+			
+			assert info.pack_offset == stream.pack_offset
+			assert info.type_id == stream.type_id
+			assert hasattr(stream, 'read')
+			
+			# it should be possible to read from both streams
+			assert obj.read() == stream.read()
+			
+			streams = pack.collect_streams(obj.pack_offset)
+			assert streams
+			
+			# read the stream
+			try:
+				dstream = DeltaApplyReader.new(streams)
+			except ValueError:
+				# ignore these, old git versions use only ref deltas, 
+				# which we havent resolved ( as we are without an index )
+				# Also ignore non-delta streams
+				continue
+			# END get deltastream
+			
+			# read all
+			data = dstream.read()
+			assert len(data) == dstream.size
+			
+			# test seek
+			dstream.seek(0)
+			assert dstream.read() == data
+			
+			
+			# read chunks
+			# NOTE: the current implementation is safe, it basically transfers
+			# all calls to the underlying memory map
+			
+		# END for each object
+		assert num_obj == size
+		
+	
+	def test_pack_index(self):
+		# check version 1 and 2
+		for indexfile, version, size in (self.packindexfile_v1, self.packindexfile_v2): 
+			index = PackIndexFile(indexfile)
+			self._assert_index_file(index, version, size)
+		# END run tests
+		
+	def test_pack(self):
+		# there is this special version 3, but apparently its like 2 ... 
+		for packfile, version, size in (self.packfile_v2_3_ascii, self.packfile_v2_1, self.packfile_v2_2):
+			pack = PackFile(packfile)
+			self._assert_pack_file(pack, version, size)
+		# END for each pack to test
+		
+	@with_rw_directory
+	def test_pack_entity(self, rw_dir):
+		pack_objs = list()
+		for packinfo, indexinfo in (	(self.packfile_v2_1, self.packindexfile_v1), 
+										(self.packfile_v2_2, self.packindexfile_v2),
+										(self.packfile_v2_3_ascii, self.packindexfile_v2_3_ascii)):
+			packfile, version, size = packinfo
+			indexfile, version, size = indexinfo
+			entity = PackEntity(packfile)
+			assert entity.pack().path() == packfile
+			assert entity.index().path() == indexfile
+			pack_objs.extend(entity.stream_iter())
+			
+			count = 0
+			for info, stream in izip(entity.info_iter(), entity.stream_iter()):
+				count += 1
+				assert info.binsha == stream.binsha
+				assert len(info.binsha) == 20
+				assert info.type_id == stream.type_id
+				assert info.size == stream.size
+				
+				# we return fully resolved items, which is implied by the sha centric access
+				assert not info.type_id in delta_types
+				
+				# try all calls
+				assert len(entity.collect_streams(info.binsha))
+				oinfo = entity.info(info.binsha)
+				assert isinstance(oinfo, OInfo)
+				assert oinfo.binsha is not None
+				ostream = entity.stream(info.binsha)
+				assert isinstance(ostream, OStream)
+				assert ostream.binsha is not None
+				
+				# verify the stream
+				try:
+					assert entity.is_valid_stream(info.binsha, use_crc=True)
+				except UnsupportedOperation:
+					pass
+				# END ignore version issues
+				assert entity.is_valid_stream(info.binsha, use_crc=False)
+			# END for each info, stream tuple
+			assert count == size
+			
+		# END for each entity
+		
+		# pack writing - write all packs into one
+		# index path can be None
+		pack_path = tempfile.mktemp('', "pack", rw_dir)
+		index_path = tempfile.mktemp('', 'index', rw_dir)
+		iteration = 0
+		def rewind_streams():
+			for obj in pack_objs: 
+				obj.stream.seek(0)
+		#END utility
+		for ppath, ipath, num_obj in zip((pack_path, )*2, (index_path, None), (len(pack_objs), None)):
+			pfile = open(ppath, 'wb')
+			iwrite = None
+			if ipath:
+				ifile = open(ipath, 'wb')
+				iwrite = ifile.write
+			#END handle ip
+			
+			# make sure we rewind the streams ... we work on the same objects over and over again
+			if iteration > 0: 
+				rewind_streams()
+			#END rewind streams
+			iteration += 1
+			
+			pack_sha, index_sha = PackEntity.write_pack(pack_objs, pfile.write, iwrite, object_count=num_obj)
+			pfile.close()
+			assert os.path.getsize(ppath) > 100
+			
+			# verify pack
+			pf = PackFile(ppath)
+			assert pf.size() == len(pack_objs)
+			assert pf.version() == PackFile.pack_version_default
+			assert pf.checksum() == pack_sha
+			
+			# verify index
+			if ipath is not None:
+				ifile.close()
+				assert os.path.getsize(ipath) > 100
+				idx = PackIndexFile(ipath)
+				assert idx.version() == PackIndexFile.index_version_default
+				assert idx.packfile_checksum() == pack_sha
+				assert idx.indexfile_checksum() == index_sha
+				assert idx.size() == len(pack_objs)
+			#END verify files exist
+		#END for each packpath, indexpath pair
+		
+		# verify the packs throughly
+		rewind_streams()
+		entity = PackEntity.create(pack_objs, rw_dir)
+		count = 0
+		for info in entity.info_iter():
+			count += 1
+			for use_crc in range(2):
+				assert entity.is_valid_stream(info.binsha, use_crc)
+			# END for each crc mode
+		#END for each info
+		assert count == len(pack_objs)
+		 
+		
+	def test_pack_64(self):
+		# TODO: hex-edit a pack helping us to verify that we can handle 64 byte offsets
+		# of course without really needing such a huge pack 
+		raise SkipTest()
diff --git a/git/test/test_refs.py b/git/test/test_refs.py
index 2338b4e4..649542f3 100644
--- a/git/test/test_refs.py
+++ b/git/test/test_refs.py
@@ -4,12 +4,13 @@
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 
-from mock import *
-from git.test.lib import *
-from git import *
-import git.refs as refs
-from git.util import Actor
-from git.objects.tag import TagObject
+from gitdb.test.lib import *
+from gitdb.ref import *
+import gitdb.ref as ref
+
+from gitdb.util import Actor
+from gitdb.object.tag import TagObject
+
 from itertools import chain
 import os
 
@@ -17,7 +18,7 @@ class TestRefs(TestBase):
 
 	def test_from_path(self):
 		# should be able to create any reference directly
-		for ref_type in ( Reference, Head, TagReference, RemoteReference ):
+		for ref_type in (Reference, Head, TagReference, RemoteReference):
 			for name in ('rela_name', 'path/rela_name'):
 				full_path = ref_type.to_full_path(name)
 				instance = ref_type.from_path(self.rorepo, full_path)
@@ -27,20 +28,20 @@ class TestRefs(TestBase):
 	
 	def test_tag_base(self):
 		tag_object_refs = list()
-		for tag in self.rorepo.tags:
+		for tag in TagReference.list_items(self.rorepo):
 			assert "refs/tags" in tag.path
 			assert tag.name
-			assert isinstance( tag.commit, Commit )
+			assert isinstance(tag.commit, tag.CommitCls)
 			if tag.tag is not None:
-				tag_object_refs.append( tag )
+				tag_object_refs.append(tag)
 				tagobj = tag.tag
 				# have no dict
 				self.failUnlessRaises(AttributeError, setattr, tagobj, 'someattr', 1)
-				assert isinstance( tagobj, TagObject ) 
+				assert isinstance(tagobj, TagObject) 
 				assert tagobj.tag == tag.name
-				assert isinstance( tagobj.tagger, Actor )
-				assert isinstance( tagobj.tagged_date, int )
-				assert isinstance( tagobj.tagger_tz_offset, int )
+				assert isinstance(tagobj.tagger, Actor)
+				assert isinstance(tagobj.tagged_date, int)
+				assert isinstance(tagobj.tagger_tz_offset, int)
 				assert tagobj.message
 				assert tag.object == tagobj
 				# can't assign the object
@@ -48,15 +49,15 @@ class TestRefs(TestBase):
 			# END if we have a tag object
 		# END for tag in repo-tags
 		assert tag_object_refs
-		assert isinstance(self.rorepo.tags['0.1.5'], TagReference)
+		assert isinstance(TagReference.list_items(self.rorepo)['0.5.0'], TagReference)
 		
 	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):
+		for ref in chain(TagReference.list_items(self.rorepo), Head.list_items(self.rorepo)):
 			ref_count += 1
-			assert isinstance(ref, refs.Reference)
+			assert isinstance(ref, Reference)
 			assert str(ref) == ref.name
 			assert repr(ref)
 			assert ref == ref
@@ -66,9 +67,9 @@ class TestRefs(TestBase):
 		assert len(s) == ref_count
 		assert len(s|s) == ref_count
 		
-	@with_rw_repo('HEAD', bare=False)
-	def test_heads(self, rwrepo):
-		for head in rwrepo.heads:
+	@with_rw_repo
+	def test_heads(self, rw_repo):
+		for head in Head.iter_items(rw_repo):
 			assert head.name
 			assert head.path
 			assert "refs/heads" in head.path
@@ -88,7 +89,7 @@ class TestRefs(TestBase):
 			# after the clone, we might still have a tracking branch setup
 			head.set_tracking_branch(None)
 			assert head.tracking_branch() is None
- 			remote_ref = rwrepo.remotes[0].refs[0]
+ 			remote_ref = RemoteReference.list_items(rw_repo)[0]
 			assert head.set_tracking_branch(remote_ref) is head
 			assert head.tracking_branch() == remote_ref
 			head.set_tracking_branch(None)
@@ -96,7 +97,7 @@ class TestRefs(TestBase):
 		# END for each head
 		
 		# verify REFLOG gets altered
-		head = rwrepo.head
+		head = HEAD(rw_repo)
 		cur_head = head.ref
 		cur_commit = cur_head.commit
 		pcommit = cur_head.commit.parents[0].parents[0]
@@ -130,7 +131,7 @@ class TestRefs(TestBase):
 		assert len(cur_head.log()) == blog_len+2
 		
 		# a new branch has just a single entry
-		other_head = Head.create(rwrepo, 'mynewhead', pcommit, logmsg='new head created')
+		other_head = Head.create(rw_repo, 'mynewhead', pcommit, logmsg='new head created')
 		log = other_head.log()
 		assert len(log) == 1
 		assert log[0].oldhexsha == pcommit.NULL_HEX_SHA
@@ -139,24 +140,25 @@ class TestRefs(TestBase):
 		
 	def test_refs(self):
 		types_found = set()
-		for ref in self.rorepo.refs:
+		for ref in Reference.list_items(self.rorepo):
 			types_found.add(type(ref))
 		assert len(types_found) >= 3 
 		
 	def test_is_valid(self):
 		assert Reference(self.rorepo, 'refs/doesnt/exist').is_valid() == False
-		assert self.rorepo.head.is_valid()
-		assert self.rorepo.head.reference.is_valid()
+		assert HEAD(self.rorepo).is_valid()
+		assert HEAD(self.rorepo).reference.is_valid()
 		assert SymbolicReference(self.rorepo, 'hellothere').is_valid() == False
 		
 	def test_orig_head(self):
-		assert type(self.rorepo.head.orig_head()) == SymbolicReference
+		assert type(HEAD(self.rorepo).orig_head()) == SymbolicReference
 		
-	@with_rw_repo('0.1.6')
+	@with_rw_repo
 	def test_head_reset(self, rw_repo):
-		cur_head = rw_repo.head
+		cur_head = HEAD(rw_repo)
 		old_head_commit = cur_head.commit
 		new_head_commit = cur_head.ref.commit.parents[0]
+		
 		cur_head.reset(new_head_commit, index=True) # index only
 		assert cur_head.reference.commit == new_head_commit
 		
@@ -176,10 +178,9 @@ class TestRefs(TestBase):
 		cur_head.reset(new_head_commit)
 		rw_repo.index.checkout(["lib"], force=True)#
 		
-		
 		# now that we have a write write repo, change the HEAD reference - its 
 		# like git-reset --soft
-		heads = rw_repo.heads
+		heads = Head.list_items(rw_repo)
 		assert heads
 		for head in heads:
 			cur_head.reference = head
@@ -198,7 +199,7 @@ class TestRefs(TestBase):
 		self.failUnlessRaises(TypeError, getattr, cur_head, "reference")
 		
 		# tags are references, hence we can point to them
-		some_tag = rw_repo.tags[0]
+		some_tag = TagReference.list_items(rw_repo)[0]
 		cur_head.reference = some_tag
 		assert not cur_head.is_detached
 		assert cur_head.commit == some_tag.commit
@@ -231,7 +232,7 @@ class TestRefs(TestBase):
 			old_name = new_head.name
 			
 			assert new_head.rename("hello").name == "hello"
-			assert new_head.rename("hello/world").name == "hello/world"
+			assert new_head.rename("hello/world").name == "hello/world"	# yes, this must work
 			assert new_head.rename(old_name).name == old_name and new_head.path == old_path
 			
 			# rename with force
@@ -414,7 +415,7 @@ class TestRefs(TestBase):
 		symbol_ref_path = "refs/symbol_ref"
 		symref = SymbolicReference(rw_repo, symbol_ref_path)
 		assert symref.path == symbol_ref_path
-		symbol_ref_abspath = os.path.join(rw_repo.git_dir, symref.path)
+		symbol_ref_abspath = os.path.join(rw_repo.root_path(), symref.path)
 		
 		# set it
 		symref.reference = new_head
@@ -471,7 +472,7 @@ class TestRefs(TestBase):
 		rw_repo.head.reference = Head.create(rw_repo, "master")
 		
 		# At least the head should still exist
-		assert os.path.isfile(os.path.join(rw_repo.git_dir, 'HEAD'))
+		assert os.path.isfile(os.path.join(rw_repo.root_path(), 'HEAD'))
 		refs = list(SymbolicReference.iter_items(rw_repo))
 		assert len(refs) == 1
 		
@@ -517,5 +518,5 @@ class TestRefs(TestBase):
 		assert SymbolicReference.dereference_recursive(self.rorepo, 'HEAD')
 		
 	def test_reflog(self):
-		assert isinstance(self.rorepo.heads.master.log(), RefLog)
+		assert isinstance(Head.list_items(self.rorepo).master.log(), RefLog)
 		
diff --git a/git/test/test_stream.py b/git/test/test_stream.py
new file mode 100644
index 00000000..b2d4bc14
--- /dev/null
+++ b/git/test/test_stream.py
@@ -0,0 +1,155 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Test for object db"""
+from lib import (
+		TestBase,
+		DummyStream,
+		Sha1Writer, 
+		make_bytes, 
+		make_object,
+		fixture_path
+	)
+
+from gitdb import *
+from gitdb.util import (
+	NULL_HEX_SHA,
+	hex_to_bin
+	)
+
+from gitdb.util import zlib
+from gitdb.typ import (
+	str_blob_type
+	)
+
+from gitdb.db.py import PureLooseObjectODB
+import time
+import tempfile
+import os
+
+
+
+
+class TestStream(TestBase):
+	"""Test stream classes"""
+	
+	data_sizes = (15, 10000, 1000*1024+512)
+		
+	def _assert_stream_reader(self, stream, cdata, rewind_stream=lambda s: None):
+		"""Make stream tests - the orig_stream is seekable, allowing it to be 
+		rewound and reused
+		:param cdata: the data we expect to read from stream, the contents
+		:param rewind_stream: function called to rewind the stream to make it ready
+			for reuse"""
+		ns = 10
+		assert len(cdata) > ns-1, "Data must be larger than %i, was %i" % (ns, len(cdata))
+		
+		# read in small steps
+		ss = len(cdata) / ns
+		for i in range(ns):
+			data = stream.read(ss)
+			chunk = cdata[i*ss:(i+1)*ss]
+			assert data == chunk
+		# END for each step
+		rest = stream.read()
+		if rest:
+			assert rest == cdata[-len(rest):]
+		# END handle rest
+		
+		if isinstance(stream, DecompressMemMapReader):
+			assert len(stream.data()) == stream.compressed_bytes_read()
+		# END handle special type
+		
+		rewind_stream(stream)
+		
+		# read everything
+		rdata = stream.read()
+		assert rdata == cdata
+		
+		if isinstance(stream, DecompressMemMapReader):
+			assert len(stream.data()) == stream.compressed_bytes_read()
+		# END handle special type
+		
+	def test_decompress_reader(self):
+		for close_on_deletion in range(2):
+			for with_size in range(2):
+				for ds in self.data_sizes:
+					cdata = make_bytes(ds, randomize=False)
+					
+					# zdata = zipped actual data
+					# cdata = original content data
+					
+					# create reader
+					if with_size:
+						# need object data
+						zdata = zlib.compress(make_object(str_blob_type, cdata))
+						type, size, reader = DecompressMemMapReader.new(zdata, close_on_deletion)
+						assert size == len(cdata)
+						assert type == str_blob_type
+						
+						# even if we don't set the size, it will be set automatically on first read
+						test_reader = DecompressMemMapReader(zdata, close_on_deletion=False)
+						assert test_reader._s == len(cdata)
+					else:
+						# here we need content data
+						zdata = zlib.compress(cdata)
+						reader = DecompressMemMapReader(zdata, close_on_deletion, len(cdata))
+						assert reader._s == len(cdata)
+					# END get reader 
+					
+					self._assert_stream_reader(reader, cdata, lambda r: r.seek(0))
+					
+					# put in a dummy stream for closing
+					dummy = DummyStream()
+					reader._m = dummy
+					
+					assert not dummy.closed
+					del(reader)
+					assert dummy.closed == close_on_deletion
+				# END for each datasize
+			# END whether size should be used
+		# END whether stream should be closed when deleted
+		
+	def test_sha_writer(self):
+		writer = Sha1Writer()
+		assert 2 == writer.write("hi")
+		assert len(writer.sha(as_hex=1)) == 40
+		assert len(writer.sha(as_hex=0)) == 20
+		
+		# make sure it does something ;)
+		prev_sha = writer.sha()
+		writer.write("hi again")
+		assert writer.sha() != prev_sha
+		
+	def test_compressed_writer(self):
+		for ds in self.data_sizes:
+			fd, path = tempfile.mkstemp()
+			ostream = FDCompressedSha1Writer(fd)
+			data = make_bytes(ds, randomize=False)
+			
+			# for now, just a single write, code doesn't care about chunking
+			assert len(data) == ostream.write(data)
+			ostream.close()
+		
+			# its closed already
+			self.failUnlessRaises(OSError, os.close, fd)
+			
+			# read everything back, compare to data we zip
+			fd = os.open(path, os.O_RDONLY|getattr(os, 'O_BINARY', 0))
+			written_data = os.read(fd, os.path.getsize(path))
+			assert len(written_data) == os.path.getsize(path)
+			os.close(fd)
+			assert written_data == zlib.compress(data, 1)	# best speed
+			
+			os.remove(path)
+		# END for each os
+	
+	def test_decompress_reader_special_case(self):
+		odb = PureLooseObjectODB(fixture_path('objects'))
+		ostream = odb.stream(hex_to_bin('7bb839852ed5e3a069966281bb08d50012fb309b'))
+		
+		# if there is a bug, we will be missing one byte exactly !
+		data = ostream.read()
+		assert len(data) == ostream.size
+		
diff --git a/git/test/test_util.py b/git/test/test_util.py
index e55a6d15..151fe5bc 100644
--- a/git/test/test_util.py
+++ b/git/test/test_util.py
@@ -7,7 +7,7 @@
 import os
 import tempfile
 
-from git.test.lib import *
+from lib import TestBase
 from git.util import *
 from git.objects.util import *
 from git import *
@@ -15,6 +15,14 @@ from git.cmd import dashify
 
 import time
 
+from gitdb.util import (
+	to_hex_sha, 
+	to_bin_sha, 
+	NULL_HEX_SHA, 
+	LockedFD, 
+	Actor
+	)
+
 
 class TestUtils(TestBase):
 	def setup(self):
@@ -107,3 +115,118 @@ class TestUtils(TestBase):
 			assert isinstance(Actor.committer(cr), Actor)
 			assert isinstance(Actor.author(cr), Actor)
 		#END assure config reader is handled
+		
+	def test_basics(self):
+		assert to_hex_sha(NULL_HEX_SHA) == NULL_HEX_SHA
+		assert len(to_bin_sha(NULL_HEX_SHA)) == 20
+		assert to_hex_sha(to_bin_sha(NULL_HEX_SHA)) == NULL_HEX_SHA
+		
+	def _cmp_contents(self, file_path, data):
+		# raise if data from file at file_path 
+		# does not match data string
+		fp = open(file_path, "rb")
+		try:
+			assert fp.read() == data
+		finally:
+			fp.close()
+		
+	def test_lockedfd(self):
+		my_file = tempfile.mktemp()
+		orig_data = "hello"
+		new_data = "world"
+		my_file_fp = open(my_file, "wb")
+		my_file_fp.write(orig_data)
+		my_file_fp.close()
+		
+		try:
+			lfd = LockedFD(my_file)
+			lockfilepath = lfd._lockfilepath() 
+			
+			# cannot end before it was started
+			self.failUnlessRaises(AssertionError, lfd.rollback)
+			self.failUnlessRaises(AssertionError, lfd.commit)
+			
+			# open for writing
+			assert not os.path.isfile(lockfilepath)
+			wfd = lfd.open(write=True)
+			assert lfd._fd is wfd
+			assert os.path.isfile(lockfilepath)
+			
+			# write data and fail
+			os.write(wfd, new_data)
+			lfd.rollback()
+			assert lfd._fd is None
+			self._cmp_contents(my_file, orig_data)
+			assert not os.path.isfile(lockfilepath)
+			
+			# additional call doesnt fail
+			lfd.commit()
+			lfd.rollback()
+			
+			# test reading
+			lfd = LockedFD(my_file)
+			rfd = lfd.open(write=False)
+			assert os.read(rfd, len(orig_data)) == orig_data
+			
+			assert os.path.isfile(lockfilepath)
+			# deletion rolls back
+			del(lfd)
+			assert not os.path.isfile(lockfilepath)
+			
+			
+			# write data - concurrently
+			lfd = LockedFD(my_file)
+			olfd = LockedFD(my_file)
+			assert not os.path.isfile(lockfilepath)
+			wfdstream = lfd.open(write=True, stream=True)		# this time as stream
+			assert os.path.isfile(lockfilepath)
+			# another one fails
+			self.failUnlessRaises(IOError, olfd.open)
+			
+			wfdstream.write(new_data)
+			lfd.commit()
+			assert not os.path.isfile(lockfilepath)
+			self._cmp_contents(my_file, new_data)
+			
+			# could test automatic _end_writing on destruction
+		finally:
+			os.remove(my_file)
+		# END final cleanup
+		
+		# try non-existing file for reading
+		lfd = LockedFD(tempfile.mktemp())
+		try:
+			lfd.open(write=False)
+		except OSError:
+			assert not os.path.exists(lfd._lockfilepath())
+		else:
+			self.fail("expected OSError")
+		# END handle exceptions
+
+
+class TestActor(TestBase):
+    def test_from_string_should_separate_name_and_email(self):
+        a = Actor._from_string("Michael Trier <mtrier@example.com>")
+        assert "Michael Trier" == a.name
+        assert "mtrier@example.com" == a.email
+        
+        # base type capabilities
+        assert a == a
+        assert not ( a != a )
+        m = set()
+        m.add(a)
+        m.add(a)
+        assert len(m) == 1
+
+    def test_from_string_should_handle_just_name(self):
+        a = Actor._from_string("Michael Trier")
+        assert "Michael Trier" == a.name
+        assert None == a.email
+
+    def test_should_display_representation(self):
+        a = Actor._from_string("Michael Trier <mtrier@example.com>")
+        assert '<git.Actor "Michael Trier <mtrier@example.com>">' == repr(a)
+
+    def test_str_should_alias_name(self):
+        a = Actor._from_string("Michael Trier <mtrier@example.com>")
+        assert a.name == str(a)
diff --git a/git/typ.py b/git/typ.py
new file mode 100644
index 00000000..a2e719be
--- /dev/null
+++ b/git/typ.py
@@ -0,0 +1,27 @@
+# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
+#
+# This module is part of GitDB and is released under
+# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
+"""Module containing information about types known to the database"""
+
+#{ String types 
+
+# For compatability only, use ObjectType instead
+str_blob_type = "blob"
+str_commit_type = "commit"
+str_tree_type = "tree"
+str_tag_type = "tag"
+
+class ObjectType(object):
+	"""Enumeration providing object types as strings and ids"""
+	blob = str_blob_type
+	commit = str_commit_type
+	tree = str_tree_type
+	tag = str_tag_type
+
+	commit_id = 1
+	tree_id = 2
+	blob_id = 3
+	tag_id = 4
+
+#} END string types
diff --git a/git/util.py b/git/util.py
index 3d0bd82e..1ef1fca1 100644
--- a/git/util.py
+++ b/git/util.py
@@ -4,38 +4,753 @@
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 
+import platform
+import binascii
 import os
-import re
+import mmap
 import sys
+import errno
+import re
 import time
 import tempfile
 
-from gitdb.util import (
-							make_sha, 
-							LockedFD, 
-							file_contents_ro, 
-							LazyMixin, 
-							to_hex_sha, 
-							to_bin_sha,
-							join_path, 
-							join_path_native,
-							to_native_path,
-							to_native_path_linux,
-							to_native_path_windows,
-							assure_directory_exists,
-							LockFile,
-							BlockingLockFile,
-							Actor,
-							Iterable,
-							stream_copy,
-							IterableList,
-							get_user_id
-						)
-
 __all__ = ( "stream_copy", "join_path", "to_native_path_windows", "to_native_path_linux", 
 			"join_path_native", "Stats", "IndexFileSHA1Writer", "Iterable", "IterableList", 
 			"BlockingLockFile", "LockFile", 'Actor', 'get_user_id', 'assure_directory_exists',
-			'RemoteProgress', 'RepoAliasMixin')
+			'RemoteProgress', 'RepoAliasMixin', 'LockedFD', 'LazyMixin' )
+
+from cStringIO import StringIO
+
+# in py 2.4, StringIO is only StringI, without write support.
+# Hence we must use the python implementation for this
+if sys.version_info[1] < 5:
+	from StringIO import StringIO
+# END handle python 2.4
+
+try:
+	import async.mod.zlib as zlib
+except ImportError:
+	import zlib
+# END try async zlib
+
+from async import ThreadPool
+
+try:
+    import hashlib
+except ImportError:
+    import sha
+
+try:
+	from struct import unpack_from
+except ImportError:
+	from struct import unpack, calcsize
+	__calcsize_cache = dict()
+	def unpack_from(fmt, data, offset=0):
+		try:
+			size = __calcsize_cache[fmt]
+		except KeyError:
+			size = calcsize(fmt)
+			__calcsize_cache[fmt] = size
+		# END exception handling
+		return unpack(fmt, data[offset : offset + size])
+	# END own unpack_from implementation
+
+
+#{ Globals
+
+# A pool distributing tasks, initially with zero threads, hence everything 
+# will be handled in the main thread
+pool = ThreadPool(0)
+
+#} END globals
+
+
+#{ Aliases
+
+hex_to_bin = binascii.a2b_hex
+bin_to_hex = binascii.b2a_hex
+
+# errors
+ENOENT = errno.ENOENT
+
+# os shortcuts
+exists = os.path.exists
+mkdir = os.mkdir
+chmod = os.chmod
+isdir = os.path.isdir
+isfile = os.path.isfile
+rename = os.rename
+remove = os.remove
+dirname = os.path.dirname
+basename = os.path.basename
+normpath = os.path.normpath
+expandvars = os.path.expandvars
+expanduser = os.path.expanduser
+abspath = os.path.abspath
+join = os.path.join
+read = os.read
+write = os.write
+close = os.close
+fsync = os.fsync
+
+# constants
+NULL_HEX_SHA = "0"*40
+NULL_BIN_SHA = "\0"*20
+
+#} END Aliases
+
+#{ compatibility stuff ... 
+
+class _RandomAccessStringIO(object):
+	"""Wrapper to provide required functionality in case memory maps cannot or may 
+	not be used. This is only really required in python 2.4"""
+	__slots__ = '_sio'
+	
+	def __init__(self, buf=''):
+		self._sio = StringIO(buf)
+		
+	def __getattr__(self, attr):
+		return getattr(self._sio, attr)
+	
+	def __len__(self):
+		return len(self.getvalue())
+		
+	def __getitem__(self, i):
+		return self.getvalue()[i]
+		
+	def __getslice__(self, start, end):
+		return self.getvalue()[start:end]
+	
+#} END compatibility stuff ...
+
+#{ Routines
+
+def get_user_id():
+	""":return: string identifying the currently active system user as name@node
+	:note: user can be set with the 'USER' environment variable, usually set on windows"""
+	ukn = 'UNKNOWN'
+	username = os.environ.get('USER', os.environ.get('USERNAME', ukn))
+	if username == ukn and hasattr(os, 'getlogin'):
+		username = os.getlogin()
+	# END get username from login
+	return "%s@%s" % (username, platform.node())
+
+def is_git_dir(d):
+	""" This is taken from the git setup.c:is_git_directory
+	function."""
+	if isdir(d) and \
+			isdir(join(d, 'objects')) and \
+			isdir(join(d, 'refs')):
+		headref = join(d, 'HEAD')
+		return isfile(headref) or \
+				(os.path.islink(headref) and
+				os.readlink(headref).startswith('refs'))
+	return False
+
+
+def stream_copy(source, destination, chunk_size=512*1024):
+	"""Copy all data from the source stream into the destination stream in chunks
+	of size chunk_size
+	
+	:return: amount of bytes written"""
+	br = 0
+	while True:
+		chunk = source.read(chunk_size)
+		destination.write(chunk)
+		br += len(chunk)
+		if len(chunk) < chunk_size:
+			break
+	# END reading output stream
+	return br
+	
+def make_sha(source=''):
+    """A python2.4 workaround for the sha/hashlib module fiasco 
+    :note: From the dulwich project """
+    try:
+        return hashlib.sha1(source)
+    except NameError:
+        sha1 = sha.sha(source)
+        return sha1
+
+def allocate_memory(size):
+	""":return: a file-protocol accessible memory block of the given size"""
+	if size == 0:
+		return _RandomAccessStringIO('')
+	# END handle empty chunks gracefully
+	
+	try:
+		return mmap.mmap(-1, size)	# read-write by default
+	except EnvironmentError:
+		# setup real memory instead
+		# this of course may fail if the amount of memory is not available in
+		# one chunk - would only be the case in python 2.4, being more likely on 
+		# 32 bit systems.
+		return _RandomAccessStringIO("\0"*size)
+	# END handle memory allocation
+	
+
+def file_contents_ro(fd, stream=False, allow_mmap=True):
+	""":return: read-only contents of the file represented by the file descriptor fd
+	:param fd: file descriptor opened for reading
+	:param stream: if False, random access is provided, otherwise the stream interface
+		is provided.
+	:param allow_mmap: if True, its allowed to map the contents into memory, which 
+		allows large files to be handled and accessed efficiently. The file-descriptor
+		will change its position if this is False"""
+	try:
+		if allow_mmap:
+			# supports stream and random access
+			try:
+				return mmap.mmap(fd, 0, access=mmap.ACCESS_READ)
+			except EnvironmentError:
+				# python 2.4 issue, 0 wants to be the actual size
+				return mmap.mmap(fd, os.fstat(fd).st_size, access=mmap.ACCESS_READ)
+			# END handle python 2.4
+	except OSError:
+		pass
+	# END exception handling
+	
+	# read manully
+	contents = os.read(fd, os.fstat(fd).st_size)
+	if stream:
+		return _RandomAccessStringIO(contents)
+	return contents
+	
+def file_contents_ro_filepath(filepath, stream=False, allow_mmap=True, flags=0):
+	"""Get the file contents at filepath as fast as possible
+	:return: random access compatible memory of the given filepath
+	:param stream: see ``file_contents_ro``
+	:param allow_mmap: see ``file_contents_ro``
+	:param flags: additional flags to pass to os.open
+	:raise OSError: If the file could not be opened
+	:note: for now we don't try to use O_NOATIME directly as the right value needs to be 
+		shared per database in fact. It only makes a real difference for loose object 
+		databases anyway, and they use it with the help of the ``flags`` parameter"""
+	fd = os.open(filepath, os.O_RDONLY|getattr(os, 'O_BINARY', 0)|flags)
+	try:
+		return file_contents_ro(fd, stream, allow_mmap)
+	finally:
+		close(fd)
+	# END assure file is closed
+	
+def to_hex_sha(sha):
+	""":return: hexified version  of sha"""
+	if len(sha) == 40:
+		return sha
+	return bin_to_hex(sha)
+	
+def to_bin_sha(sha):
+	if len(sha) == 20:
+		return sha
+	return hex_to_bin(sha)
+
+def join_path(a, *p):
+	"""Join path tokens together similar to os.path.join, but always use 
+	'/' instead of possibly '\' on windows."""
+	path = a
+	for b in p:
+		if b.startswith('/'):
+			path += b[1:]
+		elif path == '' or path.endswith('/'):
+			path +=	 b
+		else:
+			path += '/' + b
+	return path
+	
+def to_native_path_windows(path):
+	return path.replace('/','\\')
+	
+def to_native_path_linux(path):
+	return path.replace('\\','/')
+
+
+if sys.platform.startswith('win'):
+	to_native_path = to_native_path_windows
+else:
+	# no need for any work on linux
+	def to_native_path_linux(path):
+		return path
+	to_native_path = to_native_path_linux
+
+def join_path_native(a, *p):
+	"""
+	As join path, but makes sure an OS native path is returned. This is only 
+		needed to play it safe on my dear windows and to assure nice paths that only 
+		use '\'"""
+	return to_native_path(join_path(a, *p))
+
+def assure_directory_exists(path, is_file=False):
+	"""Assure that the directory pointed to by path exists.
+	
+	:param is_file: If True, path is assumed to be a file and handled correctly.
+		Otherwise it must be a directory
+	:return: True if the directory was created, False if it already existed"""
+	if is_file:
+		path = os.path.dirname(path)
+	#END handle file 
+	if not os.path.isdir(path):
+		os.makedirs(path)
+		return True
+	return False
+
+
+#} END routines
+
+
+#{ Utilities
+
+class LazyMixin(object):
+	"""
+	Base class providing an interface to lazily retrieve attribute values upon
+	first access. If slots are used, memory will only be reserved once the attribute
+	is actually accessed and retrieved the first time. All future accesses will
+	return the cached value as stored in the Instance's dict or slot.
+	"""
+	
+	__slots__ = tuple()
+	
+	def __getattr__(self, attr):
+		"""
+		Whenever an attribute is requested that we do not know, we allow it 
+		to be created and set. Next time the same attribute is reqeusted, it is simply
+		returned from our dict/slots. """
+		self._set_cache_(attr)
+		# will raise in case the cache was not created
+		return object.__getattribute__(self, attr)
+
+	def _set_cache_(self, attr):
+		"""
+		This method should be overridden in the derived class. 
+		It should check whether the attribute named by attr can be created
+		and cached. Do nothing if you do not know the attribute or call your subclass
+		
+		The derived class may create as many additional attributes as it deems 
+		necessary in case a git command returns more information than represented 
+		in the single attribute."""
+		pass
+
+	
+class LockedFD(object):
+	"""
+	This class facilitates a safe read and write operation to a file on disk.
+	If we write to 'file', we obtain a lock file at 'file.lock' and write to 
+	that instead. If we succeed, the lock file will be renamed to overwrite 
+	the original file.
+	
+	When reading, we obtain a lock file, but to prevent other writers from 
+	succeeding while we are reading the file.
+	
+	This type handles error correctly in that it will assure a consistent state 
+	on destruction.
+	
+	:note: with this setup, parallel reading is not possible"""
+	__slots__ = ("_filepath", '_fd', '_write')
+	
+	def __init__(self, filepath):
+		"""Initialize an instance with the givne filepath"""
+		self._filepath = filepath
+		self._fd = None
+		self._write = None			# if True, we write a file
+	
+	def __del__(self):
+		# will do nothing if the file descriptor is already closed
+		if self._fd is not None:
+			self.rollback()
+		
+	def _lockfilepath(self):
+		return "%s.lock" % self._filepath
+		
+	def open(self, write=False, stream=False):
+		"""
+		Open the file descriptor for reading or writing, both in binary mode.
+		
+		:param write: if True, the file descriptor will be opened for writing. Other
+			wise it will be opened read-only.
+		:param stream: if True, the file descriptor will be wrapped into a simple stream 
+			object which supports only reading or writing
+		:return: fd to read from or write to. It is still maintained by this instance
+			and must not be closed directly
+		:raise IOError: if the lock could not be retrieved
+		:raise OSError: If the actual file could not be opened for reading
+		:note: must only be called once"""
+		if self._write is not None:
+			raise AssertionError("Called %s multiple times" % self.open)
+		
+		self._write = write
+		
+		# try to open the lock file
+		binary = getattr(os, 'O_BINARY', 0)
+		lockmode = 	os.O_WRONLY | os.O_CREAT | os.O_EXCL | binary
+		try:
+			fd = os.open(self._lockfilepath(), lockmode, 0600)
+			if not write:
+				os.close(fd)
+			else:
+				self._fd = fd
+			# END handle file descriptor
+		except OSError:
+			raise IOError("Lock at %r could not be obtained" % self._lockfilepath())
+		# END handle lock retrieval
+		
+		# open actual file if required
+		if self._fd is None:
+			# we could specify exlusive here, as we obtained the lock anyway
+			try:
+				self._fd = os.open(self._filepath, os.O_RDONLY | binary)
+			except:
+				# assure we release our lockfile
+				os.remove(self._lockfilepath())
+				raise
+			# END handle lockfile
+		# END open descriptor for reading
+		
+		if stream:
+			# need delayed import
+			from stream import FDStream
+			return FDStream(self._fd)
+		else:
+			return self._fd
+		# END handle stream
+		
+	def commit(self):
+		"""When done writing, call this function to commit your changes into the 
+		actual file. 
+		The file descriptor will be closed, and the lockfile handled.
+		:note: can be called multiple times"""
+		self._end_writing(successful=True)
+		
+	def rollback(self):
+		"""Abort your operation without any changes. The file descriptor will be 
+		closed, and the lock released.
+		:note: can be called multiple times"""
+		self._end_writing(successful=False)
+		
+	def _end_writing(self, successful=True):
+		"""Handle the lock according to the write mode """
+		if self._write is None:
+			raise AssertionError("Cannot end operation if it wasn't started yet")
+		
+		if self._fd is None:
+			return
+		
+		os.close(self._fd)
+		self._fd = None
+		
+		lockfile = self._lockfilepath()
+		if self._write and successful:
+			# on windows, rename does not silently overwrite the existing one
+			if sys.platform == "win32":
+				if isfile(self._filepath):
+					os.remove(self._filepath)
+				# END remove if exists
+			# END win32 special handling
+			os.rename(lockfile, self._filepath)
+			
+			# assure others can at least read the file - the tmpfile left it at rw--
+			# We may also write that file, on windows that boils down to a remove-
+			# protection as well
+			chmod(self._filepath, 0644)
+		else:
+			# just delete the file so far, we failed
+			os.remove(lockfile)
+		# END successful handling
+		
+		
+class LockFile(object):
+	"""Provides methods to obtain, check for, and release a file based lock which 
+	should be used to handle concurrent access to the same file.
+	
+	As we are a utility class to be derived from, we only use protected methods.
+	
+	Locks will automatically be released on destruction"""
+	__slots__ = ("_file_path", "_owns_lock")
+	
+	def __init__(self, file_path):
+		self._file_path = file_path
+		self._owns_lock = False
+	
+	def __del__(self):
+		self._release_lock()
+	
+	def _lock_file_path(self):
+		""":return: Path to lockfile"""
+		return "%s.lock" % (self._file_path)
+	
+	def _has_lock(self):
+		""":return: True if we have a lock and if the lockfile still exists
+		:raise AssertionError: if our lock-file does not exist"""
+		if not self._owns_lock:
+			return False
+		
+		return True
+		
+	def _obtain_lock_or_raise(self):
+		"""Create a lock file as flag for other instances, mark our instance as lock-holder
+		
+		:raise IOError: if a lock was already present or a lock file could not be written"""
+		if self._has_lock():
+			return 
+		lock_file = self._lock_file_path()
+		if os.path.isfile(lock_file):
+			raise IOError("Lock for file %r did already exist, delete %r in case the lock is illegal" % (self._file_path, lock_file))
+			
+		try:
+			fd = os.open(lock_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0)
+			os.close(fd)
+		except OSError,e:
+			raise IOError(str(e))
+		
+		self._owns_lock = True
+		
+	def _obtain_lock(self):
+		"""The default implementation will raise if a lock cannot be obtained.
+		Subclasses may override this method to provide a different implementation"""
+		return self._obtain_lock_or_raise()
+		
+	def _release_lock(self):
+		"""Release our lock if we have one"""
+		if not self._has_lock():
+			return
+			
+		# if someone removed our file beforhand, lets just flag this issue
+		# instead of failing, to make it more usable.
+		lfp = self._lock_file_path()
+		try:
+			# on bloody windows, the file needs write permissions to be removable.
+			# Why ... 
+			if os.name == 'nt':
+				os.chmod(lfp, 0777)
+			# END handle win32
+			os.remove(lfp)
+		except OSError:
+			pass
+		self._owns_lock = False
+
+
+class BlockingLockFile(LockFile):
+	"""The lock file will block until a lock could be obtained, or fail after 
+	a specified timeout.
+	
+	:note: If the directory containing the lock was removed, an exception will 
+		be raised during the blocking period, preventing hangs as the lock 
+		can never be obtained."""
+	__slots__ = ("_check_interval", "_max_block_time")
+	def __init__(self, file_path, check_interval_s=0.3, max_block_time_s=sys.maxint):
+		"""Configure the instance
+		
+		:parm check_interval_s:
+			Period of time to sleep until the lock is checked the next time.
+			By default, it waits a nearly unlimited time
+		
+		:parm max_block_time_s: Maximum amount of seconds we may lock"""
+		super(BlockingLockFile, self).__init__(file_path)
+		self._check_interval = check_interval_s
+		self._max_block_time = max_block_time_s
+		
+	def _obtain_lock(self):
+		"""This method blocks until it obtained the lock, or raises IOError if 
+		it ran out of time or if the parent directory was not available anymore.
+		If this method returns, you are guranteed to own the lock"""
+		starttime = time.time()
+		maxtime = starttime + float(self._max_block_time)
+		while True:
+			try:
+				super(BlockingLockFile, self)._obtain_lock()
+			except IOError:
+				# synity check: if the directory leading to the lockfile is not
+				# readable anymore, raise an execption
+				curtime = time.time()
+				if not os.path.isdir(os.path.dirname(self._lock_file_path())):
+					msg = "Directory containing the lockfile %r was not readable anymore after waiting %g seconds" % (self._lock_file_path(), curtime - starttime)
+					raise IOError(msg)
+				# END handle missing directory
+				
+				if curtime >= maxtime:
+					msg = "Waited %g seconds for lock at %r" % ( maxtime - starttime, self._lock_file_path())
+					raise IOError(msg)
+				# END abort if we wait too long
+				time.sleep(self._check_interval)
+			else:
+				break
+		# END endless loop
+
+
+class Actor(object):
+	"""Actors hold information about a person acting on the repository. They 
+	can be committers and authors or anything with a name and an email as 
+	mentioned in the git log entries."""
+	# PRECOMPILED REGEX
+	name_only_regex = re.compile( r'<(.+)>' )
+	name_email_regex = re.compile( r'(.*) <(.+?)>' )
+	
+	# ENVIRONMENT VARIABLES
+	# read when creating new commits
+	env_author_name = "GIT_AUTHOR_NAME"
+	env_author_email = "GIT_AUTHOR_EMAIL"
+	env_committer_name = "GIT_COMMITTER_NAME"
+	env_committer_email = "GIT_COMMITTER_EMAIL"
+	
+	# CONFIGURATION KEYS
+	conf_name = 'name'
+	conf_email = 'email'
+	
+	__slots__ = ('name', 'email')
+	
+	def __init__(self, name, email):
+		self.name = name
+		self.email = email
+
+	def __eq__(self, other):
+		return self.name == other.name and self.email == other.email
+		
+	def __ne__(self, other):
+		return not (self == other)
+		
+	def __hash__(self):
+		return hash((self.name, self.email))
+
+	def __str__(self):
+		return self.name
+
+	def __repr__(self):
+		return '<git.Actor "%s <%s>">' % (self.name, self.email)
+
+	@classmethod
+	def _from_string(cls, string):
+		"""Create an Actor from a string.
+		:param string: is the string, which is expected to be in regular git format
+
+				John Doe <jdoe@example.com>
+				
+		:return: Actor """
+		m = cls.name_email_regex.search(string)
+		if m:
+			name, email = m.groups()
+			return cls(name, email)
+		else:
+			m = cls.name_only_regex.search(string)
+			if m:
+				return cls(m.group(1), None)
+			else:
+				# assume best and use the whole string as name
+				return cls(string, None)
+			# END special case name
+		# END handle name/email matching
+		
+	@classmethod
+	def _main_actor(cls, env_name, env_email, config_reader=None):
+		actor = cls('', '')
+		default_email = get_user_id()
+		default_name = default_email.split('@')[0]
+		
+		for attr, evar, cvar, default in (('name', env_name, cls.conf_name, default_name), 
+										('email', env_email, cls.conf_email, default_email)):
+			try:
+				setattr(actor, attr, os.environ[evar])
+			except KeyError:
+				if config_reader is not None:
+					setattr(actor, attr, config_reader.get_value('user', cvar, default))
+				#END config-reader handling
+				if not getattr(actor, attr):
+					setattr(actor, attr, default)
+			#END handle name
+		#END for each item to retrieve
+		return actor
+		
+		
+	@classmethod
+	def committer(cls, config_reader=None):
+		"""
+		:return: Actor instance corresponding to the configured committer. It behaves
+			similar to the git implementation, such that the environment will override 
+			configuration values of config_reader. If no value is set at all, it will be
+			generated
+		:param config_reader: ConfigReader to use to retrieve the values from in case
+			they are not set in the environment"""
+		return cls._main_actor(cls.env_committer_name, cls.env_committer_email, config_reader)
+		
+	@classmethod
+	def author(cls, config_reader=None):
+		"""Same as committer(), but defines the main author. It may be specified in the environment, 
+		but defaults to the committer"""
+		return cls._main_actor(cls.env_author_name, cls.env_author_email, config_reader)
+		
+
+class Iterable(object):
+	"""Defines an interface for iterable items which is to assure a uniform 
+	way to retrieve and iterate items within the git repository"""
+	__slots__ = tuple()
+	_id_attribute_ = "attribute that most suitably identifies your instance"
+	
+	@classmethod
+	def list_items(cls, repo, *args, **kwargs):
+		"""
+		Find all items of this type - subclasses can specify args and kwargs differently.
+		If no args are given, subclasses are obliged to return all items if no additional 
+		arguments arg given.
+		
+		:note: Favor the iter_items method as it will
+		
+		:return:list(Item,...) list of item instances"""
+		out_list = IterableList( cls._id_attribute_ )
+		out_list.extend(cls.iter_items(repo, *args, **kwargs))
+		return out_list
+		
+		
+	@classmethod
+	def iter_items(cls, repo, *args, **kwargs):
+		"""For more information about the arguments, see list_items
+		:return:  iterator yielding Items"""
+		raise NotImplementedError("To be implemented by Subclass")
+		
+
+class IterableList(list):
+	"""
+	List of iterable objects allowing to query an object by id or by named index::
+	 
+	 heads = repo.heads
+	 heads.master
+	 heads['master']
+	 heads[0]
+	 
+	It requires an id_attribute name to be set which will be queried from its 
+	contained items to have a means for comparison.
+	
+	A prefix can be specified which is to be used in case the id returned by the 
+	items always contains a prefix that does not matter to the user, so it 
+	can be left out."""
+	__slots__ = ('_id_attr', '_prefix')
+	
+	def __new__(cls, id_attr, prefix=''):
+		return super(IterableList,cls).__new__(cls)
+		
+	def __init__(self, id_attr, prefix=''):
+		self._id_attr = id_attr
+		self._prefix = prefix
+		if not isinstance(id_attr, basestring):
+			raise ValueError("First parameter must be a string identifying the name-property. Extend the list after initialization")
+		# END help debugging !
+		
+	def __getattr__(self, attr):
+		attr = self._prefix + attr
+		for item in self:
+			if getattr(item, self._id_attr) == attr:
+				return item
+		# END for each item
+		return list.__getattribute__(self, attr)
+		
+	def __getitem__(self, index):
+		if isinstance(index, int):
+			return list.__getitem__(self,index)
+		
+		try:
+			return getattr(self, index)
+		except AttributeError:
+			raise IndexError( "No item found with id %r" % (self._prefix + index) )
+			
+
+
+#} END utilities
 
 #{ Classes