@@ -27,6 +27,9 @@ General
   terms are used everywhere, such as "Reference" ( ref ) and "Revision" ( rev ).
   Prevously multiple terms where used making it harder to know which type was allowed
   or not.
+* Unified diff interface to allow easy diffing between trees, trees and index, trees
+  and working tree, index and working tree, trees and index. This closely follows
+  the git-diff capabilities.
 
 
 Item Iteration
 
@@ -9,7 +9,7 @@
 
 class Diff(object):
 	"""
-	A Diff contains diff information between two commits.
+	A Diff contains diff information between two Trees.
 	
 	It contains two sides a and b of the diff, members are prefixed with 
 	"a" and "b" respectively to inidcate that.
@@ -74,18 +74,20 @@ def __init__(self, repo, a_path, b_path, a_blob_id, b_blob_id, a_mode,
 		self.diff = diff
 
 	@classmethod
-	def _list_from_string(cls, repo, text):
+	def _index_from_patch_format(cls, repo, stream):
 		"""
-		Create a new diff object from the given text
+		Create a new DiffIndex from the given text which must be in patch format
 		``repo``
 			is the repository we are operating on - it is required 
 		
-		``text``
-			result of 'git diff' between two commits or one commit and the index
+		``stream``
+			result of 'git diff' as a stream (supporting file protocol)
 		
 		Returns
-			git.Diff[]
+			git.DiffIndex
 		"""
+		# for now, we have to bake the stream
+		text = stream.read()
 		diffs = []
 
 		diff_header = cls.re_header.match
@@ -102,4 +104,14 @@ def _list_from_string(cls, repo, text):
 				new_file, deleted_file, rename_from, rename_to, diff[header.end():]))
 
 		return diffs
+		
+	@classmethod
+	def _index_from_raw_format(cls, repo, stream):
+		"""
+		Create a new DiffIndex from the given stream which must be in raw format.
+		
+		Returns
+			git.DiffIndex
+		"""
+		raise NotImplementedError("")
 
@@ -172,3 +172,74 @@ def _mode_str_to_int(cls, modestr):
 		return mode
 
 
+class Diffable(object):
+	"""
+	Common interface for all object that can be diffed against another object of compatible type.
+	
+	NOTE: 
+		Subclasses require a repo member as it is the case for Object instances, for practical 
+		reasons we do not derive from Object.
+	"""
+	__slots__ = tuple()
+	
+	# subclasses provide additional arguments to the git-diff comamnd by supplynig 
+	# them in this tuple
+	_diff_args = tuple()
+	
+	def diff(self, other=None, paths=None, create_patch=False, **kwargs):
+		"""
+		Creates diffs between two items being trees, trees and index or an 
+		index and the working tree.
+
+		``other``
+			Is the item to compare us with. 
+			If None, we will be compared to the working tree.
+
+		``paths``
+			is a list of paths or a single path to limit the diff to.
+			It will only include at least one of the givne path or paths.
+
+		``create_patch``
+			If True, the returned Diff contains a detailed patch that if applied
+			makes the self to other. Patches are somwhat costly as blobs have to be read
+			and diffed.
+
+		``kwargs``
+			Additional arguments passed to git-diff, such as 
+			R=True to swap both sides of the diff.
+
+		Returns
+			git.DiffIndex
+			
+		Note
+			Rename detection will only work if create_patch is True
+		"""
+		args = list(self._diff_args[:])
+		args.append( "--abbrev=40" )		# we need full shas
+		args.append( "--full-index" )		# get full index paths, not only filenames
+		
+		if create_patch:
+			args.append("-p")
+			args.append("-M") # check for renames
+		else:
+			args.append("--raw")
+		
+		paths = paths or []
+		if paths:
+			paths.insert(0, "--")
+
+		if other is not None:
+			args.insert(0, other)
+		
+		args.insert(0,self)
+		args.extend(paths)
+		
+		kwargs['as_process'] = True
+		proc = self.repo.git.diff(*args, **kwargs)
+		
+		diff_method = diff.Diff._index_from_raw_format
+		if create_patch:
+			diff_method = diff.Diff._index_from_patch_format(self.repo, proc.stdout)
+		return diff_method(self.repo, proc.stdout)
+		
+
@@ -11,7 +11,7 @@
 import base
 import utils
 
-class Commit(base.Object, Iterable):
+class Commit(base.Object, Iterable, base.Diffable):
 	"""
 	Wraps a git Commit object.
 	
@@ -176,60 +176,6 @@ def iter_parents(self, paths='', **kwargs):
 
 		return self.iter_items( self.repo, self, paths, **kwargs )
 
-	@classmethod
-	def diff(cls, repo, a, b=None, paths=None):
-		"""
-		Creates diffs between a tree and the index or between two trees:
-
-		``repo``
-			is the Repo
-
-		``a``
-			is a named commit
-
-		``b``
-			is an optional named commit.  Passing a list assumes you
-			wish to omit the second named commit and limit the diff to the
-			given paths.
-
-		``paths``
-			is a list of paths to limit the diff to.
-
-		Returns
-			git.Diff[]::
-			
-			 between tree and the index if only a is given
-			 between two trees if a and b  are given and are commits 
-		"""
-		paths = paths or []
-
-		if isinstance(b, list):
-			paths = b
-			b = None
-
-		if paths:
-			paths.insert(0, "--")
-
-		if b:
-			paths.insert(0, b)
-		paths.insert(0, a)
-		text = repo.git.diff('-M', full_index=True, *paths)
-		return diff.Diff._list_from_string(repo, text)
-
-	@property
-	def diffs(self):
-		"""
-		Returns
-			git.Diff[]
-			Diffs between this commit and its first parent or all changes if this 
-			commit is the first commit and has no parent.
-		"""
-		if not self.parents:
-			d = self.repo.git.show(self.id, '-M', full_index=True, pretty='raw')
-			return diff.Diff._list_from_string(self.repo, d)
-		else:
-			return self.diff(self.repo, self.parents[0].id, self.id)
-
 	@property
 	def stats(self):
 		"""
 
@@ -15,7 +15,7 @@ def sha_to_hex(sha):
     assert len(hexsha) == 40, "Incorrect length of sha1 string: %d" % hexsha
     return hexsha
 
-class Tree(base.IndexObject):
+class Tree(base.IndexObject, base.Diffable):
 	"""
 	Tress represent a ordered list of Blobs and other Trees. Hence it can be 
 	accessed like a list.
@@ -169,6 +169,7 @@ def _iter_recursive(cls, repo, tree, cur_depth, max_depth, predicate ):
 	def traverse(self, max_depth=-1, predicate = lambda i: True):
 		"""
 		Returns
+		
 			Iterator to traverse the tree recursively up to the given level.
 			The iterator returns Blob and Tree objects