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 #510

3 files changed, 14 insertions, 1 deletions

diff --git a/doc/source/changes.rst b/doc/source/changes.rst
index 62f8ab45..fcd8240c 100644
--- a/doc/source/changes.rst
+++ b/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
diff --git a/git/refs/head.py b/git/refs/head.py
index 06207e0a..fe820b10 100644
--- a/git/refs/head.py
+++ b/git/refs/head.py
@@ -202,6 +202,8 @@ class Head(Reference):
         :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 @@ class Head(Reference):
             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
 
diff --git a/git/test/test_refs.py b/git/test/test_refs.py
index 879b8caa..9816fb50 100644
--- a/git/test/test_refs.py
+++ b/git/test/test_refs.py
@@ -175,6 +175,12 @@ class TestRefs(TestBase):
 
     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):