fix(Head): checkout() handles detached head

It's not optimal, as we can now return one of two types
which are only compatible in the most basic ways.

However, it is better than before, I presume.

Fixes gitpython-developers#510

Author: Byron

doc/source/changes.rst

@@ -7,6 +7,8 @@ Changelog
 
 * `tag.commit` will now resolve commits deeply.
 * `Repo` objects can now be pickled, which helps with multi-processing.
+* `Head.checkout()` now deals with detached heads, which is when it will return
+  the `HEAD` reference instead.
 
 * `DiffIndex.iter_change_type(...)` produces better results when diffing
 2.0.8 - Features and Bugfixes

git/refs/head.py

@@ -202,6 +202,8 @@ def checkout(self, force=False, **kwargs):
         :return:
             The active branch after the checkout operation, usually self unless
             a new branch has been created.
+            If there is no active branch, as the HEAD is now detached, the HEAD
+            reference will be returned instead.
 
         :note:
             By default it is only allowed to checkout heads - everything else
@@ -212,7 +214,10 @@ def checkout(self, force=False, **kwargs):
             kwargs.pop('f')
 
         self.repo.git.checkout(self, **kwargs)
-        return self.repo.active_branch
+        if self.repo.head.is_detached:
+            return self.repo.head
+        else:
+            return self.repo.active_branch
 
     #{ Configruation
 

git/test/test_refs.py

@@ -175,6 +175,12 @@ def test_is_valid(self):
 
     def test_orig_head(self):
         assert type(self.rorepo.head.orig_head()) == SymbolicReference
+        
+    @with_rw_repo('0.1.6')
+    def test_head_checkout_detached_head(self, rw_repo):
+        res = rw_repo.remotes.origin.refs.master.checkout()
+        assert isinstance(res, SymbolicReference)
+        assert res.name == 'HEAD'
 
     @with_rw_repo('0.1.6')
     def test_head_reset(self, rw_repo):