feat: Repository::head_id() (#364)

A long-needed shortcut.

Author: Byron

git-repository/src/head.rs

@@ -124,7 +124,8 @@ pub mod peel {
 
     use crate::head::Kind;
 
-    mod peel_to_commit {
+    ///
+    pub mod to_commit {
         use crate::object;
 
         /// The error returned by [Head::peel_to_commit_in_place()][super::Head::peel_to_commit_in_place()].
@@ -192,14 +193,12 @@ 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<crate::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<crate::Commit<'repo>, to_commit::Error> {
+            let id = self.peel_to_id_in_place().ok_or_else(|| 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)))
+                .map_err(|err| to_commit::Error::Peel(Error::FindExistingObject(err)))
                 .and_then(|object| object.try_into_commit().map_err(Into::into))
         }
 

git-repository/src/reference/errors.rs

@@ -28,6 +28,21 @@ pub mod peel {
     }
 }
 
+///
+pub mod head_id {
+    /// The error returned by [Repository::head_id(…)][crate::Repository::head_id()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        Head(#[from] crate::reference::find::existing::Error),
+        #[error(transparent)]
+        PeelToId(#[from] crate::head::peel::Error),
+        #[error("Branch '{name}' does not have any commits")]
+        Unborn { name: git_ref::FullName },
+    }
+}
+
 ///
 pub mod find {
     ///

git-repository/src/reference/mod.rs

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

git-repository/src/repository/reference.rs

@@ -184,6 +184,22 @@ impl crate::Repository {
         .attach(self))
     }
 
+    /// Resolve the head, 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.
+    ///
+    /// Also note that the returned id is likely to point to a commit, but could also
+    /// point to a tree or blob. It won't, however, point to a tag as these are always peeled.
+    pub fn head_id(&self) -> Result<crate::Id<'_>, crate::reference::head_id::Error> {
+        let mut head = self.head()?;
+        head.peel_to_id_in_place()
+            .ok_or_else(|| crate::reference::head_id::Error::Unborn {
+                name: head.referent_name().expect("unborn").to_owned(),
+            })?
+            .map_err(Into::into)
+    }
+
     /// 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/ext/object.rs

@@ -45,7 +45,7 @@ mod tag {
     #[test]
     fn simple() -> crate::Result {
         let (repo, _keep) = crate::repo_rw("make_basic_repo.sh")?;
-        let current_head_id = repo.head()?.peeled()?.id().expect("born");
+        let current_head_id = repo.head_id()?;
         let message = "a multi\nline message";
         let tag_ref = repo.tag(
             "v1.0.0",