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 empty() -> WalkBuilder

Create an empty builder to which paths can be added.

Note that if you call build on this instance before calling add on it, it will return exactly zero items during iteration.

fn from_iter<P: AsRef<Path>, I: IntoIterator<Item = P>>(paths: I) -> WalkBuilder

Create a new builder for a recursive directory iterator from the sequence of paths.

Note that if the iterator is empty, this is the same as WalkBuilder::empty.

fn build(&self) -> Walk

Build a new Walk iterator.

fn build_matchers(&self) -> Vec<IncrementalIgnore>

Build matchers for checking paths against ignore files without recursively walking the configured roots.

The returned matchers use the path-based filtering configuration on this builder, including glob overrides, file type selections, parent ignore files, .ignore, .gitignore, global Git ignore files, explicitly added ignore files and custom ignore file names. For example, ripgrep configures .rgignore via WalkBuilder::add_custom_ignore_filename. Minimum and maximum depth limits, maximum file size and hidden-file filtering are also applied. Other options that only control traversal or require a directory entry, such as custom entry predicates, are not applied.

One matcher is returned for each configured path, in the same order as the paths were added to this builder. Each matcher accepts paths relative to its own IncrementalIgnore::root. The matcher for the special - path representing standard input always returns a non-match for all inputs.

Ignore matchers are loaded lazily and cached by directory. Thus, the first query may read ignore files from the root and its parents, while later queries reuse the compiled matchers. Errors encountered while loading ignore files are returned by IncrementalIgnore::matched_with_errors. Once an ignore file has been loaded, changes to it are not observed. Build new matchers to reload changed ignore files.

Matchers built together share the builder's base ignore configuration and compiled parent matchers.

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

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 min_depth(&mut self, depth: Option<usize>) -> &mut WalkBuilder

The minimum depth to recurse.

The default, None, imposes no minimum depth restriction.

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

Whether to follow symbolic links or not.

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

Whether to ignore files above the specified limit.

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.

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.

Errors

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.

An error will also occur if this walker could not get the current working directory (and WalkBuilder::current_dir isn't set).

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.

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

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 .gitignore files in parent directories of each file path given are respected. Otherwise, they are ignored.

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.

This is enabled by default.

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.

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.

In particular, if this is false then .gitignore files will be read from parent directories above the git root directory containing .git, which is different from the git behavior.

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

Process ignore files case insensitively

This is disabled by default.

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.

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.

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.

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.

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.

Note also that only one filter predicate can be applied to a WalkBuilder. Calling this subsequent times overrides previous filter predicates.

fn current_dir(&mut self, cwd: impl Into<PathBuf>) -> &mut WalkBuilder

Set the current working directory used for matching global gitignores.

If this is not set, then this walker will attempt to discover the correct path from the environment's current working directory. If that fails, then global gitignore files will be ignored.

Global gitignore files come from things like a user's git configuration or from gitignore files added via WalkBuilder::add_ignore.