Struct Reference

pub struct Reference<'r> {
    pub inner: Reference,
    /* private fields */
}

A reference that points to an object or reference, with access to its source repository.

Note that these are snapshots and won’t recognize if they are stale.

Fields

inner: Reference

The actual reference data

Implementations

impl<'repo> Reference<'repo>

Remotes

pub fn remote_name(&self, direction: Direction) -> Option<Name<'_>>

Find the name of our remote for direction as configured in branch.<name>.remote|pushRemote respectively. Return None if no remote is configured.

See also Repository::branch_remote_name() for more details.

pub fn remote( &self, direction: Direction, ) -> Option<Result<Remote<'repo>, Error>>

Find the remote along with all configuration associated with it suitable for handling this reference.

See also Repository::branch_remote() for more details.

pub fn remote_ref_name( &self, direction: Direction, ) -> Option<Result<Cow<'_, FullNameRef>, Error>>

Return the name of this reference on the remote side.

See Repository::branch_remote_ref_name() for details.

pub fn remote_tracking_ref_name( &self, direction: Direction, ) -> Option<Result<Cow<'_, FullNameRef>, Error>>

Return the name of the reference that tracks this reference on the remote side.

See Repository::branch_remote_tracking_ref_name() for details.

impl Reference<'_>

pub fn log_iter(&self) -> Platform<'_, '_>

Return a platform for obtaining iterators over reference logs.

pub fn log_exists(&self) -> bool

Return true if a reflog is present for this reference.

impl Reference<'_>

pub fn set_target_id( &mut self, id: impl Into<ObjectId>, reflog_message: impl Into<BString>, ) -> Result<(), Error>

Set the id of this direct reference to id and use reflog_message for the reflog (if enabled in the repository).

Note that the operation will fail on symbolic references, to change their type use the lower level reference database, or if the reference was deleted or changed in the mean time. Furthermore, refrain from using this method for more than a one-off change as it creates a transaction for each invocation. If multiple reference should be changed, use Repository::edit_references() or the lower level reference database instead.

impl Reference<'_>

pub fn delete(&self) -> Result<(), Error>

Delete this reference or fail if it was changed since last observed. Note that this instance remains available in memory but probably shouldn’t be used anymore.

impl<'repo> Reference<'repo>

Access

pub fn try_id(&self) -> Option<Id<'repo>>

Returns the attached id we point to, or None if this is a symbolic ref.

pub fn id(&self) -> Id<'repo>

Returns the attached id we point to, or panic if this is a symbolic ref.

pub fn target(&self) -> TargetRef<'_>

Return the target to which this reference points to.

pub fn name(&self) -> &FullNameRef

Return the reference’s full name.

pub fn detach(self) -> Reference

Turn this instances into a stand-alone reference.

impl<'repo> Reference<'repo>

Peeling

pub fn peel_to_id_in_place(&mut self) -> Result<Id<'repo>, Error>

Follow all symbolic targets this reference might point to and peel all annotated tags to their first non-tag target, and return it,

This is useful to learn where this reference is ultimately pointing to after following the chain of symbolic refs and annotated tags.

pub fn peel_to_id_in_place_packed( &mut self, packed: Option<&Buffer>, ) -> Result<Id<'repo>, Error>

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.

pub fn into_fully_peeled_id(self) -> Result<Id<'repo>, Error>

Similar to peel_to_id_in_place(), but consumes this instance.

pub fn peel_to_kind(&mut self, kind: Kind) -> Result<Object<'repo>, Error>

Follow this reference’s target until it points at an object directly, and peel that object until 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() where it will point to the first non-tag object.

pub fn peel_to_commit(&mut self) -> Result<Commit<'repo>, Error>

Peel this ref until the first commit.

For details, see peel_to_kind().

pub fn peel_to_tag(&mut self) -> Result<Tag<'repo>, Error>

Peel this ref until the first annotated tag.

For details, see peel_to_kind().

pub fn peel_to_tree(&mut self) -> Result<Tree<'repo>, Error>

Peel this ref until the first tree.

For details, see peel_to_kind().

pub fn peel_to_blob(&mut self) -> Result<Blob<'repo>, Error>

Peel this ref until it points to a blob. Note that this is highly uncommon to happen as it would require an annotated tag to point to a blob, instead of a commit.

For details, see peel_to_kind().

pub fn peel_to_kind_packed( &mut self, kind: Kind, packed: Option<&Buffer>, ) -> Result<Object<'repo>, Error>

Like peel_to_kind(), but allows to provide packed for best possible performance when peeling many refs.

pub fn follow_to_object(&mut self) -> Result<Id<'repo>, Error>

Follow all symbolic references we point to up to the first object, which is typically (but not always) a tag, returning its id. After this call, this ref will be pointing to an object directly, but may still not consider itself ‘peeled’ unless a symbolic target ref was looked up from packed-refs.

pub fn follow_to_object_packed( &mut self, packed: Option<&Buffer>, ) -> Result<Id<'repo>, Error>

Like follow_to_object, but can be used for repeated calls as it won’t look up packed each time, but can reuse it instead.

pub fn follow(&self) -> Option<Result<Reference<'repo>, Error>>

Follow this symbolic reference one level and return the ref it refers to.

Returns None if this is not a symbolic reference, hence the leaf of the chain.

Trait Implementations

impl<'r> Clone for Reference<'r>

fn clone(&self) -> Reference<'r>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Reference<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.