Struct ignore::gitignore::Gitignore

pub struct Gitignore { /* private fields */ }

Gitignore is a matcher for the globs in one or more gitignore files in the same directory.

Implementations

impl Gitignore

pub fn new<P: AsRef<Path>>(gitignore_path: P) -> (Gitignore, Option<Error>)

Creates a new gitignore matcher from the gitignore file path given.

If it’s desirable to include multiple gitignore files in a single matcher, or read gitignore globs from a different source, then use GitignoreBuilder.

This always returns a valid matcher, even if it’s empty. In particular, a Gitignore file can be partially valid, e.g., when one glob is invalid but the rest aren’t.

Note that I/O errors are ignored. For more granular control over errors, use GitignoreBuilder.

pub fn global() -> (Gitignore, Option<Error>)

Creates a new gitignore matcher from the global ignore file, if one exists.

The global config file path is specified by git’s core.excludesFile config option.

Git’s config file location is $HOME/.gitconfig. If $HOME/.gitconfig does not exist or does not specify core.excludesFile, then $XDG_CONFIG_HOME/git/ignore is read. If $XDG_CONFIG_HOME is not set or is empty, then $HOME/.config/git/ignore is used instead.

pub fn empty() -> Gitignore

Creates a new empty gitignore matcher that never matches anything.

Its path is empty.

pub fn path(&self) -> &Path

Returns the directory containing this gitignore matcher.

All matches are done relative to this path.

pub fn is_empty(&self) -> bool

Returns true if and only if this gitignore has zero globs, and therefore never matches any file path.

pub fn len(&self) -> usize

Returns the total number of globs, which should be equivalent to num_ignores + num_whitelists.

pub fn num_ignores(&self) -> u64

Returns the total number of ignore globs.

pub fn num_whitelists(&self) -> u64

Returns the total number of whitelisted globs.

pub fn matched<P: AsRef<Path>>(&self, path: P, is_dir: bool) -> Match<&Glob>

Returns whether the given path (file or directory) matched a pattern in this gitignore matcher.

is_dir should be true if the path refers to a directory and false otherwise.

The given path is matched relative to the path given when building the matcher. Specifically, before matching path, its prefix (as determined by a common suffix of the directory containing this gitignore) is stripped. If there is no common suffix/prefix overlap, then path is assumed to be relative to this matcher.

pub fn matched_path_or_any_parents<P: AsRef<Path>>(
    &self,
    path: P,
    is_dir: bool
) -> Match<&Glob>

Returns whether the given path (file or directory, and expected to be under the root) or any of its parent directories (up to the root) matched a pattern in this gitignore matcher.

NOTE: This method is more expensive than walking the directory hierarchy top-to-bottom and matching the entries. But, is easier to use in cases when a list of paths are available without a hierarchy.

is_dir should be true if the path refers to a directory and false otherwise.

The given path is matched relative to the path given when building the matcher. Specifically, before matching path, its prefix (as determined by a common suffix of the directory containing this gitignore) is stripped. If there is no common suffix/prefix overlap, then path is assumed to be relative to this matcher.

Panics

This method panics if the given file path is not under the root path of this matcher.

Trait Implementations

impl Clone for Gitignore

fn clone(&self) -> Gitignore

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Gitignore

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

Formats the value using the given formatter.