Struct ignore::WalkBuilder
[−]
[src]
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, 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.
Methods
impl WalkBuilder
[src]
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 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))
.
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 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 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.
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.
fn sort_by<F>(&mut self, cmp: F) -> &mut WalkBuilder where F: Fn(&OsString, &OsString) -> Ordering + 'static
Set a function for sorting directory entries.
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.
Note that this is not used in the parallel iterator.
Trait Implementations
impl Clone for WalkBuilder
[src]
fn clone(&self) -> WalkBuilder
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more