Struct git2::Reference

source ·
pub struct Reference<'repo> { /* private fields */ }
Expand description

A structure to represent a git reference.

Implementations§

source§

impl<'repo> Reference<'repo>

source

pub fn is_valid_name(refname: &str) -> bool

Ensure the reference name is well-formed.

Validation is performed as if ReferenceFormat::ALLOW_ONELEVEL was given to Reference::normalize_name. No normalization is performed, however.

use git2::Reference;

assert!(Reference::is_valid_name("HEAD"));
assert!(Reference::is_valid_name("refs/heads/main"));

// But:
assert!(!Reference::is_valid_name("main"));
assert!(!Reference::is_valid_name("refs/heads/*"));
assert!(!Reference::is_valid_name("foo//bar"));
source

pub fn normalize_name( refname: &str, flags: ReferenceFormat, ) -> Result<String, Error>

Normalize reference name and check validity.

This will normalize the reference name by collapsing runs of adjacent slashes between name components into a single slash. It also validates the name according to the following rules:

  1. If ReferenceFormat::ALLOW_ONELEVEL is given, the name may contain only capital letters and underscores, and must begin and end with a letter. (e.g. “HEAD”, “ORIG_HEAD”).
  2. The flag ReferenceFormat::REFSPEC_SHORTHAND has an effect only when combined with ReferenceFormat::ALLOW_ONELEVEL. If it is given, “shorthand” branch names (i.e. those not prefixed by refs/, but consisting of a single word without / separators) become valid. For example, “main” would be accepted.
  3. If ReferenceFormat::REFSPEC_PATTERN is given, the name may contain a single * in place of a full pathname component (e.g. foo/*/bar, foo/bar*).
  4. Names prefixed with “refs/” can be almost anything. You must avoid the characters ‘~’, ‘^’, ‘:’, ‘\’, ‘?’, ‘[’, and ‘*’, and the sequences “..” and “@{” which have special meaning to revparse.

If the reference passes validation, it is returned in normalized form, otherwise an Error with ErrorCode::InvalidSpec is returned.

use git2::{Reference, ReferenceFormat};

assert_eq!(
    Reference::normalize_name(
        "foo//bar",
        ReferenceFormat::NORMAL
    )
    .unwrap(),
    "foo/bar".to_owned()
);

assert_eq!(
    Reference::normalize_name(
        "HEAD",
        ReferenceFormat::ALLOW_ONELEVEL
    )
    .unwrap(),
    "HEAD".to_owned()
);

assert_eq!(
    Reference::normalize_name(
        "refs/heads/*",
        ReferenceFormat::REFSPEC_PATTERN
    )
    .unwrap(),
    "refs/heads/*".to_owned()
);

assert_eq!(
    Reference::normalize_name(
        "main",
        ReferenceFormat::ALLOW_ONELEVEL | ReferenceFormat::REFSPEC_SHORTHAND
    )
    .unwrap(),
    "main".to_owned()
);
source

pub fn raw(&self) -> *mut git_reference

Get access to the underlying raw pointer.

source

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

Delete an existing reference.

This method works for both direct and symbolic references. The reference will be immediately removed on disk.

This function will return an error if the reference has changed from the time it was looked up.

source

pub fn is_branch(&self) -> bool

Check if a reference is a local branch.

source

pub fn is_note(&self) -> bool

Check if a reference is a note.

source

pub fn is_remote(&self) -> bool

Check if a reference is a remote tracking branch

source

pub fn is_tag(&self) -> bool

Check if a reference is a tag

source

pub fn kind(&self) -> Option<ReferenceType>

Get the reference type of a reference.

If the type is unknown, then None is returned.

source

pub fn name(&self) -> Option<&str>

Get the full name of a reference.

Returns None if the name is not valid utf-8.

source

pub fn name_bytes(&self) -> &[u8]

Get the full name of a reference.

source

pub fn shorthand(&self) -> Option<&str>

Get the full shorthand of a reference.

This will transform the reference name into a name “human-readable” version. If no shortname is appropriate, it will return the full name.

Returns None if the shorthand is not valid utf-8.

source

pub fn shorthand_bytes(&self) -> &[u8]

Get the full shorthand of a reference.

source

pub fn target(&self) -> Option<Oid>

Get the OID pointed to by a direct reference.

Only available if the reference is direct (i.e. an object id reference, not a symbolic one).

source

pub fn target_peel(&self) -> Option<Oid>

Return the peeled OID target of this reference.

This peeled OID only applies to direct references that point to a hard Tag object: it is the result of peeling such Tag.

source

pub fn symbolic_target(&self) -> Option<&str>

Get full name to the reference pointed to by a symbolic reference.

May return None if the reference is either not symbolic or not a valid utf-8 string.

source

pub fn symbolic_target_bytes(&self) -> Option<&[u8]>

Get full name to the reference pointed to by a symbolic reference.

Only available if the reference is symbolic.

source

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

Resolve a symbolic reference to a direct reference.

This method iteratively peels a symbolic reference until it resolves to a direct reference to an OID.

If a direct reference is passed as an argument, a copy of that reference is returned.

source

pub fn peel(&self, kind: ObjectType) -> Result<Object<'repo>, Error>

Peel a reference to an object

This method recursively peels the reference until it reaches an object of the specified type.

source

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

Peel a reference to a blob

This method recursively peels the reference until it reaches a blob.

source

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

Peel a reference to a commit

This method recursively peels the reference until it reaches a commit.

source

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

Peel a reference to a tree

This method recursively peels the reference until it reaches a tree.

source

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

Peel a reference to a tag

This method recursively peels the reference until it reaches a tag.

source

pub fn rename( &mut self, new_name: &str, force: bool, msg: &str, ) -> Result<Reference<'repo>, Error>

Rename an existing reference.

This method works for both direct and symbolic references.

If the force flag is not enabled, and there’s already a reference with the given name, the renaming will fail.

source

pub fn set_target( &mut self, id: Oid, reflog_msg: &str, ) -> Result<Reference<'repo>, Error>

Conditionally create a new reference with the same name as the given reference but a different OID target. The reference must be a direct reference, otherwise this will fail.

The new reference will be written to disk, overwriting the given reference.

source

pub fn symbolic_set_target( &mut self, target: &str, reflog_msg: &str, ) -> Result<Reference<'repo>, Error>

Create a new reference with the same name as the given reference but a different symbolic target. The reference must be a symbolic reference, otherwise this will fail.

The new reference will be written to disk, overwriting the given reference.

The target name will be checked for validity. See Repository::reference_symbolic for rules about valid names.

The message for the reflog will be ignored if the reference does not belong in the standard set (HEAD, branches and remote-tracking branches) and it does not have a reflog.

Trait Implementations§

source§

impl<'repo> Drop for Reference<'repo>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl<'repo> Ord for Reference<'repo>

source§

fn cmp(&self, other: &Reference<'repo>) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
source§

impl<'repo> PartialEq for Reference<'repo>

source§

fn eq(&self, other: &Reference<'repo>) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl<'repo> PartialOrd for Reference<'repo>

source§

fn partial_cmp(&self, other: &Reference<'repo>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

impl<'repo> Eq for Reference<'repo>

Auto Trait Implementations§

§

impl<'repo> Freeze for Reference<'repo>

§

impl<'repo> RefUnwindSafe for Reference<'repo>

§

impl<'repo> !Send for Reference<'repo>

§

impl<'repo> !Sync for Reference<'repo>

§

impl<'repo> Unpin for Reference<'repo>

§

impl<'repo> UnwindSafe for Reference<'repo>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.