Struct gix::pathspec::Search

pub struct Search {
    pub source: Option<PathBuf>,
    /* private fields */
}

Available on crate feature attributes only.

A lists of pathspec patterns, possibly from a file.

Pathspecs are generally relative to the root of the repository.

Fields

source: Option<PathBuf>

The path from which the patterns were read, or None if the patterns don’t originate in a file on disk.

Implementations

impl Search

Lifecycle

pub fn from_specs( pathspecs: impl IntoIterator<Item = Pattern>, prefix: Option<&Path>, root: &Path, ) -> Result<Search, Error>

Create a search from ready-made pathspecs, and normalize them with prefix and root. root is the absolute path to the worktree root, if available, or the git_dir in case of bare repositories. If pathspecs doesn’t yield any pattern, we will match everything automatically. If prefix is also provided and not empty, an artificial pattern will be added to yield all.

pub fn into_patterns(self) -> impl Iterator<Item = Pattern>

Obtain ownership of the normalized pathspec patterns that were used for the search.

impl Search

Access

pub fn patterns(&self) -> impl ExactSizeIterator

Return an iterator over the patterns that participate in the search.

pub fn common_prefix(&self) -> &BStr

Return the portion of the prefix among all of the pathspecs involved in this search, or an empty string if there is none. It doesn’t have to end at a directory boundary though, nor does it denote a directory.

Note that the common_prefix is always matched case-sensitively, and it is useful to skip large portions of input. Further, excluded pathspecs don’t participate which makes this common prefix inclusive. To work correctly though, one will have to additionally match paths that have the common prefix with that pathspec itself to assure it is not excluded.

pub fn prefix_directory(&self) -> Cow<'_, Path>

Returns a guaranteed-to-be-directory that is shared across all pathspecs, in its repository-relative form. Thus to be valid, it must be joined with the worktree root. The prefix is the CWD within a worktree passed when normalizing the pathspecs.

Note that it may well be that the directory isn’t available even though there is a common_prefix(), as they are not quire the same.

See also: maybe_prefix_directory().

pub fn longest_common_directory(&self) -> Option<Cow<'_, Path>>

Return the longest possible common directory that is shared across all non-exclusive pathspecs. It must be tested for existence by joining it with a suitable root before being able to use it. Note that if it is returned, it’s guaranteed to be longer than the prefix-directory.

Returns None if the returned directory would be empty, or if all pathspecs are exclusive.

impl Search

pub fn pattern_matching_relative_path( &mut self, relative_path: &BStr, is_dir: Option<bool>, attributes: &mut dyn FnMut(&BStr, Case, bool, &mut Outcome) -> bool, ) -> Option<Match<'_>>

Return the first Match of relative_path, or None. is_dir is true if relative_path is a directory, or assumed false if None. attributes is called as attributes(relative_path, case, is_dir, outcome) -> has_match to obtain for attributes for relative_path, if the underlying pathspec defined an attribute filter, to be stored in outcome, returning true if there was a match. All attributes of the pathspec have to be present in the defined value for the pathspec to match.

Note that relative_path is expected to be starting at the same root as is assumed for this pattern, see Pattern::normalize(). Further, empty searches match everything, as if : was provided.

Deviation

The case-sensitivity of the attribute match is controlled by the sensitivity of the pathspec, instead of being based on the case folding settings of the repository. That way we assure that the matching is consistent. Higher-level crates should control this default case folding of pathspecs when instantiating them, which is when they can set it to match the repository setting for more natural behaviour when, for instance, adding files to a repository: as it stands, on a case-insensitive file system, touch File && git add file will not add the file, but also not error.

pub fn can_match_relative_path( &self, relative_path: &BStr, is_dir: Option<bool>, ) -> bool

As opposed to Self::pattern_matching_relative_path(), this method will return true for a possibly partial relative_path if this pathspec could match by looking at the shortest shared prefix only.

This is useful if relative_path is a directory leading up to the item that is going to be matched in full later. Note that it should not end with / to indicate it’s a directory, rather, use is_dir to indicate this. is_dir is true if relative_path is a directory. If None, the fact that a pathspec might demand a directory match is ignored. Returns false if this pathspec has no chance of ever matching relative_path.

pub fn directory_matches_prefix( &self, relative_path: &BStr, leading: bool, ) -> bool

Returns true if relative_path matches the prefix of this pathspec.

For example, the relative path d matches d/, d*/, d/ and d/*, but not d/d/* or dir. When leading is true, then d matches d/d as well. Thus, relative_path must may be partially included in pathspec, otherwise it has to be fully included.

Trait Implementations

impl Clone for Search

fn clone(&self) -> Search

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Search

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

Formats the value using the given formatter.