feat: easy::Head::name() to learn about the name of the HEAD ref (#293)

It's mainly for completeness to provide people with with a `FullNameRef`
of HEAD.

Author: Byron

git-repository/src/easy/head.rs

@@ -37,6 +37,13 @@ impl Kind {
 }
 
 impl<'repo> Head<'repo> {
+    /// Returns the name of this references, always `HEAD`.
+    pub fn name(&self) -> FullNameRef<'static> {
+        // TODO: use a statically checked version of this when available.
+        use std::convert::TryFrom;
+        FullNameRef::try_from("HEAD").expect("HEAD is valid")
+    }
+
     /// Returns the full reference name of this head if it is not detached, or `None` otherwise.
     pub fn referent_name(&self) -> Option<FullNameRef<'_>> {
         Some(match &self.kind {
@@ -49,14 +56,15 @@ impl<'repo> Head<'repo> {
     pub fn is_detached(&self) -> bool {
         matches!(self.kind, Kind::Detached { .. })
     }
-}
 
-impl<'repo> Head<'repo> {
     // TODO: tests
     /// Returns the id the head points to, which isn't possible on unborn heads.
     pub fn id(&self) -> Option<easy::Oid<'repo>> {
         match &self.kind {
-            Kind::Symbolic(r) => r.target.as_id().map(|oid| oid.to_owned().attach(self.handle)),
+            Kind::Symbolic(r) => r
+                .target
+                .as_id()
+                .map(|oid| oid.to_owned().attach(self.handle)),
             Kind::Detached { peeled, target } => (*peeled)
                 .unwrap_or_else(|| target.to_owned())
                 .attach(self.handle)
@@ -66,14 +74,17 @@ impl<'repo> Head<'repo> {
     }
 
     /// Force transforming this instance into the symbolic reference that it points to, or panic if it is unborn or detached.
+    ///
+    /// # Panics
+    ///
+    /// If this isn't actually a head pointing to a symbolic reference.
     pub fn into_referent(self) -> easy::Reference<'repo> {
         match self.kind {
             Kind::Symbolic(r) => r.attach(self.handle),
             _ => panic!("BUG: Expected head to be a born symbolic reference"),
         }
     }
 }
-
 ///
 pub mod log {
     use std::convert::TryFrom;
@@ -150,9 +161,13 @@ pub mod peel {
             Some(match &mut self.kind {
                 Kind::Unborn(_name) => return None,
                 Kind::Detached {
-                    peeled: Some(peeled), ..
+                    peeled: Some(peeled),
+                    ..
                 } => Ok((*peeled).attach(self.handle)),
-                Kind::Detached { peeled: None, target } => {
+                Kind::Detached {
+                    peeled: None,
+                    target,
+                } => {
                     match target
                         .attach(self.handle)
                         .object()
@@ -185,12 +200,14 @@ pub mod peel {
         /// more object to follow, transform the id into a commit if possible and return that.
         ///
         /// Returns an error if the head is unborn or if it doesn't point to a commit.
-        pub fn peel_to_commit_in_place(&mut self) -> Result<easy::Commit<'repo>, peel_to_commit::Error> {
-            let id = self
-                .peel_to_id_in_place()
-                .ok_or_else(|| peel_to_commit::Error::Unborn {
-                    name: self.referent_name().expect("unborn").to_owned(),
-                })??;
+        pub fn peel_to_commit_in_place(
+            &mut self,
+        ) -> Result<easy::Commit<'repo>, peel_to_commit::Error> {
+            let id =
+                self.peel_to_id_in_place()
+                    .ok_or_else(|| peel_to_commit::Error::Unborn {
+                        name: self.referent_name().expect("unborn").to_owned(),
+                    })??;
             id.object()
                 .map_err(|err| peel_to_commit::Error::Peel(Error::FindExistingObject(err)))
                 .and_then(|object| object.try_into_commit().map_err(Into::into))
@@ -202,15 +219,22 @@ pub mod peel {
             Some(match self.kind {
                 Kind::Unborn(_name) => return None,
                 Kind::Detached {
-                    peeled: Some(peeled), ..
+                    peeled: Some(peeled),
+                    ..
                 } => Ok(peeled.attach(self.handle)),
-                Kind::Detached { peeled: None, target } => target
+                Kind::Detached {
+                    peeled: None,
+                    target,
+                } => target
                     .attach(self.handle)
                     .object()
                     .map_err(Into::into)
                     .and_then(|obj| obj.peel_tags_to_end().map_err(Into::into))
                     .map(|obj| obj.id.attach(self.handle)),
-                Kind::Symbolic(r) => r.attach(self.handle).peel_to_id_in_place().map_err(Into::into),
+                Kind::Symbolic(r) => r
+                    .attach(self.handle)
+                    .peel_to_id_in_place()
+                    .map_err(Into::into),
             })
         }
     }