Struct ignore::WalkBuilder

pub struct WalkBuilder { /* private fields */ }

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

impl WalkBuilder

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.

pub fn build(&self) -> Walk

Build a new Walk iterator.

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)).

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.

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

The maximum depth to recurse.

The default, None, imposes no depth restriction.

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

Whether to follow symbolic links or not.

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

Whether to ignore files above the specified limit.

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.

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.

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.

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.

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.

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:

• hidden()
• parents()
• ignore()
• git_ignore()
• git_global()
• git_exclude()

They may still be toggled individually after calling this function.

This is (by definition) enabled by default.

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

Enables ignoring hidden files.

This is enabled by default.

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.

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.

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.

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.

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.

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.

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

Process ignore files case insensitively

This is disabled by default.

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.

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.

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.

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.

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

impl Clone for WalkBuilder

fn clone(&self) -> WalkBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for WalkBuilder

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

Formats the value using the given formatter.