Struct Stack

pub struct Stack { /* private fields */ }

A cache for efficiently executing operations on directories and files which are encountered in sorted order. That way, these operations can be re-used for subsequent invocations in the same directory.

This cache can be configured to create directories efficiently, read git-ignore files and git-attribute files, in any combination.

A cache for directory creation to reduce the amount of stat calls when creating directories safely, that is without following symlinks that might be on the way.

As a special case, it offers a ‘prefix’ which (by itself) is assumed to exist and may contain symlinks. Everything past that prefix boundary must not contain a symlink. We do this by allowing any input path.

Another added benefit is its ability to store the path of full path of the entry to which leading directories are to be created to avoid allocating memory.

For this to work, it remembers the last ‘good’ path to a directory and assumes that all components of it are still valid, too. As directories are created, the cache will be adjusted to reflect the latest seen directory.

The caching is only useful if consecutive calls to create a directory are using a sorted list of entries.

Implementations

impl Stack

Attribute matching specific methods

pub fn attribute_matches(&self) -> Outcome

Available on crate feature attributes only.

Creates a new container to store match outcomes for all attribute matches.

Panics

If attributes aren’t configured.

pub fn selected_attribute_matches<'a>( &self, given: impl IntoIterator<Item = impl Into<&'a str>>, ) -> Outcome

Available on crate feature attributes only.

Creates a new container to store match outcomes for the given attributes.

Panics

If attributes aren’t configured.

pub fn attributes_collection(&self) -> &MetadataCollection

Available on crate feature attributes only.

Return the metadata collection that enables initializing attribute match outcomes as done in attribute_matches() or selected_attribute_matches()

Panics

If attributes aren’t configured.

impl Stack

Initialization

pub fn new( worktree_root: impl Into<PathBuf>, state: State, case: Case, buf: Vec<u8>, id_mappings: Vec<(BString, ObjectId)>, ) -> Self

Create a new instance with worktree_root being the base for all future paths we match. state defines the capabilities of the cache. The case configures attribute and exclusion case sensitivity at query time, which should match the case that state might be configured with. buf is used when reading files, and id_mappings should have been created with State::id_mappings_from_index().

pub fn from_state_and_ignore_case( root: impl Into<PathBuf>, ignore_case: bool, state: State, index: &State, path_backing: &PathStorageRef, ) -> Self

Create a new stack that takes into consideration the ignore_case result of a filesystem probe in root. It takes a configured state to control what it can do, while initializing attribute or ignore files that are to be queried from the ODB using index and path_backing.

This is the easiest way to correctly setup a stack.

impl Stack

Entry points for attribute query

pub fn at_path( &mut self, relative: impl AsRef<Path>, mode: Option<Mode>, objects: &dyn Find, ) -> Result<Platform<'_>>

Append the relative path to the root directory of the cache and efficiently create leading directories, while assuring that no symlinks are in that path. Unless mode is known with Some(gix_index::entry::Mode::DIR|COMMIT), then relative points to a directory itself in which case the entire resulting path is created as directory. If it’s not known it is assumed to be a file. objects maybe used to lookup objects from an id mapping, with mappnigs

Provide access to cached information for that relative path via the returned platform.

pub fn at_entry<'r>( &mut self, relative: impl Into<&'r BStr>, mode: Option<Mode>, objects: &dyn Find, ) -> Result<Platform<'_>>

Obtain a platform for lookups from a repo-relative path, typically obtained from an index entry. mode should reflect the kind of item set here, or left at None if unknown. objects maybe used to lookup objects from an id mapping. All effects are similar to at_path().

If relative ends with / and mode is None, it is automatically assumed set to be a directory.

impl Stack

Mutation

pub fn take_statistics(&mut self) -> Statistics

Reset the statistics after returning them.

pub fn state_mut(&mut self) -> &mut State

Return our state for applying changes.

pub fn set_case(&mut self, case: Case) -> &mut Self

Change the case of the next match to the given one.

impl Stack

Access

pub fn statistics(&self) -> &Statistics

Return the statistics we gathered thus far.

pub fn state(&self) -> &State

Return the state for introspection.

pub fn base(&self) -> &Path

Return the base path against which all entries or paths should be relative to when querying.

Note that this path may not be canonicalized.

Trait Implementations

impl Clone for Stack

fn clone(&self) -> Stack

Returns a copy of the value.

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

Performs copy-assignment from source.