Merge pull request #2174 from cruessler/deprecate-in-place-methods

feat: replace `Reference::peel_to_id_in_place_packed`

Author: Byron

gix-ref/src/lib.rs

@@ -148,7 +148,7 @@ pub enum Kind {
     Object,
     /// A ref that points to another reference, adding a level of indirection.
     ///
-    /// It can be resolved to an id using the [`peel_in_place_to_id()`][`crate::file::ReferenceExt::peel_to_id_in_place()`] method.
+    /// It can be resolved to an id using the [`peel_to_id()`][`crate::file::ReferenceExt::peel_to_id()`] method.
     Symbolic,
 }
 

gix-ref/src/peel.rs

@@ -2,7 +2,7 @@
 pub mod to_id {
     use gix_object::bstr::BString;
 
-    /// The error returned by [`crate::file::ReferenceExt::peel_to_id_in_place()`].
+    /// The error returned by [`crate::file::ReferenceExt::peel_to_id()`].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -21,7 +21,7 @@ pub mod to_object {
 
     use crate::file;
 
-    /// The error returned by [`file::ReferenceExt::follow_to_object_in_place_packed()`].
+    /// The error returned by [`file::ReferenceExt::follow_to_object_packed()`].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

gix-ref/src/raw.rs

@@ -12,7 +12,7 @@ pub struct Reference {
     pub target: Target,
     /// The fully peeled object to which this reference ultimately points to after following all symbolic refs and all annotated
     /// tags. Only guaranteed to be set after
-    /// [`Reference::peel_to_id_in_place()`](crate::file::ReferenceExt) was called or if this reference originated
+    /// [`Reference::peel_to_id()`](crate::file::ReferenceExt::peel_to_id) was called or if this reference originated
     /// from a packed ref.
     pub peeled: Option<ObjectId>,
 }

gix-ref/src/store/file/raw_ext.rs

@@ -58,8 +58,8 @@ pub trait ReferenceExt: Sealed {
         packed: Option<&packed::Buffer>,
     ) -> Result<ObjectId, peel::to_id::Error>;
 
-    /// Like [`ReferenceExt::peel_to_id_in_place()`], but with support for a known stable `packed` buffer
-    /// to use for resolving symbolic links.
+    /// Like [`ReferenceExt::peel_to_id()`], but with support for a known stable `packed` buffer to
+    /// use for resolving symbolic links.
     fn peel_to_id_packed(
         &mut self,
         store: &file::Store,

gix/src/reference/errors.rs

@@ -22,8 +22,8 @@ pub mod edit {
 
 ///
 pub mod peel {
-    /// The error returned by [`Reference::peel_to_id_in_place(…)`](crate::Reference::peel_to_id_in_place()) and
-    /// [`Reference::into_fully_peeled_id(…)`](crate::Reference::into_fully_peeled_id()).
+    /// The error returned by [`Reference::peel_to_id()`](crate::Reference::peel_to_id()) and
+    /// [`Reference::into_fully_peeled_id()`](crate::Reference::into_fully_peeled_id()).
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

gix/src/reference/iter.rs

@@ -90,7 +90,7 @@ impl<'repo> Platform<'repo> {
 impl Iter<'_, '_> {
     /// Automatically peel references before yielding them during iteration.
     ///
-    /// This has the same effect as using `iter.map(|r| {r.peel_to_id_in_place(); r})`.
+    /// This has the same effect as using `iter.map(|r| {r.peel_to_id(); r})`.
     ///
     /// # Note
     ///

gix/src/reference/mod.rs

@@ -81,8 +81,8 @@ impl<'repo> Reference<'repo> {
     /// This is useful to learn where this reference is ultimately pointing to after following
     /// the chain of symbolic refs and annotated tags.
     ///
-    /// Note that this method mutates `self` in place if it does not already point to non-symbolic
-    /// object.
+    /// Note that this method mutates `self` in place if it does not already point to a
+    /// non-symbolic object.
     pub fn peel_to_id(&mut self) -> Result<Id<'repo>, peel::Error> {
         let oid = self.inner.peel_to_id(&self.repo.refs, &self.repo.objects)?;
         Ok(Id::from_id(oid, self.repo))
@@ -93,6 +93,7 @@ impl<'repo> Reference<'repo> {
     ///
     /// This is useful to learn where this reference is ultimately pointing to after following
     /// the chain of symbolic refs and annotated tags.
+    #[deprecated = "Use `peel_to_id_packed()` instead"]
     pub fn peel_to_id_in_place_packed(
         &mut self,
         packed: Option<&gix_ref::packed::Buffer>,
@@ -103,6 +104,21 @@ impl<'repo> Reference<'repo> {
         Ok(Id::from_id(oid, self.repo))
     }
 
+    /// Follow all symbolic targets this reference might point to and peel all annotated tags
+    /// to their first non-tag target, and return it, reusing the `packed` buffer if available.
+    ///
+    /// This is useful to learn where this reference is ultimately pointing to after following
+    /// the chain of symbolic refs and annotated tags.
+    ///
+    /// Note that this method mutates `self` in place if it does not already point to a
+    /// non-symbolic object.
+    pub fn peel_to_id_packed(&mut self, packed: Option<&gix_ref::packed::Buffer>) -> Result<Id<'repo>, peel::Error> {
+        let oid = self
+            .inner
+            .peel_to_id_packed(&self.repo.refs, &self.repo.objects, packed)?;
+        Ok(Id::from_id(oid, self.repo))
+    }
+
     /// Similar to [`peel_to_id()`](Reference::peel_to_id()), but consumes this instance.
     pub fn into_fully_peeled_id(mut self) -> Result<Id<'repo>, peel::Error> {
         self.peel_to_id()
@@ -112,7 +128,7 @@ impl<'repo> Reference<'repo> {
     /// its type matches the given `kind`. It's an error to try to peel to a kind that this ref doesn't point to.
     ///
     /// Note that this ref will point to the first target object afterward, which may be a tag. This is different
-    /// from [`peel_to_id_in_place()`](Self::peel_to_id_in_place()) where it will point to the first non-tag object.
+    /// from [`peel_to_id()`](Self::peel_to_id()) where it will point to the first non-tag object.
     ///
     /// Note that `git2::Reference::peel` does not "peel in place", but returns a new object
     /// instead.