ignore

https://docs.rs/ignore/latest
Admin
A fast recursive directory iterator for Rust that respects gitignore files, globs, and file type...
Tokens:67,734
Snippets:448
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Gitignore Parent Handling

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Verifies that ignore files are correctly respected when starting a walk from a subdirectory.

```rust
    #[test]
    fn gitignore_parent() {
        let td = tmpdir();
        mkdirp(td.path().join(".git"));
        mkdirp(td.path().join("a"));
        wfile(td.path().join(".gitignore"), "foo");
        wfile(td.path().join("a/foo"), "");
        wfile(td.path().join("a/bar"), "");

        let root = td.path().join("a");
        assert_paths(&root, &WalkBuilder::new(&root), &["bar"]);
    }
```

--------------------------------

### Get device number by platform

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Platform-specific implementations to retrieve the device number for a given path.

```rust
#[cfg(unix)]
fn device_num<P: AsRef<Path>>(path: P) -> io::Result<u64> {
    use std::os::unix::fs::MetadataExt;

    path.as_ref().metadata().map(|md| md.dev())
}
```

```rust
#[cfg(windows)]
fn device_num<P: AsRef<Path>>(path: P) -> io::Result<u64> {
    use winapi_util::{Handle, file};

    let h = Handle::from_path_any(path)?;
    file::information(h).map(|info| info.volume_serial_number())
}
```

```rust
#[cfg(not(any(unix, windows)))]
fn device_num<P: AsRef<Path>>(_: P) -> io::Result<u64> {
    Err(io::Error::new(
        io::ErrorKind::Other,
        "walkdir: same_file_system option not supported on this platform",
    ))
}
```

--------------------------------

### Get stdout file handle

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Returns a handle to stdout if it is redirected to a file, allowing for safe file comparison.

```rust
fn stdout_handle() -> Option<Handle> {
    let h = match Handle::stdout() {
        Err(_) => return None,
        Ok(h) => h,
    };
    let md = match h.as_file().metadata() {
        Err(_) => return None,
        Ok(md) => md,
    };
    if !md.is_file() {
        return None;
    }
    Some(h)
}
```

--------------------------------

### Get Total Glob Count

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.Gitignore.html

Returns the sum of ignore and whitelist patterns.

```rust
pub fn len(&self) -> usize
```

--------------------------------

### Basic WalkBuilder Usage

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Demonstrates a standard file system walk with default ignore settings.

```rust
        mkdirp(td.path().join("a"));
        wfile(td.path().join(".gitignore"), "foo");
        wfile(td.path().join("foo"), "");
        wfile(td.path().join("a/foo"), "");
        wfile(td.path().join("bar"), "");
        wfile(td.path().join("a/bar"), "");

        assert_paths(
            td.path(),
            &WalkBuilder::new(td.path()),
            &["bar", "a", "a/bar"],
        );
    }
```

--------------------------------

### Get Ignore and Whitelist Counts

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.Gitignore.html

Returns the specific counts for ignore and whitelist patterns respectively.

```rust
pub fn num_ignores(&self) -> u64
pub fn num_whitelists(&self) -> u64
```

--------------------------------

### Define file types based on existing definitions

Source: https://docs.rs/ignore/latest/ignore/types/index.html

Shows how to create a new file type definition that includes patterns from other existing definitions.

```rust
use ignore::types::TypesBuilder;

let mut builder = TypesBuilder::new();
builder.add_defaults();
builder.add("foo", "*.foo");
builder.add_def("bar:include:foo,cpp");
builder.select("bar");
let matcher = builder.build().unwrap();

assert!(matcher.matched("x.foo", false).is_whitelist());
assert!(matcher.matched("y.cpp", false).is_whitelist());
```

--------------------------------

### Minimum Depth Configuration

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Shows how to set a minimum depth for the file system walk.

```rust
    #[test]
    fn min_depth() {
        let td = tmpdir();
        mkdirp(td.path().join("a/b/c"));
        wfile(td.path().join("foo"), "");
        wfile(td.path().join("a/foo"), "");
        wfile(td.path().join("a/b/foo"), "");
        wfile(td.path().join("a/b/c/foo"), "");

        let builder = WalkBuilder::new(td.path());
        assert_paths(
            td.path(),
            &builder,
            &["a", "a/b", "a/b/c", "foo", "a/foo", "a/b/foo", "a/b/c/foo"],
        );
        let mut builder = WalkBuilder::new(td.path());
        assert_paths(
            td.path(),
            &builder.min_depth(Some(0)),
            &["a", "a/b", "a/b/c", "foo", "a/foo", "a/b/foo", "a/b/c/foo"],
        );
        assert_paths(
            td.path(),
            &builder.min_depth(Some(1)),
            &["a", "a/b", "a/b/c", "foo", "a/foo", "a/b/foo", "a/b/c/foo"],
        );
        assert_paths(
            td.path(),
            builder.min_depth(Some(2)),
```

--------------------------------

### Work implementation methods

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Methods for managing directory traversal, including checking file types, adding ignore rules, and reading directory contents.

```rust
impl Work {
    /// Returns true if and only if this work item is a directory.
    fn is_dir(&self) -> bool {
        self.dent.is_dir()
    }

    /// Returns true if and only if this work item is a symlink.
    fn is_symlink(&self) -> bool {
        self.dent.file_type().map_or(false, |ft| ft.is_symlink())
    }

    /// Adds ignore rules for parent directories.
    ///
    /// Note that this only applies to entries at depth 0. On all other
    /// entries, this is a no-op.
    fn add_parents(&mut self) -> Option<Error> {
        if self.dent.depth() > 0 {
            return None;
        }
        // At depth 0, the path of this entry is a root path, so we can
        // use it directly to add parent ignore rules.
        let (ig, err) = self.ignore.add_parents(self.dent.path());
        self.ignore = ig;
        err
    }

    /// Adds ignore rules for this directory without reading its contents.
    fn add_ignore(&mut self) {
        let (ig, err) = self.ignore.add_child(self.dent.path());
        self.ignore = ig;
        self.dent.err = err;
    }

    /// Reads the directory contents of this work item and adds ignore
    /// rules for this directory.
    ///
    /// If there was a problem with reading the directory contents, then
    /// an error is returned. If there was a problem reading the ignore
    /// rules for this directory, then the error is attached to this
    /// work item's directory entry.
    fn read_dir(&mut self) -> Result<ReadDirResult, Error> {
        let readdir = match fs::read_dir(self.dent.path()) {
            Ok(readdir) => readdir,
            Err(err) => {
                let err = Error::from(err)
                    .with_path(self.dent.path())
                    .with_depth(self.dent.depth());
                return Err(err);
            }
        };
        // Actually descend into the directory and read its contents
        let mut result = ReadDirResult::default();
        for entry in readdir {
            match entry {
                Ok(entry) => result.entries.push(entry),
                Err(err) => result.errors.push(
                    Error::from(err)
                        .with_path(self.dent.path())
                        .with_depth(self.dent.depth() + 1),
                ),
            }
        }
        let (ig, err) = self
            .ignore
            .add_child_with_entries(self.dent.path(), &result.entries);
        self.ignore = ig;
        self.dent.err = err;
        Ok(result)
    }
}
```

--------------------------------

### Create a new GitignoreBuilder

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.GitignoreBuilder.html

Initializes a new builder with a specified root path for relative matching.

```rust
pub fn new<P: AsRef<Path>>(root: P) -> GitignoreBuilder
```

--------------------------------

### Create a Global Gitignore Matcher

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.Gitignore.html

Initializes a matcher based on the global git configuration, typically found in core.excludesFile.

```rust
pub fn global() -> (Gitignore, Option<Error>)
```

--------------------------------

### Check if a path is hidden based on name only

Source: https://docs.rs/ignore/latest/src/ignore/pathutil.rs.html

A platform-agnostic helper that checks if a path's base name starts with a dot.

```rust
fn is_hidden_path_only(path: &Path) -> bool {
    if let Some(name) = file_name(path) {
        name.as_encoded_bytes().starts_with(b".")
    } else {
        false
    }
}
```

--------------------------------

### Get Default Git Ignore Path

Source: https://docs.rs/ignore/latest/src/ignore/gitignore.rs.html

Determines the default path for a global .gitignore file, respecting the XDG_CONFIG_HOME environment variable.

```rust
fn excludes_file_default() -> Option<PathBuf> {
    std::env::var_os("XDG_CONFIG_HOME")
        .map(PathBuf::from)
        .filter(|x| !x.as_os_str().is_empty())
        .or_else(|| home_dir().map(|p| p.join(".config")))
        .map(|x| x.join("git/ignore"))
}
```

--------------------------------

### File System Helper Functions

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Utilities for creating files, directories, and symlinks within test environments.

```rust
fn wfile_size<P: AsRef<Path>>(path: P, size: u64) {
    let file = File::create(path).unwrap();
    file.set_len(size).unwrap();
}
```

```rust
#[cfg(unix)]
fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) {
    use std::os::unix::fs::symlink;
    symlink(src, dst).unwrap();
}
```

```rust
fn mkdirp<P: AsRef<Path>>(path: P) {
    fs::create_dir_all(path).unwrap();
}
```

--------------------------------

### Test Empty Configuration

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Ensures that the builder handles directories without ignore files correctly.

```rust
#[test]
    fn not_present_empty() {
        let td = tmpdir();

        let (_, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert!(err.is_none());
    }
```

--------------------------------

### Get the file name from a path

Source: https://docs.rs/ignore/latest/src/ignore/pathutil.rs.html

Extracts the final component of a path if it is a normal file. Returns None for paths terminating in '.' or '..'.

```rust
pub(crate) fn file_name<'a, P: AsRef<Path> + ?Sized>(
    path: &'a P,
) -> Option<&'a OsStr> {
    #[cfg(unix)]
    fn imp(path: &Path) -> Option<&OsStr> {
        use std::os::unix::ffi::OsStrExt;

        use memchr::memrchr;

        let path = path.as_os_str().as_bytes();
        if path.is_empty() {
            return None;
        } else if path.len() == 1 && path[0] == b'.' {
            return None;
        } else if path.last() == Some(&b'.') {
            return None;
```

--------------------------------

### Create and use a default file type matcher

Source: https://docs.rs/ignore/latest/ignore/types/index.html

Initializes a TypesBuilder with default file types and selects the 'rust' type to match .rs files.

```rust
use ignore::types::TypesBuilder;

let mut builder = TypesBuilder::new();
builder.add_defaults();
builder.select("rust");
let matcher = builder.build().unwrap();

assert!(matcher.matched("foo.rs", false).is_whitelist());
assert!(matcher.matched("foo.c", false).is_ignore());
```

--------------------------------

### Create a New Gitignore Matcher

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.Gitignore.html

Initializes a matcher from a specific file path. Use GitignoreBuilder for more complex requirements or granular error handling.

```rust
pub fn new<P: AsRef<Path>>(gitignore_path: P) -> (Gitignore, Option<Error>)
```

--------------------------------

### WalkBuilder Initialization Methods

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Methods for creating new instances of WalkBuilder, either with an initial path or as an empty builder.

```rust
impl 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.
    pub fn new<P: AsRef<Path>>(path: P) -> WalkBuilder {
        WalkBuilder::from_iter([path])
    }

    /// 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.
    pub fn empty() -> WalkBuilder {
        WalkBuilder {
            paths: vec![],
            ig_builder: IgnoreBuilder::new(),
            max_depth: None,
            min_depth: None,
            max_filesize: None,
            follow_links: false,
            same_file_system: false,
            sorter: None,
            threads: 0,
            skip: None,
            filter: None,
            global_gitignores_relative_to: OnceLock::new(),
        }
    }
```

--------------------------------

### Configure Depth Limits

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Demonstrates using min_depth and max_depth to control the directory traversal depth.

```rust
        assert_paths(
            td.path(),
            builder.min_depth(Some(3)),
            &["a/b/c", "a/b/c/foo", "a/b/foo"],
        );
        assert_paths(td.path(), builder.min_depth(Some(10)), &[]);

        assert_paths(
            td.path(),
            builder.min_depth(Some(2)).max_depth(Some(1)),
            &["a/b", "a/foo"],
        );
```

--------------------------------

### Initialize Ignore Matchers

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Logic for creating and aggregating various ignore matchers including custom, .ignore, .gitignore, and git info/exclude files.

```rust
            .custom_ignore_filenames
                    .iter()
                    .zip(m.custom_ignore_files.iter())
                    .filter(|&(_, &matched)| matched)
                    .map(|(name, _)| name)
                    .collect(),
            };
            if custom_ignore_names.is_empty() {
                Gitignore::empty()
            } else {
                let (m, err) = create_gitignore(
                    &dir,
                    &dir,
                    &custom_ignore_names,
                    self.inner.opts.ignore_case_insensitive,
                );
                errs.maybe_push(err);
                m
            }
        };
        let ig_matcher = if !self.inner.opts.ignore
            || !ignore_files_list.is_none_or(|i| i.has_ignore)
        {
            Gitignore::empty()
        } else {
            let (m, err) = create_gitignore(
                &dir,
                &dir,
                &[".ignore"],
                self.inner.opts.ignore_case_insensitive,
            );
            errs.maybe_push(err);
            m
        };
        let gi_matcher = if !self.inner.opts.git_ignore
            || !ignore_files_list.is_none_or(|i| i.has_git_ignore)
        {
            Gitignore::empty()
        } else {
            let (m, err) = create_gitignore(
                &dir,
                &dir,
                &[".gitignore"],
                self.inner.opts.ignore_case_insensitive,
            );
            errs.maybe_push(err);
            m
        };

        let gi_exclude_matcher = if !self.inner.opts.git_exclude
            || !ignore_files_list.is_none_or(|i| i.has_git_dir)
        {
            Gitignore::empty()
        } else {
            match resolve_git_commondir(dir, git_type) {
                Ok(git_dir) => {
                    let (m, err) = create_gitignore(
                        &dir,
                        &git_dir,
                        &["info/exclude"],
                        self.inner.opts.ignore_case_insensitive,
                    );
                    errs.maybe_push(err);
                    m
                }
                Err(err) => {
                    errs.maybe_push(err);
                    Gitignore::empty()
                }
            }
        };
```

--------------------------------

### Parallel Directory Traversal Execution

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

The visit method initializes the traversal process by setting up workers and distributing directory paths across threads.

```rust
pub fn visit(mut self, builder: &mut dyn ParallelVisitorBuilder<'_>) {
        let threads = self.threads();
        let mut stack = vec![];
        {
            let mut visitor = builder.build();
            let mut paths = Vec::new().into_iter();
            std::mem::swap(&mut paths, &mut self.paths);
            // Send the initial set of root paths to the pool of workers. Note
            // that we only send directories. For files, we send to them the
            // callback directly.
            for path in paths {
                let (dent, root_device) = if path == Path::new("-") {
                    (DirEntry::new_stdin(), None)
                } else {
                    let root_device = if !self.same_file_system {
                        None
                    } else {
                        match device_num(&path) {
                            Ok(root_device) => Some(root_device),
                            Err(err) => {
                                let err = Error::Io(err).with_path(path);
                                if visitor.visit(Err(err)).is_quit() {
                                    return;
                                }
                                continue;
                            }
                        }
                    };
                    match DirEntryRaw::from_path(0, path, false) {
                        Ok(dent) => {
                            (DirEntry::new_raw(dent, None), root_device)
                        }
                        Err(err) => {
                            if visitor.visit(Err(err)).is_quit() {
                                return;
                            }
                            continue;
                        }
                    }
                };
                stack.push(Message::Work(Work {
                    dent,
                    ignore: self.ig_root.clone(),
                    root_device,
                }));
            }
            // ... but there's no need to start workers if we don't need them.
            if stack.is_empty() {
                return;
            }
        }
        // Create the workers and then wait for them to finish.
        let quit_now = Arc::new(AtomicBool::new(false));
        let active_workers = Arc::new(AtomicUsize::new(threads));
        let stacks = Stack::new_for_each_thread(threads, stack);
        // Collect all of the workers first. In the case that
        // `builder.build()` panics, we want that to happen and
        // propagate before we actually start to run any of the
        // workers.
        let workers: Vec<_> = stacks
            .into_iter()
            .map(|stack| Worker {
                visitor: builder.build(),
                stack,
                quit_now: quit_now.clone(),
                active_workers: active_workers.clone(),
                max_depth: self.max_depth,
                min_depth: self.min_depth,
                max_filesize: self.max_filesize,
                follow_links: self.follow_links,
                skip: self.skip.clone(),
                filter: self.filter.clone(),
            })
            .collect();
        std::thread::scope(|s| {
            let handles: Vec<_> = workers
                .into_iter()
                .map(|worker| s.spawn(|| worker.run()))
                .collect();
            for handle in handles {
                handle.join().unwrap();
            }
        });
    }
```

--------------------------------

### Path and Home Directory Utilities

Source: https://docs.rs/ignore/latest/src/ignore/gitignore.rs.html

Helper functions for expanding tilde characters in paths and retrieving the user's home directory.

```rust
fn expand_tilde(path: &str) -> String {
    let home = match home_dir() {
        None => return path.to_string(),
        Some(home) => home.to_string_lossy().into_owned(),
    };
    path.replace("~", &home)
}

/// Returns the location of the user's home directory.
fn home_dir() -> Option<PathBuf> {
    // We're fine with using std::env::home_dir for now. Its bugs are, IMO,
    // pretty minor corner cases.
    #![allow(deprecated)]
    std::env::home_dir()
}
```

--------------------------------

### Create an Empty Gitignore Matcher

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.Gitignore.html

Returns a matcher that contains no patterns and matches nothing.

```rust
pub fn empty() -> Gitignore
```

--------------------------------

### Create Ignore Matcher with Pre-collected Entries

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Optimizes matcher creation by using pre-collected directory entries to reduce filesystem probing.

```rust
pub(crate) fn add_child_with_entries<P: AsRef<Path>>(
        &self,
        dir: P,
        entries: &[fs::DirEntry],
    ) -> (Ignore, Option<Error>) {
        let files = self.collect_ignore_files(entries);
        let (ig, err) = self.add_child_path_with_found_ignore_files(
            dir.as_ref(),
            Some(&files),
        );
        (
            Ignore {
                inner: Arc::new(ig),
                absolute_base: self.absolute_base.clone(),
            },
            err,
        )
    }
```

--------------------------------

### Test Custom Ignore Files and Precedence

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Demonstrates how to add custom ignore filenames and how they interact with existing ignore files and each other.

```rust
#[test]
    fn custom_ignore() {
        let td = tmpdir();
        let custom_ignore = ".customignore";
        wfile(td.path().join(custom_ignore), "foo\n!bar");

        let (ig, err) = IgnoreBuilder::new()
            .add_custom_ignore_filename(custom_ignore)
            .build()
            .add_child(td.path());
        assert!(err.is_none());
        assert!(ig.matched("foo", false).is_ignore());
        assert!(ig.matched("bar", false).is_whitelist());
        assert!(ig.matched("baz", false).is_none());
    }
```

```rust
#[test]
    fn custom_ignore_over_ignore() {
        let td = tmpdir();
        let custom_ignore = ".customignore";
        wfile(td.path().join(".ignore"), "foo");
        wfile(td.path().join(custom_ignore), "!foo");

        let (ig, err) = IgnoreBuilder::new()
            .add_custom_ignore_filename(custom_ignore)
            .build()
            .add_child(td.path());
        assert!(err.is_none());
        assert!(ig.matched("foo", false).is_whitelist());
    }
```

```rust
#[test]
    fn custom_ignore_precedence() {
        let td = tmpdir();
        let custom_ignore1 = ".customignore1";
        let custom_ignore2 = ".customignore2";
        wfile(td.path().join(custom_ignore1), "foo");
        wfile(td.path().join(custom_ignore2), "!foo");

        let (ig, err) = IgnoreBuilder::new()
            .add_custom_ignore_filename(custom_ignore1)
            .add_custom_ignore_filename(custom_ignore2)
            .build()
            .add_child(td.path());
        assert!(err.is_none());
        assert!(ig.matched("foo", false).is_whitelist());
    }
```

--------------------------------

### Create test file

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Helper function for creating files during testing.

```rust
fn wfile<P: AsRef<Path>>(path: P, contents: &str) {
    let mut file = File::create(path).unwrap();
```

--------------------------------

### Verify depth limit configuration

Source: https://docs.rs/ignore/latest/src/ignore/incremental.rs.html

Tests the initialization of a matcher with specific minimum and maximum depth constraints.

```rust
#[test]
    fn depth_limits() {
        let td = tmpdir();
        mkdirp(td.path().join("a/b/c/d"));

        let mut b = builder(td.path());
        b.min_depth(Some(2)).max_depth(Some(3));
        let mut m = one_matcher(&b);
```

--------------------------------

### pub fn visit(self, builder: &mut dyn ParallelVisitorBuilder<'_>)

Source: https://docs.rs/ignore/latest/ignore/struct.WalkParallel.html

Executes the parallel recursive directory iterator using a custom visitor, which is useful for performing cleanup or aggregating results across threads.

```APIDOC
## pub fn visit(self, builder: &mut dyn ParallelVisitorBuilder<'_>)

### Description
Executes the parallel recursive directory iterator using a custom visitor. The builder is used to construct a visitor for every thread used by this traversal.

### Parameters
- **builder** (&mut dyn ParallelVisitorBuilder<'_>) - Required - A builder used to construct a visitor for every thread used by the traversal.
```

--------------------------------

### Configure Traversal Options

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Methods to toggle symbolic link following, file size limits, and thread counts for parallel execution.

```rust
pub fn follow_links(&mut self, yes: bool) -> &mut WalkBuilder {
    self.follow_links = yes;
    self
}

pub fn max_filesize(&mut self, filesize: Option<u64>) -> &mut WalkBuilder {
    self.max_filesize = filesize;
    self
}

pub fn threads(&mut self, n: usize) -> &mut WalkBuilder {
    self.threads = n;
    self
}
```

--------------------------------

### Perform incremental path matching

Source: https://docs.rs/ignore/latest/ignore/struct.IncrementalIgnore.html

Demonstrates how to build a matcher and check if a specific path is ignored.

```rust
use ignore::WalkBuilder;

let mut builder = WalkBuilder::new(".");
builder.add_custom_ignore_filename(".rgignore");
let mut matchers = builder.build_matchers();
let matcher = &mut matchers[0];

if matcher.matched("src/generated.rs", false).is_ignore() {
    println!("ignored");
}
```

--------------------------------

### Initialize IgnoreBuilder

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Creates a new IgnoreBuilder instance with default settings.

```rust
pub(crate) fn new() -> IgnoreBuilder {
        IgnoreBuilder {
            dir: Path::new("").to_path_buf(),
            overrides: Arc::new(Override::empty()),
            types: Arc::new(Types::empty()),
            explicit_ignores: vec![],
            custom_ignore_filenames: vec![],
            global_gitignores_relative_to: None,
            opts: IgnoreOptions {
                hidden: true,
                ignore: true,
                parents: true,
                git_global: true,
                git_ignore: true,
                git_exclude: true,
                ignore_case_insensitive: false,
                require_git: true,
            },
        }
    }
```

--------------------------------

### WalkBuilder Configuration Methods

Source: https://docs.rs/ignore/latest/ignore/struct.WalkBuilder.html

Methods for configuring the WalkBuilder instance, including filters, sorting, and traversal constraints.

```APIDOC
## pub fn types(&mut self, types: Types) -> &mut WalkBuilder

### Description
Adds a file type matcher to the builder. This overrides any previous file type matcher settings.

## pub fn standard_filters(&mut self, yes: bool) -> &mut WalkBuilder

### Description
Enables or disables all standard ignore filters (hidden, parents, ignore, git_ignore, git_global, git_exclude) as a group.

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

### Description
Enables or disables ignoring hidden files. Enabled by default.

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

### Description
Enables or disables reading ignore files from parent directories. Enabled by default.

## pub fn ignore(&mut self, yes: bool) -> &mut WalkBuilder

### Description
Enables or disables reading `.ignore` files. Enabled by default.

## pub fn git_global(&mut self, yes: bool) -> &mut WalkBuilder

### Description
Enables or disables reading a global gitignore file. Enabled by default.

## pub fn git_ignore(&mut self, yes: bool) -> &mut WalkBuilder

### Description
Enables or disables reading `.gitignore` files. Enabled by default.

## pub fn git_exclude(&mut self, yes: bool) -> &mut WalkBuilder

### Description
Enables or disables reading `.git/info/exclude` files. Enabled by default.

## pub fn require_git(&mut self, yes: bool) -> &mut WalkBuilder

### Description
Configures whether a git repository is required to apply git-related ignore rules.

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

### Description
Configures whether to process ignore files case insensitively. Disabled by default.

## pub fn sort_by_file_path<F>(&mut self, cmp: F) -> &mut WalkBuilder

### Description
Sets a function for sorting directory entries by their path. Overrides previous sorters.

## pub fn sort_by_file_name<F>(&mut self, cmp: F) -> &mut WalkBuilder

### Description
Sets a function for sorting directory entries by file name. Overrides previous sorters.

## pub fn same_file_system(&mut self, yes: bool) -> &mut WalkBuilder

### Description
Configures whether to prevent crossing file system boundaries during traversal.
```

--------------------------------

### Initialize TypesBuilder

Source: https://docs.rs/ignore/latest/src/ignore/types.rs.html

Creates a new, empty TypesBuilder instance.

```rust
pub fn new() -> TypesBuilder {
    TypesBuilder { types: HashMap::new(), selections: vec![] }
}
```

--------------------------------

### Add Default File Type Definitions

Source: https://docs.rs/ignore/latest/src/ignore/types.rs.html

Populates the builder with a predefined set of file type mappings.

```rust
pub fn add_defaults(&mut self) -> &mut TypesBuilder {
        static MSG: &'static str = "adding a default type should never fail";
        for &(names, exts) in DEFAULT_TYPES {
            for name in names {
                for ext in exts {
                    self.add(name, ext).expect(MSG);
                }
            }
        }
        self
    }
```

--------------------------------

### Build a Gitignore matcher

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.GitignoreBuilder.html

Finalizes the builder to create a Gitignore instance.

```rust
pub fn build(&self) -> Result<Gitignore, Error>
```

--------------------------------

### Handle Symlinks

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Configures symlink following behavior during directory traversal.

```rust
        let mut builder = WalkBuilder::new(td.path());
        assert_paths(td.path(), &builder, &["a", "a/b", "a/b/foo", "z"]);
        assert_paths(
            td.path(),
            &builder.follow_links(true),
            &["a", "a/b", "a/b/foo", "z", "z/foo"],
        );
```

--------------------------------

### Walk::new

Source: https://docs.rs/ignore/latest/index.html

Creates a new recursive directory iterator that automatically respects ignore files like .gitignore.

```APIDOC
## Walk::new(path: P)

### Description
Creates a new recursive directory iterator for the given path. It automatically filters out files and directories based on ignore rules.

### Usage
```rust
use ignore::Walk;

for result in Walk::new("./") {
    match result {
        Ok(entry) => println!("{}", entry.path().display()),
        Err(err) => println!("ERROR: {}", err),
    }
}
```
```

--------------------------------

### Test Utilities for Incremental Ignore

Source: https://docs.rs/ignore/latest/src/ignore/incremental.rs.html

Helper functions for setting up file system environments and builders for testing incremental ignore logic.

```rust
fn wfile<P: AsRef<Path>>(path: P, contents: &str) {
    let mut file = File::create(path).unwrap();
    file.write_all(contents.as_bytes()).unwrap();
}

fn mkdirp<P: AsRef<Path>>(path: P) {
    fs::create_dir_all(path).unwrap();
}

fn tmpdir() -> TempDir {
    TempDir::new().unwrap()
}

fn builder<P: AsRef<Path>>(path: P) -> WalkBuilder {
    let mut builder = WalkBuilder::new(path);
    builder.git_global(false);
    builder
}

fn one_matcher(builder: &WalkBuilder) -> IncrementalIgnore {
    let mut matchers = builder.build_matchers();
    assert_eq!(matchers.len(), 1);
    matchers.pop().unwrap()
}

fn builders<I: IntoIterator<Item = P>, P: AsRef<Path>>(
    paths: I,
) -> WalkBuilder {
    let mut builder = WalkBuilder::from_iter(paths);
    builder.git_global(false);
    builder
}

fn matchers(builder: &WalkBuilder) -> Vec<IncrementalIgnore> {
    builder.build_matchers()
}

fn matchedf<P: AsRef<Path>>(
    matcher: &mut IncrementalIgnore,
    path: P,
) -> IncrementalMatch {
```

--------------------------------

### Test .gitignore Patterns

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Verifies that .gitignore files are processed correctly, including scenarios with and without a .git directory.

```rust
#[test]
    fn gitignore() {
        let td = tmpdir();
        mkdirp(td.path().join(".git"));
        wfile(td.path().join(".gitignore"), "foo\n!bar");

        let (ig, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert!(err.is_none());
        assert!(ig.matched("foo", false).is_ignore());
        assert!(ig.matched("bar", false).is_whitelist());
        assert!(ig.matched("baz", false).is_none());
    }
```

```rust
#[test]
    fn gitignore_with_jj() {
        let td = tmpdir();
        mkdirp(td.path().join(".jj"));
        wfile(td.path().join(".gitignore"), "foo\n!bar");

        let (ig, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert!(err.is_none());
        assert!(ig.matched("foo", false).is_ignore());
        assert!(ig.matched("bar", false).is_whitelist());
        assert!(ig.matched("baz", false).is_none());
    }
```

```rust
#[test]
    fn gitignore_no_git() {
        let td = tmpdir();
        wfile(td.path().join(".gitignore"), "foo\n!bar");

        let (ig, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert!(err.is_none());
        assert!(ig.matched("foo", false).is_none());
        assert!(ig.matched("bar", false).is_none());
        assert!(ig.matched("baz", false).is_none());
    }
```

```rust
#[test]
    fn gitignore_allowed_no_git() {
        let td = tmpdir();
        wfile(td.path().join(".gitignore"), "foo\n!bar");

        let (ig, err) = IgnoreBuilder::new()
            .require_git(false)
            .build()
            .add_child(td.path());
        assert!(err.is_none());
        assert!(ig.matched("foo", false).is_ignore());
        assert!(ig.matched("bar", false).is_whitelist());
        assert!(ig.matched("baz", false).is_none());
    }
```

--------------------------------

### Build a global Gitignore matcher

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.GitignoreBuilder.html

Consumes the builder to create a global matcher based on git configuration.

```rust
pub fn build_global(self) -> (Gitignore, Option<Error>)
```

--------------------------------

### GitignoreBuilder::build

Source: https://docs.rs/ignore/latest/src/ignore/gitignore.rs.html

Builds a new matcher from the globs added to the builder so far.

```APIDOC
## GitignoreBuilder::build

### Description
Builds a new matcher from the globs added so far. Once a matcher is built, no new globs can be added to it.

### Signature
`pub fn build(&self) -> Result<Gitignore, Error>`
```

--------------------------------

### Check same file system

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Verifies if a path resides on the same device as the root device.

```rust
fn is_same_file_system(root_device: u64, path: &Path) -> Result<bool, Error> {
    let dent_device =
        device_num(path).map_err(|err| Error::Io(err).with_path(path))?;
    Ok(root_device == dent_device)
}
```

--------------------------------

### Stack initialization

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Creates a work-stealing stack for each thread, using LIFO order to ensure depth-first traversal.

```rust
impl Stack {
    /// Create a work-stealing stack for each thread. The given messages
    /// correspond to the initial paths to start the search at. They will
    /// be distributed automatically to each stack in a round-robin fashion.
    fn new_for_each_thread(threads: usize, init: Vec<Message>) -> Vec<Stack> {
        // Using new_lifo() ensures each worker operates depth-first, not
        // breadth-first. We do depth-first because a breadth first traversal
        // on wide directories with a lot of gitignores is disastrous (for
        // example, searching a directory tree containing all of crates.io).
        let deques: Vec<Deque<Message>> =
            std::iter::repeat_with(Deque::new_lifo).take(threads).collect();
        let stealers = Arc::<[Stealer<Message>]>::from(
            deques.iter().map(Deque::stealer).collect::<Vec<_>>(),
        );
        let stacks: Vec<Stack> = deques
            .into_iter()
            .enumerate()
            .map(|(index, deque)| Stack {
                index,
                deque,
                stealers: stealers.clone(),
            })
            .collect();
        // Distribute the initial messages, reverse the order to cancel out
```

--------------------------------

### Build Ignore Matcher

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Methods to finalize the configuration and produce an Ignore matcher instance.

```rust
pub(crate) fn build(&self) -> Ignore {
        self.build_with_cwd(None)
    }
```

```rust
pub(crate) fn build_with_cwd(&self, cwd: Option<PathBuf>) -> Ignore {
        let global_gitignores_relative_to =
            cwd.or_else(|| self.global_gitignores_relative_to.clone());
        let git_global_matcher = if !self.opts.git_global {
            Gitignore::empty()
        } else if let Some(ref cwd) = global_gitignores_relative_to {
            let mut builder = GitignoreBuilder::new(cwd);
            builder
                .case_insensitive(self.opts.ignore_case_insensitive)
                .unwrap();
            let (gi, err) = builder.build_global();
            if let Some(err) = err {
                log::debug!("{}", err);
            }
            gi
        } else {
            log::debug!(
                "ignoring global gitignore file because CWD is not known"
            );
            Gitignore::empty()
        };

        Ignore {
            inner: Arc::new(IgnoreInner {
                compiled: Arc::new(RwLock::new(HashMap::new())),
                dir: self.dir.clone(),
                overrides: self.overrides.clone(),
                types: self.types.clone(),
                parent: None,
                is_absolute_parent: true,
                global_gitignores_relative_to,
                explicit_ignores: Arc::new(self.explicit_ignores.clone()),
                custom_ignore_filenames: Arc::new(
                    self.custom_ignore_filenames.clone(),
                ),
                custom_ignore_matcher: Gitignore::empty(),
                ignore_matcher: Gitignore::empty(),
                git_global_matcher: Arc::new(git_global_matcher),
                git_ignore_matcher: Gitignore::empty(),
                git_exclude_matcher: Gitignore::empty(),
                has_git: false,
                opts: self.opts,
            }),
            absolute_base: None,
        }
    }
```

--------------------------------

### DirEntryRaw Implementation Methods

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Methods for path handling and metadata retrieval within DirEntryRaw.

```rust
258impl std::fmt::Debug for DirEntryRaw {
259    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
260        // Leaving out FileType because it doesn't have a debug impl
261        // in Rust 1.9. We could add it if we really wanted to by manually
262        // querying each possibly file type. Meh. ---AG
263        f.debug_struct("DirEntryRaw")
264            .field("path", &self.path)
265            .field("follow_link", &self.follow_link)
266            .field("depth", &self.depth)
267            .finish()
268    }
269}
270
271impl DirEntryRaw {
272    fn path(&self) -> &Path {
273        &self.path
274    }
275
276    fn into_path(self) -> PathBuf {
277        self.path
278    }
279
280    fn path_is_symlink(&self) -> bool {
281        self.ty.is_symlink() || self.follow_link
282    }
283
284    fn metadata(&self) -> Result<Metadata, Error> {
285        self.metadata_internal()
286    }
287
288    #[cfg(windows)]
289    fn metadata_internal(&self) -> Result<fs::Metadata, Error> {
290        if self.follow_link {
291            fs::metadata(&self.path)
292        } else {
293            Ok(self.metadata.clone())
294        }
295        .map_err(|err| Error::Io(io::Error::from(err)).with_path(&self.path))
296    }
297
298    #[cfg(not(windows))]
299    fn metadata_internal(&self) -> Result<fs::Metadata, Error> {
300        if self.follow_link {
301            fs::metadata(&self.path)
302        } else {
303            fs::symlink_metadata(&self.path)
304        }
305        .map_err(|err| {
306            Error::Io(err).with_depth(self.depth).with_path(&self.path)
307        })
308    }
309
310    fn file_type(&self) -> FileType {
311        self.ty
312    }
313
314    fn file_name(&self) -> &OsStr {

```

--------------------------------

### Initialize IncrementalIgnore

Source: https://docs.rs/ignore/latest/src/ignore/incremental.rs.html

Initializes the IncrementalIgnore structure, handling stdin as a special root case.

```rust
        // can use `./-`. As is the case for file traversal too.
        let ignore = if root == Path::new("-") {
            RootIgnore::Stdin
        } else {
            RootIgnore::Unloaded(ignore)
        };
        IncrementalIgnore {
            root,
            normalized_root: OnceLock::new(),
            ignore,
            dirs: HashMap::new(),
            options,
        }
    }
```

--------------------------------

### Gitignore::path

Source: https://docs.rs/ignore/latest/src/ignore/gitignore.rs.html

Returns the directory containing this gitignore matcher.

```APIDOC
## Gitignore::path()

### Description
Returns the directory containing this gitignore matcher. All matches are done relative to this path.

### Returns
- **&Path** - The root path associated with the matcher.
```

--------------------------------

### Handle Symlink Loops

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Demonstrates how the walker handles circular symlink references.

```rust
        let mut builder = WalkBuilder::new(td.path());
        assert_paths(td.path(), &builder, &["a", "a/b", "a/b/c"]);
        assert_paths(td.path(), &builder.follow_links(true), &["a", "a/b"]);
```

--------------------------------

### Test Error Handling

Source: https://docs.rs/ignore/latest/src/ignore/dir.rs.html

Demonstrates how the builder reports errors when encountering malformed ignore files.

```rust
#[test]
    fn errored() {
        let td = tmpdir();
        wfile(td.path().join(".gitignore"), "{foo");

        let (_, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert!(err.is_some());
    }
```

```rust
#[test]
    fn errored_both() {
        let td = tmpdir();
        wfile(td.path().join(".gitignore"), "{foo");
        wfile(td.path().join(".ignore"), "{bar");

        let (_, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert_eq!(2, partial(err.expect("an error")).len());
    }
```

```rust
#[test]
    fn errored_partial() {
        let td = tmpdir();
        mkdirp(td.path().join(".git"));
        wfile(td.path().join(".gitignore"), "{foo\nbar");

        let (ig, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert!(err.is_some());
        assert!(ig.matched("bar", false).is_ignore());
    }
```

```rust
#[test]
    fn errored_partial_and_ignore() {
        let td = tmpdir();
        wfile(td.path().join(".gitignore"), "{foo\nbar");
        wfile(td.path().join(".ignore"), "!bar");

        let (ig, err) = IgnoreBuilder::new().build().add_child(td.path());
        assert!(err.is_some());
        assert!(ig.matched("bar", false).is_whitelist());
    }
```

--------------------------------

### Match Path

Source: https://docs.rs/ignore/latest/src/ignore/incremental.rs.html

Matches a root-relative path against ignore files, loading and caching directories as needed.

```rust
    pub fn matched<P: AsRef<Path>>(
        &mut self,
        path: P,
        is_dir: bool,
    ) -> IncrementalMatch {
        let (matched, err) = self.matched_with_errors(path, is_dir);
        if let Some(err) = err {
            log::debug!("error while loading ignore files: {err}");
        }
        matched
    }
```

--------------------------------

### Read Git Configuration Files

Source: https://docs.rs/ignore/latest/src/ignore/gitignore.rs.html

Internal helper functions to read contents from global and system-level git configuration files.

```rust
fn gitconfig_global_env_contents() -> Option<Vec<u8>> {
    let path = std::env::var_os("GIT_CONFIG_GLOBAL").map(PathBuf::from)?;
    if path.as_os_str().is_empty() {
        return None;
    }
    let mut file = BufReader::new(File::open(path).ok()?);
    let mut contents = vec![];
    file.read_to_end(&mut contents).ok().map(|_| contents)
}
```

```rust
fn gitconfig_system_contents() -> Option<Vec<u8>> {
    let path = std::env::var_os("GIT_CONFIG_SYSTEM")
        .map(PathBuf::from)
        .filter(|x| !x.as_os_str().is_empty())
        .unwrap_or_else(|| PathBuf::from("/etc/gitconfig"));
    let mut file = BufReader::new(File::open(path).ok()?);
    let mut contents = vec![];
    file.read_to_end(&mut contents).ok().map(|_| contents)
}
```

```rust
fn gitconfig_home_contents() -> Option<Vec<u8>> {
    let home = home_dir()?;
    let mut file = BufReader::new(File::open(home.join(".gitconfig")).ok()?);
```

--------------------------------

### Retrieve Gitignore Path

Source: https://docs.rs/ignore/latest/ignore/gitignore/struct.Gitignore.html

Returns the directory path associated with the matcher.

```rust
pub fn path(&self) -> &Path
```

--------------------------------

### Verify stdin root handling

Source: https://docs.rs/ignore/latest/src/ignore/incremental.rs.html

Tests that only the literal '-' string is treated as standard input, while './-' is treated as a standard path.

```rust
#[test]
    fn dot_dash_root_is_not_stdin() {
        let m = one_matcher(&builder("./-"));
        assert_eq!(m.root(), Path::new("./-"));
        assert_eq!(m.normalize("./-/file"), Some(PathBuf::from("file")));
    }
```

--------------------------------

### Explicit Ignore File Configuration

Source: https://docs.rs/ignore/latest/src/ignore/walk.rs.html

Shows how to add a custom ignore file to the builder and how it behaves with standard filters enabled or disabled.

```rust
    #[test]
    fn explicit_ignore() {
        let td = tmpdir();
        let igpath = td.path().join(".not-an-ignore");
        mkdirp(td.path().join("a"));
        wfile(&igpath, "foo");
        wfile(td.path().join("foo"), "");
        wfile(td.path().join("a/foo"), "");
        wfile(td.path().join("bar"), "");
        wfile(td.path().join("a/bar"), "");

        let mut builder = WalkBuilder::new(td.path());
        assert!(builder.add_ignore(&igpath).is_none());
        assert_paths(td.path(), &builder, &["bar", "a", "a/bar"]);
    }
```

```rust
    #[test]
    fn explicit_ignore_exclusive_use() {
        let td = tmpdir();
        let igpath = td.path().join(".not-an-ignore");
        mkdirp(td.path().join("a"));
        wfile(&igpath, "foo");
        wfile(td.path().join("foo"), "");
        wfile(td.path().join("a/foo"), "");
        wfile(td.path().join("bar"), "");
        wfile(td.path().join("a/bar"), "");

        let mut builder = WalkBuilder::new(td.path());
        builder.standard_filters(false);
        assert!(builder.add_ignore(&igpath).is_none());
        assert_paths(
            td.path(),
            &builder,
            &[".not-an-ignore", "bar", "a", "a/bar"],
        );
    }
```
Tokens:
Raw