diff --git a/gix-ref/src/lib.rs b/gix-ref/src/lib.rs index 1d9eded44cc..a1aa5952fa4 100644 --- a/gix-ref/src/lib.rs +++ b/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, } diff --git a/gix-ref/src/peel.rs b/gix-ref/src/peel.rs index 3a7011ab7c2..fae321aa23f 100644 --- a/gix-ref/src/peel.rs +++ b/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 { diff --git a/gix-ref/src/raw.rs b/gix-ref/src/raw.rs index ccbf33439aa..d476bd17cf9 100644 --- a/gix-ref/src/raw.rs +++ b/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, } diff --git a/gix-ref/src/store/file/raw_ext.rs b/gix-ref/src/store/file/raw_ext.rs index 4fca9b33ee7..fc0a3a9f378 100644 --- a/gix-ref/src/store/file/raw_ext.rs +++ b/gix-ref/src/store/file/raw_ext.rs @@ -58,8 +58,8 @@ pub trait ReferenceExt: Sealed { packed: Option<&packed::Buffer>, ) -> Result; - /// 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, diff --git a/gix/src/reference/errors.rs b/gix/src/reference/errors.rs index efd2b1721ee..f8d3c187966 100644 --- a/gix/src/reference/errors.rs +++ b/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 { diff --git a/gix/src/reference/iter.rs b/gix/src/reference/iter.rs index 29076417fcd..0d0831ee943 100644 --- a/gix/src/reference/iter.rs +++ b/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 /// diff --git a/gix/src/reference/mod.rs b/gix/src/reference/mod.rs index 7f944d7168a..937795cca78 100644 --- a/gix/src/reference/mod.rs +++ b/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, 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, 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, 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.