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: &Self) -> Walk

Build a new Walk iterator.

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

The maximum depth to recurse.

The default, None, imposes no depth restriction.

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

The minimum depth to recurse.

The default, None, imposes no minimum depth restriction.

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

Whether to follow symbolic links or not.

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

Whether to ignore files above the specified limit.

fn threads(self: &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>>(self: &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>>(self: &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(self: &mut Self, overrides: Override) -> &mut WalkBuilder

Add an override matcher.

By default, no override matcher is used.

This overrides any previous setting.

fn types(self: &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(self: &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(self: &mut Self, yes: bool) -> &mut WalkBuilder

Enables ignoring hidden files.

This is enabled by default.

fn parents(self: &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(self: &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(self: &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(self: &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(self: &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(self: &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(self: &mut Self, yes: bool) -> &mut WalkBuilder

Process ignore files case insensitively

This is disabled by default.

fn sort_by_file_path<F>(self: &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>(self: &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(self: &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(self: &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>(self: &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<impl Into<PathBuf>: Into<PathBuf>>(self: &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.

impl Clone for WalkBuilder

fn clone(self: &Self) -> WalkBuilder

impl Debug for WalkBuilder

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

impl Freeze for WalkBuilder

impl RefUnwindSafe for WalkBuilder

impl Send for WalkBuilder

impl Sync for WalkBuilder

impl Unpin for WalkBuilder

impl UnsafeUnpin for WalkBuilder

impl UnwindSafe for WalkBuilder

impl<T> Any for WalkBuilder

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for WalkBuilder

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for WalkBuilder

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

impl<T> CloneToUninit for WalkBuilder

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for WalkBuilder

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Pointable for WalkBuilder

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

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

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

unsafe fn drop(ptr: usize)

impl<T> ToOwned for WalkBuilder

fn to_owned(self: &Self) -> T

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

impl<T, U> Into for WalkBuilder

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for WalkBuilder

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

impl<T, U> TryInto for WalkBuilder

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