pub struct Search {
pub source: Option<PathBuf>,
/* private fields */
}
Expand description
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§
Source§impl Search
impl Search
Lifecycle
Sourcepub fn from_specs(
pathspecs: impl IntoIterator<Item = Pattern>,
prefix: Option<&Path>,
root: &Path,
) -> Result<Self, Error>
pub fn from_specs( pathspecs: impl IntoIterator<Item = Pattern>, prefix: Option<&Path>, root: &Path, ) -> Result<Self, 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.
Sourcepub fn into_patterns(self) -> impl Iterator<Item = Pattern>
pub fn into_patterns(self) -> impl Iterator<Item = Pattern>
Obtain ownership of the normalized pathspec patterns that were used for the search.
Source§impl Search
impl Search
Sourcepub 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<'_>>
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.
Sourcepub fn can_match_relative_path(
&self,
relative_path: &BStr,
is_dir: Option<bool>,
) -> bool
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
.
Sourcepub fn directory_matches_prefix(
&self,
relative_path: &BStr,
leading: bool,
) -> bool
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.
Source§impl Search
impl Search
Access
Sourcepub fn patterns(&self) -> impl ExactSizeIterator<Item = &Pattern> + '_
pub fn patterns(&self) -> impl ExactSizeIterator<Item = &Pattern> + '_
Return an iterator over the patterns that participate in the search.
Sourcepub fn common_prefix(&self) -> &BStr
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.
Sourcepub fn prefix_directory(&self) -> Cow<'_, Path>
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()
.
Sourcepub fn longest_common_directory(&self) -> Option<Cow<'_, Path>>
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.