Merge pull request #2171 from cruessler/deprecate-in-place-methods-on-head

feat: replace `peel_to_x_in_place` by `peel_to_x` in `gix::types::Head`

Author: Byron

gitoxide-core/src/repository/log.rs

@@ -12,7 +12,7 @@ pub fn log(mut repo: gix::Repository, out: &mut dyn std::io::Write, path: Option
 }
 
 fn log_all(repo: gix::Repository, out: &mut dyn std::io::Write) -> Result<(), anyhow::Error> {
-    let head = repo.head()?.peel_to_commit_in_place()?;
+    let head = repo.head()?.peel_to_commit()?;
     let topo = gix::traverse::commit::topo::Builder::from_iters(&repo.objects, [head.id], None::<Vec<gix::ObjectId>>)
         .build()?;
 

gix/src/clone/checkout.rs

@@ -98,7 +98,7 @@ pub mod main_worktree {
 
             let root_tree_id = match &self.ref_name {
                 Some(reference_val) => Some(repo.find_reference(reference_val)?.peel_to_id()?),
-                None => repo.head()?.try_peel_to_id_in_place()?,
+                None => repo.head()?.try_peel_to_id()?,
             };
 
             let root_tree = match root_tree_id {

gix/src/config/cache/access.rs

@@ -349,7 +349,7 @@ impl Cache {
             if let Ok(mut head) = repo.head() {
                 let ctx = filters.driver_context_mut();
                 ctx.ref_name = head.referent_name().map(|name| name.as_bstr().to_owned());
-                ctx.treeish = head.peel_to_commit_in_place().ok().map(|commit| commit.id);
+                ctx.treeish = head.peel_to_commit().ok().map(|commit| commit.id);
             }
             filters
         };

gix/src/head/peel.rs

@@ -7,8 +7,8 @@ use crate::{
 mod error {
     use crate::{object, reference};
 
-    /// The error returned by [`Head::peel_to_id_in_place()`](super::Head::try_peel_to_id_in_place())
-    /// and [`Head::into_fully_peeled_id()`](super::Head::try_into_peeled_id()).
+    /// The error returned by [`Head::peel_to_id()`](super::Head::try_peel_to_id()) and
+    /// [`Head::into_fully_peeled_id()`](super::Head::try_into_peeled_id()).
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -42,7 +42,7 @@ pub mod into_id {
 pub mod to_commit {
     use crate::object;
 
-    /// The error returned by [`Head::peel_to_commit_in_place()`](super::Head::peel_to_commit_in_place()).
+    /// The error returned by [`Head::peel_to_commit()`](super::Head::peel_to_commit()).
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -55,7 +55,7 @@ pub mod to_commit {
 
 ///
 pub mod to_object {
-    /// The error returned by [`Head::peel_to_object_in_place()`](super::Head::peel_to_object_in_place()).
+    /// The error returned by [`Head::peel_to_object()`](super::Head::peel_to_object()).
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -72,7 +72,7 @@ impl<'repo> Head<'repo> {
     /// The final target is obtained by following symbolic references and peeling tags to their final destination, which
     /// typically is a commit, but can be any object.
     pub fn into_peeled_id(mut self) -> Result<crate::Id<'repo>, into_id::Error> {
-        self.try_peel_to_id_in_place()?;
+        self.try_peel_to_id()?;
         self.id().ok_or_else(|| match self.kind {
             Kind::Symbolic(gix_ref::Reference { name, .. }) | Kind::Unborn(name) => into_id::Error::Unborn { name },
             Kind::Detached { .. } => unreachable!("id can be returned after peeling"),
@@ -84,7 +84,7 @@ impl<'repo> Head<'repo> {
     /// The final target is obtained by following symbolic references and peeling tags to their final destination, which
     /// typically is a commit, but can be any object as well.
     pub fn into_peeled_object(mut self) -> Result<crate::Object<'repo>, to_object::Error> {
-        self.peel_to_object_in_place()
+        self.peel_to_object()
     }
 
     /// Consume this instance and transform it into the final object that it points to, or `Ok(None)` if the `HEAD`
@@ -93,7 +93,7 @@ impl<'repo> Head<'repo> {
     /// The final target is obtained by following symbolic references and peeling tags to their final destination, which
     /// typically is a commit, but can be any object.
     pub fn try_into_peeled_id(mut self) -> Result<Option<crate::Id<'repo>>, Error> {
-        self.try_peel_to_id_in_place()
+        self.try_peel_to_id()
     }
 
     /// Follow the symbolic reference of this head until its target object and peel it by following tag objects until there is no
@@ -103,7 +103,21 @@ impl<'repo> Head<'repo> {
     ///
     /// The final target is obtained by following symbolic references and peeling tags to their final destination, which
     /// typically is a commit, but can be any object.
+    #[deprecated = "Use `try_peel_to_id()` instead"]
     pub fn try_peel_to_id_in_place(&mut self) -> Result<Option<crate::Id<'repo>>, Error> {
+        self.try_peel_to_id()
+    }
+
+    /// Follow the symbolic reference of this head until its target object and peel it by following tag objects until there is no
+    /// more object to follow, and return that object id.
+    ///
+    /// Returns `Ok(None)` if the head is unborn.
+    ///
+    /// The final target is obtained by following symbolic references and peeling tags to their final destination, which
+    /// typically is a commit, but can be any object.
+    ///
+    /// Note that this method mutates `self` in place.
+    pub fn try_peel_to_id(&mut self) -> Result<Option<crate::Id<'repo>>, Error> {
         Ok(Some(match &mut self.kind {
             Kind::Unborn(_name) => return Ok(None),
             Kind::Detached {
@@ -139,12 +153,21 @@ impl<'repo> Head<'repo> {
     /// 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.
+    #[deprecated = "Use `peel_to_object()` instead"]
     pub fn peel_to_object_in_place(&mut self) -> Result<crate::Object<'repo>, to_object::Error> {
-        let id = self
-            .try_peel_to_id_in_place()?
-            .ok_or_else(|| to_object::Error::Unborn {
-                name: self.referent_name().expect("unborn").to_owned(),
-            })?;
+        self.peel_to_object()
+    }
+
+    /// Follow the symbolic reference of this head until its target object and peel it by following tag objects until there is no
+    /// 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.
+    ///
+    /// Note that this method mutates `self` in place.
+    pub fn peel_to_object(&mut self) -> Result<crate::Object<'repo>, to_object::Error> {
+        let id = self.try_peel_to_id()?.ok_or_else(|| to_object::Error::Unborn {
+            name: self.referent_name().expect("unborn").to_owned(),
+        })?;
         id.object()
             .map_err(|err| to_object::Error::Peel(Error::FindExistingObject(err)))
     }
@@ -153,7 +176,18 @@ impl<'repo> Head<'repo> {
     /// 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.
+    #[deprecated = "Use `peel_to_commit()` instead"]
     pub fn peel_to_commit_in_place(&mut self) -> Result<crate::Commit<'repo>, to_commit::Error> {
-        Ok(self.peel_to_object_in_place()?.try_into_commit()?)
+        self.peel_to_commit()
+    }
+
+    /// Follow the symbolic reference of this head until its target object and peel it by following tag objects until there is no
+    /// 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.
+    ///
+    /// Note that this method mutates `self` in place.
+    pub fn peel_to_commit(&mut self) -> Result<crate::Commit<'repo>, to_commit::Error> {
+        Ok(self.peel_to_object()?.try_into_commit()?)
     }
 }

gix/src/repository/mailmap.rs

@@ -36,7 +36,7 @@ impl crate::Repository {
             None => {
                 blob_id = blob_id.or_else(|| {
                     self.head().ok().and_then(|mut head| {
-                        let commit = head.peel_to_commit_in_place().ok()?;
+                        let commit = head.peel_to_commit().ok()?;
                         let tree = commit.tree().ok()?;
                         tree.find_entry(".mailmap").map(|e| e.object_id())
                     })

gix/src/repository/reference.rs

@@ -214,7 +214,7 @@ impl crate::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<'_>, reference::head_commit::Error> {
-        Ok(self.head()?.peel_to_commit_in_place()?)
+        Ok(self.head()?.peel_to_commit()?)
     }
 
     /// Return the tree id the `HEAD` reference currently points to after peeling it fully,

gix/src/repository/submodule.rs

@@ -55,7 +55,7 @@ impl Repository {
                     Some(id) => id,
                     None => match self
                         .head()?
-                        .try_peel_to_id_in_place()?
+                        .try_peel_to_id()?
                         .map(|id| -> Result<Option<_>, submodule::modules::Error> {
                             Ok(id
                                 .object()?

gix/tests/gix/head.rs

@@ -14,8 +14,8 @@ mod peel {
             assert_eq!(repo.head_tree_id()?, commit.tree_id()?);
             assert_eq!(repo.head_tree_id_or_empty()?, commit.tree_id()?);
             assert_eq!(repo.head()?.try_into_peeled_id()?.expect("born"), expected_commit);
-            assert_eq!(repo.head()?.peel_to_object_in_place()?.id, expected_commit);
-            assert_eq!(repo.head()?.try_peel_to_id_in_place()?.expect("born"), expected_commit);
+            assert_eq!(repo.head()?.peel_to_object()?.id, expected_commit);
+            assert_eq!(repo.head()?.try_peel_to_id()?.expect("born"), expected_commit);
         }
         Ok(())
     }