Struct ignore::WalkBuilder

pub struct WalkBuilder { /* fields omitted */ }

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 over less nested ignore files.
• Third, if the previous step yields an ignore match, than all matching is stopped and the path is skipped.. If it yields a whitelist match, then process 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's an ignore match, then all matching is stopped and the path is skipped. If it's a whitelist match, then matching continues.
• Fifth, if the path hasn't been whitelisted and it is hidden, then the path is skipped.
• Sixth, if the path has made it this far then it is yielded in the iterator.

Methods

impl WalkBuilder

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.

fn build(&self) -> Walk

Build a new Walk iterator.

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.

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

The maximum depth to recurse.

The default, None, imposes no depth restriction.

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

Whether to follow symbolic links or not.

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

Add an 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.

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

Add an override matcher.

By default, no override matcher is used.

This overrides any previous setting.

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.

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

Enables ignoring hidden files.

This is enabled by default.

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

Enables reading ignore files from parent directories.

If this is enabled, then the parent directories of each file path given are traversed for ignore files (subject to the ignore settings on this builder). Note that file paths are canonicalized with respect to the current working directory in order to determine parent directories.

This is enabled by default.

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.

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.

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.

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.