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
impl WalkBuilder
sourcepub fn new<P: AsRef<Path>>(path: P) -> 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.
sourcepub fn build_parallel(&self) -> WalkParallel
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 })
.
sourcepub fn add<P: AsRef<Path>>(&mut self, path: P) -> &mut WalkBuilder
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.
sourcepub fn max_depth(&mut self, depth: Option<usize>) -> &mut WalkBuilder
pub fn max_depth(&mut self, depth: Option<usize>) -> &mut WalkBuilder
The maximum depth to recurse.
The default, None
, imposes no depth restriction.
sourcepub fn follow_links(&mut self, yes: bool) -> &mut WalkBuilder
pub fn follow_links(&mut self, yes: bool) -> &mut WalkBuilder
Whether to follow symbolic links or not.
sourcepub fn max_filesize(&mut self, filesize: Option<u64>) -> &mut WalkBuilder
pub fn max_filesize(&mut self, filesize: Option<u64>) -> &mut WalkBuilder
Whether to ignore files above the specified limit.
sourcepub fn threads(&mut self, n: usize) -> &mut WalkBuilder
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.
sourcepub fn add_ignore<P: AsRef<Path>>(&mut self, path: P) -> Option<Error>
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.
sourcepub fn add_custom_ignore_filename<S: AsRef<OsStr>>(
&mut self,
file_name: S,
) -> &mut WalkBuilder
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.
sourcepub fn overrides(&mut self, overrides: Override) -> &mut WalkBuilder
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.
sourcepub fn types(&mut self, types: Types) -> &mut WalkBuilder
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.
sourcepub fn standard_filters(&mut self, yes: bool) -> &mut WalkBuilder
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.
Enables ignoring hidden files.
This is enabled by default.
sourcepub fn parents(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn ignore(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn git_global(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn git_ignore(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn git_exclude(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn require_git(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn ignore_case_insensitive(&mut self, yes: bool) -> &mut WalkBuilder
pub fn ignore_case_insensitive(&mut self, yes: bool) -> &mut WalkBuilder
Process ignore files case insensitively
This is disabled by default.
sourcepub fn sort_by_file_path<F>(&mut self, cmp: F) -> &mut WalkBuilder
pub fn sort_by_file_path<F>(&mut self, cmp: F) -> &mut WalkBuilder
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.
sourcepub fn sort_by_file_name<F>(&mut self, cmp: F) -> &mut WalkBuilder
pub fn sort_by_file_name<F>(&mut self, cmp: F) -> &mut WalkBuilder
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.
sourcepub fn same_file_system(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn skip_stdout(&mut self, yes: bool) -> &mut WalkBuilder
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.
sourcepub fn filter_entry<P>(&mut self, filter: P) -> &mut WalkBuilder
pub fn filter_entry<P>(&mut self, filter: P) -> &mut WalkBuilder
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
impl Clone for WalkBuilder
source§fn clone(&self) -> WalkBuilder
fn clone(&self) -> WalkBuilder
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreAuto Trait Implementations§
impl Freeze for WalkBuilder
impl !RefUnwindSafe for WalkBuilder
impl Send for WalkBuilder
impl Sync for WalkBuilder
impl Unpin for WalkBuilder
impl !UnwindSafe for WalkBuilder
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)