Struct ignore::WalkBuilder

source ·
pub struct WalkBuilder { /* private fields */ }
Expand description

WalkBuilder builds a recursive directory iterator.

The builder supports a large number of configurable options. This includes specific glob overrides, file type matching, toggling whether hidden files are ignored or not, and of course, support for respecting gitignore files.

By default, all ignore files found are respected. This includes .ignore, .gitignore, .git/info/exclude and even your global gitignore globs, usually found in $XDG_CONFIG_HOME/git/ignore.

Some standard recursive directory options are also supported, such as limiting the recursive depth or whether to follow symbolic links (disabled by default).

§Ignore rules

There are many rules that influence whether a particular file or directory is skipped by this iterator. Those rules are documented here. Note that the rules assume a default configuration.

  • First, glob overrides are checked. If a path matches a glob override, then matching stops. The path is then only skipped if the glob that matched the path is an ignore glob. (An override glob is a whitelist glob unless it starts with a !, in which case it is an ignore glob.)
  • Second, ignore files are checked. Ignore files currently only come from git ignore files (.gitignore, .git/info/exclude and the configured global gitignore file), plain .ignore files, which have the same format as gitignore files, or explicitly added ignore files. The precedence order is: .ignore, .gitignore, .git/info/exclude, global gitignore and finally explicitly added ignore files. Note that precedence between different types of ignore files is not impacted by the directory hierarchy; any .ignore file overrides all .gitignore files. Within each precedence level, more nested ignore files have a higher precedence than less nested ignore files.
  • Third, if the previous step yields an ignore match, then all matching is stopped and the path is skipped. If it yields a whitelist match, then matching continues. A whitelist match can be overridden by a later matcher.
  • Fourth, unless the path is a directory, the file type matcher is run on the path. As above, if it yields an ignore match, then all matching is stopped and the path is skipped. If it yields a whitelist match, then matching continues.
  • Fifth, if the path hasn’t been whitelisted and it is hidden, then the path is skipped.
  • Sixth, unless the path is a directory, the size of the file is compared against the max filesize limit. If it exceeds the limit, it is skipped.
  • Seventh, if the path has made it this far then it is yielded in the iterator.

Implementations§

source§

impl WalkBuilder

source

pub fn new<P: AsRef<Path>>(path: P) -> WalkBuilder

Create a new builder for a recursive directory iterator for the directory given.

Note that if you want to traverse multiple different directories, it is better to call add on this builder than to create multiple Walk values.

source

pub fn build(&self) -> Walk

Build a new Walk iterator.

source

pub fn build_parallel(&self) -> WalkParallel

Build a new WalkParallel iterator.

Note that this doesn’t return something that implements Iterator. Instead, the returned value must be run with a closure. e.g., builder.build_parallel().run(|| |path| { println!("{path:?}"); WalkState::Continue }).

source

pub fn add<P: AsRef<Path>>(&mut self, path: P) -> &mut WalkBuilder

Add a file path to the iterator.

Each additional file path added is traversed recursively. This should be preferred over building multiple Walk iterators since this enables reusing resources across iteration.

source

pub fn max_depth(&mut self, depth: Option<usize>) -> &mut WalkBuilder

The maximum depth to recurse.

The default, None, imposes no depth restriction.

Whether to follow symbolic links or not.

source

pub fn max_filesize(&mut self, filesize: Option<u64>) -> &mut WalkBuilder

Whether to ignore files above the specified limit.

source

pub fn threads(&mut self, n: usize) -> &mut WalkBuilder

The number of threads to use for traversal.

Note that this only has an effect when using build_parallel.

The default setting is 0, which chooses the number of threads automatically using heuristics.

source

pub fn add_ignore<P: AsRef<Path>>(&mut self, path: P) -> Option<Error>

Add a global ignore file to the matcher.

This has lower precedence than all other sources of ignore rules.

If there was a problem adding the ignore file, then an error is returned. Note that the error may indicate partial failure. For example, if an ignore file contains an invalid glob, all other globs are still applied.

source

pub fn add_custom_ignore_filename<S: AsRef<OsStr>>( &mut self, file_name: S, ) -> &mut WalkBuilder

Add a custom ignore file name

These ignore files have higher precedence than all other ignore files.

When specifying multiple names, earlier names have lower precedence than later names.

source

pub fn overrides(&mut self, overrides: Override) -> &mut WalkBuilder

Add an override matcher.

By default, no override matcher is used.

This overrides any previous setting.

source

pub fn types(&mut self, types: Types) -> &mut WalkBuilder

Add a file type matcher.

By default, no file type matcher is used.

This overrides any previous setting.

source

pub fn standard_filters(&mut self, yes: bool) -> &mut WalkBuilder

Enables all the standard ignore filters.

This toggles, as a group, all the filters that are enabled by default:

They may still be toggled individually after calling this function.

This is (by definition) enabled by default.

source

pub fn hidden(&mut self, yes: bool) -> &mut WalkBuilder

Enables ignoring hidden files.

This is enabled by default.

source

pub fn parents(&mut self, yes: bool) -> &mut WalkBuilder

Enables reading ignore files from parent directories.

If this is enabled, then .gitignore files in parent directories of each file path given are respected. Otherwise, they are ignored.

This is enabled by default.

source

pub fn ignore(&mut self, yes: bool) -> &mut WalkBuilder

Enables reading .ignore files.

.ignore files have the same semantics as gitignore files and are supported by search tools such as ripgrep and The Silver Searcher.

This is enabled by default.

source

pub fn git_global(&mut self, yes: bool) -> &mut WalkBuilder

Enables reading a global gitignore file, whose path is specified in 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.

This is enabled by default.

source

pub fn git_ignore(&mut self, yes: bool) -> &mut WalkBuilder

Enables reading .gitignore files.

.gitignore files have match semantics as described in the gitignore man page.

This is enabled by default.

source

pub fn git_exclude(&mut self, yes: bool) -> &mut WalkBuilder

Enables reading .git/info/exclude files.

.git/info/exclude files have match semantics as described in the gitignore man page.

This is enabled by default.

source

pub fn require_git(&mut self, yes: bool) -> &mut WalkBuilder

Whether a git repository is required to apply git-related ignore rules (global rules, .gitignore and local exclude rules).

When disabled, git-related ignore rules are applied even when searching outside a git repository.

source

pub fn ignore_case_insensitive(&mut self, yes: bool) -> &mut WalkBuilder

Process ignore files case insensitively

This is disabled by default.

source

pub fn sort_by_file_path<F>(&mut self, cmp: F) -> &mut WalkBuilder
where F: Fn(&Path, &Path) -> Ordering + Send + Sync + 'static,

Set a function for sorting directory entries by their path.

If a compare function is set, the resulting iterator will return all paths in sorted order. The compare function will be called to compare entries from the same directory.

This is like sort_by_file_name, except the comparator accepts a &Path instead of the base file name, which permits it to sort by more criteria.

This method will override any previous sorter set by this method or by sort_by_file_name.

Note that this is not used in the parallel iterator.

source

pub fn sort_by_file_name<F>(&mut self, cmp: F) -> &mut WalkBuilder
where F: Fn(&OsStr, &OsStr) -> Ordering + Send + Sync + 'static,

Set a function for sorting directory entries by file name.

If a compare function is set, the resulting iterator will return all paths in sorted order. The compare function will be called to compare names from entries from the same directory using only the name of the entry.

This method will override any previous sorter set by this method or by sort_by_file_path.

Note that this is not used in the parallel iterator.

source

pub fn same_file_system(&mut self, yes: bool) -> &mut WalkBuilder

Do not cross file system boundaries.

When this option is enabled, directory traversal will not descend into directories that are on a different file system from the root path.

Currently, this option is only supported on Unix and Windows. If this option is used on an unsupported platform, then directory traversal will immediately return an error and will not yield any entries.

source

pub fn skip_stdout(&mut self, yes: bool) -> &mut WalkBuilder

Do not yield directory entries that are believed to correspond to stdout.

This is useful when a command is invoked via shell redirection to a file that is also being read. For example, grep -r foo ./ > results might end up trying to search results even though it is also writing to it, which could cause an unbounded feedback loop. Setting this option prevents this from happening by skipping over the results file.

This is disabled by default.

source

pub fn filter_entry<P>(&mut self, filter: P) -> &mut WalkBuilder
where P: Fn(&DirEntry) -> bool + Send + Sync + 'static,

Yields only entries which satisfy the given predicate and skips descending into directories that do not satisfy the given predicate.

The predicate is applied to all entries. If the predicate is true, iteration carries on as normal. If the predicate is false, the entry is ignored and if it is a directory, it is not descended into.

Note that the errors for reading entries that may not satisfy the predicate will still be yielded.

Trait Implementations§

source§

impl Clone for WalkBuilder

source§

fn clone(&self) -> WalkBuilder

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for WalkBuilder

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
source§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.