Now Repository.head returns a reference (#203)

Now Repository.head behaves like libgit2's git_repository_head, it
returns the resolved reference. These two lines are equivalent:

  ref = repo.head
  ref = repo.lookup_reference('HEAD').resolve()

Before it returned a commit.

docs/diff.rst

@@ -4,19 +4,18 @@ Diff
 
 A diff shows the changes between trees, an index or the working dir::
 
+    >>> head = repo.revparse_single('HEAD')
+
     # Diff two trees
-    >>> t0 = repo.head.tree
-    >>> t1 = repo.head.parents[0].tree
+    >>> t0 = head.tree
+    >>> t1 = head.parents[0].tree
     >>> diff = t1.diff(t0)
-    >>> diff
 
     # Diff a tree with the index
-    >>> tree = repo.head.tree
-    >>> diff = tree.diff(repo.index)
+    >>> diff = head.tree.diff(repo.index)
 
     # Diff a tree with the current working dir
-    >>> tree = repo.head.tree
-    >>> diff = tree.diff()
+    >>> diff = head.tree.diff()
 
 
 The Diff type

docs/objects.rst

@@ -10,9 +10,6 @@ In the first place Git is a key-value storage system. The values stored are
 called *objects*, there are four types (commits, trees, blobs and tags),
 for each type pygit2 has a Python class::
 
-    >>> # Get the last commit
-    >>> head = repo.head
-
     >>> # Show commits and trees
     >>> commit
     <pygit2.Commit object at 0x7f9d2f3000b0>

docs/references.rst

@@ -17,12 +17,11 @@ Reference log::
     >>> for entry in head.log():
     ...     print(entry.message)
 
-The interface for RefLogEntry::
+Shortcuts::
 
-    RefLogEntry.committer -- Signature of Committer
-    RefLogEntry.message   -- the message of the RefLogEntry
-    RefLogEntry.oid_old   -- oid of old reference
-    RefLogEntry.oid_new   -- oid of new reference
+    >>> # These two lines are equivalent
+    >>> head = repo.head
+    >>> head = repo.lookup_reference('HEAD').resolve()
 
 
 The Reference type
@@ -40,6 +39,14 @@ The Reference type
 .. automethod:: pygit2.Reference.log
 
 
+The HEAD
+--------------------
+
+.. autoattribute:: pygit2.Repository.head
+.. autoattribute:: pygit2.Repository.head_is_detached
+.. autoattribute:: pygit2.Repository.head_is_orphaned
+
+
 The reference log
 --------------------
 
@@ -48,7 +55,6 @@ The reference log
 .. autoattribute:: pygit2.RefLogEntry.message
 .. autoattribute:: pygit2.RefLogEntry.committer
 
-
 Notes
 ====================
 

docs/repository.rst

@@ -41,6 +41,3 @@ To open an existing repository::
 .. autoattribute:: pygit2.Repository.is_empty
 .. automethod:: pygit2.Repository.read
 .. automethod:: pygit2.Repository.write
-.. autoattribute:: pygit2.Repository.head
-.. autoattribute:: pygit2.Repository.head_is_detached
-.. autoattribute:: pygit2.Repository.head_is_orphaned

src/repository.c

@@ -183,10 +183,7 @@ Repository_head__get__(Repository *self)
         return NULL;
     }
 
-    oid = git_reference_target(head);
-    pyobj = lookup_object(self, oid, GIT_OBJ_COMMIT);
-    git_reference_free(head);
-    return pyobj;
+    return wrap_reference(head);
 }
 
 

test/test_repository.py

@@ -27,18 +27,21 @@
 
 """Tests for Repository objects."""
 
+# Import from the future
 from __future__ import absolute_import
 from __future__ import unicode_literals
+
+# Import from the Standard Library
 import binascii
 import unittest
 import tempfile
 import os
 from os.path import join, realpath
 
+# Import from pygit2
 from pygit2 import GIT_OBJ_ANY, GIT_OBJ_BLOB, GIT_OBJ_COMMIT
-from pygit2 import init_repository, discover_repository, Commit, hashfile
+from pygit2 import init_repository, discover_repository, Reference, hashfile
 import pygit2
-
 from . import utils
 
 
@@ -59,7 +62,7 @@ class RepositoryTest(utils.BareRepoTestCase):
     def test_head(self):
         head = self.repo.head
         self.assertEqual(HEAD_SHA, head.hex)
-        self.assertEqual(type(head), Commit)
+        self.assertEqual(type(head), Reference)
         self.assertFalse(self.repo.head_is_orphaned)
         self.assertFalse(self.repo.head_is_detached)
 
@@ -191,10 +194,15 @@ class RepositoryTest_II(utils.RepoTestCase):
                           lambda: self.repo.checkout(reference=ref_i18n))
 
         # checkout i18n with GIT_CHECKOUT_FORCE
-        self.assertTrue('new' not in self.repo.head.tree)
+        head = self.repo.head
+        head = self.repo[head.target]
+        self.assertTrue('new' not in head.tree)
         self.repo.checkout(pygit2.GIT_CHECKOUT_FORCE, ref_i18n)
-        self.assertEqual(self.repo.head.hex, self.repo[ref_i18n.target].hex)
-        self.assertTrue('new' in self.repo.head.tree)
+
+        head = self.repo.head
+        head = self.repo[head.target]
+        self.assertEqual(head.hex, self.repo[ref_i18n.target].hex)
+        self.assertTrue('new' in head.tree)
         self.assertTrue('bye.txt' not in self.repo.status())
 
     def test_checkout_index(self):