Struct gix::Tree

pub struct Tree<'repo> {
    pub id: ObjectId,
    pub data: Vec<u8>,
    /* private fields */
}

A decoded tree object with access to its owning repository.

Fields

id: ObjectId

The id of the tree

data: Vec<u8>

The fully decoded tree data

Implementations

impl<'repo> Tree<'repo>

Diffing

pub fn changes<'a>(&'a self) -> Result<Platform<'a, 'repo>, Error>

Available on crate feature blob-diff only.

Return a platform to see the changes needed to create other trees, for instance.

Performance

It’s highly recommended to set an object cache to avoid extracting the same object multiple times. By default, similar to git diff, rename tracking will be enabled if it is not configured.

Note that if a clone with --filter=blob=none was created, rename tracking may fail as it might try to access blobs to compute a similarity metric. Thus, it’s more compatible to turn rewrite tracking off using Platform::track_rewrites().

impl<'repo> Tree<'repo>

Traversal

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

Obtain a platform for initiating a variety of traversals.

impl<'repo> Tree<'repo>

pub fn iter(&self) -> impl Iterator<Item = Result<EntryRef<'repo, '_>, Error>>

Return an iterator over tree entries to obtain information about files and directories this tree contains.

impl<'repo> Tree<'repo>

Initialization

pub fn from_data( id: impl Into<ObjectId>, data: Vec<u8>, repo: &'repo Repository ) -> Self

Obtain a tree instance by handing in all components that it is made up of.

impl<'repo> Tree<'repo>

Access

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

Return this tree’s identifier.

pub fn decode(&self) -> Result<TreeRef<'_>, Error>

Parse our tree data and return the parse tree for direct access to its entries.

pub fn find_entry( &self, name: impl PartialEq<BStr> ) -> Option<EntryRef<'repo, '_>>

Find the entry named name by iteration, or return None if it wasn’t found.

pub fn lookup_entry<I, P>( &self, path: I, buf: &mut Vec<u8> ) -> Result<Option<Entry<'repo>>, Error>

where I: IntoIterator<Item = P>, P: PartialEq<BStr>,

Follow a sequence of path components starting from this instance, and look them up one by one until the last component is looked up and its tree entry is returned. Use buf as temporary location for sub-trees to avoid allocating a temporary buffer for each lookup.

Performance Notes

Searching tree entries is currently done in sequence, which allows to the search to be allocation free. It would be possible to reuse a vector and use a binary search instead, which might be able to improve performance over all. However, a benchmark should be created first to have some data and see which trade-off to choose here.

pub fn peel_to_entry<I, P>( &mut self, path: I ) -> Result<Option<Entry<'repo>>, Error>

where I: IntoIterator<Item = P>, P: PartialEq<BStr>,

Follow a sequence of path components starting from this instance, and look them up one by one until the last component is looked up and its tree entry is returned, while changing this instance to point to the last seen tree. Note that if the lookup fails, it may be impossible to continue making lookups through this tree. It’s useful to have this function to be able to reuse the internal buffer of the tree.

Performance Notes

Searching tree entries is currently done in sequence, which allows to the search to be allocation free. It would be possible to reuse a vector and use a binary search instead, which might be able to improve performance over all. However, a benchmark should be created first to have some data and see which trade-off to choose here.

pub fn lookup_entry_by_path( &self, relative_path: impl AsRef<Path>, buf: &mut Vec<u8> ) -> Result<Option<Entry<'repo>>, Error>

Like Self::lookup_entry(), but takes a Path directly via relative_path, a path relative to this tree.

Note

If any path component contains illformed UTF-8 and thus can’t be converted to bytes on platforms which can’t do so natively, the returned component will be empty which makes the lookup fail.

pub fn peel_to_entry_by_path( &mut self, relative_path: impl AsRef<Path> ) -> Result<Option<Entry<'repo>>, Error>

Like Self::peel_to_entry(), but takes a Path directly via relative_path, a path relative to this tree.

Note

If any path component contains illformed UTF-8 and thus can’t be converted to bytes on platforms which can’t do so natively, the returned component will be empty which makes the lookup fail.

impl Tree<'_>

Remove Lifetime

pub fn detached(&self) -> ObjectDetached

Create an owned instance of this object, copying our data in the process.

pub fn detach(self) -> ObjectDetached

Sever the connection to the Repository and turn this instance into a standalone object.

pub fn take_data(&mut self) -> Vec<u8>

Retrieve this instance’s encoded data, leaving its own data empty.

This method works around the immovability of members of this type.

Trait Implementations

impl<'repo> Clone for Tree<'repo>

fn clone(&self) -> Tree<'repo>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'r> Debug for Tree<'r>

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

Formats the value using the given formatter.

impl<'a> Drop for Tree<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'repo> From<Tree<'repo>> for ObjectDetached

fn from(v: Tree<'repo>) -> Self

Converts to this type from the input type.

impl<'repo> TryFrom<Object<'repo>> for Tree<'repo>

type Error = Object<'repo>

The type returned in the event of a conversion error.

fn try_from(value: Object<'repo>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Tree<'_>> for Tree

type Error = Error

The type returned in the event of a conversion error.

fn try_from(t: Tree<'_>) -> Result<Self, Self::Error>

Performs the conversion.