feat: Repository::head_commit() (#364)

A shortcut to get to the commit much faster.

Author: Byron

git-repository/src/reference/errors.rs

@@ -43,6 +43,19 @@ pub mod head_id {
     }
 }
 
+///
+pub mod head_commit {
+    /// The error returned by [Repository::head_commit(…)][crate::Repository::head_commit()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        Head(#[from] crate::reference::find::existing::Error),
+        #[error(transparent)]
+        PeelToCommit(#[from] crate::head::peel::to_commit::Error),
+    }
+}
+
 ///
 pub mod find {
     ///

git-repository/src/reference/mod.rs

@@ -8,7 +8,7 @@ use crate::{Id, Reference};
 pub mod iter;
 
 mod errors;
-pub use errors::{edit, find, head_id, peel};
+pub use errors::{edit, find, head_commit, head_id, peel};
 
 use crate::ext::ObjectIdExt;
 

git-repository/src/repository/reference.rs

@@ -184,7 +184,7 @@ impl crate::Repository {
         .attach(self))
     }
 
-    /// Resolve the head, follow and peel its target and obtain its object id.
+    /// Resolve the `HEAD` reference, follow and peel its target and obtain its object id.
     ///
     /// Note that this may fail for various reasons, most notably because the repository
     /// is freshly initialized and doesn't have any commits yet.
@@ -200,6 +200,15 @@ impl crate::Repository {
             .map_err(Into::into)
     }
 
+    /// Return the commit object the `HEAD` reference currently points to after peeling it fully.
+    ///
+    /// Note that this may fail for various reasons, most notably because the repository
+    /// is freshly initialized and doesn't have any commits yet. It could also fail if the
+    /// head does not point to a commit.
+    pub fn head_commit(&self) -> Result<crate::Commit<'_>, crate::reference::head_commit::Error> {
+        Ok(self.head()?.peel_to_commit_in_place()?)
+    }
+
     /// Find the reference with the given partial or full `name`, like `main`, `HEAD`, `heads/branch` or `origin/other`,
     /// or return an error if it wasn't found.
     ///

git-repository/tests/easy/object.rs

@@ -1,23 +1,22 @@
 mod commit {
     use std::cmp::Ordering;
 
-    use git_repository::{Commit, Repository};
     use git_testtools::hex_to_id;
 
     use crate::basic_repo;
 
     #[test]
     fn short_id() -> crate::Result {
         let handle = basic_repo()?;
-        let commit = head_commit(&handle);
+        let commit = handle.head_commit()?;
         assert_eq!(commit.short_id()?.cmp_oid(&commit.id), Ordering::Equal);
         Ok(())
     }
 
     #[test]
     fn tree() -> crate::Result {
         let handle = basic_repo()?;
-        let commit = head_commit(&handle);
+        let commit = handle.head_commit()?;
 
         assert_eq!(commit.tree()?.id, commit.tree_id().expect("id present"));
         assert_eq!(
@@ -30,16 +29,12 @@ mod commit {
     #[test]
     fn decode() -> crate::Result {
         let handle = basic_repo()?;
-        let commit = head_commit(&handle);
+        let commit = handle.head_commit()?;
         assert_eq!(commit.decode()?.message, commit.message_raw()?);
         assert_eq!(commit.decode()?.message(), commit.message()?);
         assert_eq!(commit.decode()?.message, "c2\n");
         Ok(())
     }
-
-    fn head_commit(repo: &Repository) -> Commit<'_> {
-        repo.head().unwrap().peel_to_commit_in_place().unwrap()
-    }
 }
 
 #[test]