### WalkBuilder::new

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

Creates a new WalkBuilder for a specified directory. This is the starting point for configuring a directory traversal.

```APIDOC
## WalkBuilder::new

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

### Signature
`pub fn new<P: AsRef<Path>>(path: P) -> WalkBuilder`
```

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

### Get Device Number (Unsupported)

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

Provides an error for unsupported platforms when attempting to get the device number, indicating that same_file_system is not available.

```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 File Type Definitions

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

Return the set of current file type definitions. Definitions and their associated globs are sorted lexicographically.

```rust
pub fn definitions(&self) -> &[FileTypeDef] {
    &self.defs
}
```

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

### Advanced Directory Traversal with WalkBuilder

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

This example shows how to use WalkBuilder to customize directory traversal. By default, hidden files and directories are ignored; this can be disabled by setting `hidden(false)`.

```rust
use ignore::WalkBuilder;

for result in WalkBuilder::new("./").hidden(false).build() {
    println!("{:?}", result);
}
```

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

### Create a new TypesBuilder

Source: https://docs.rs/ignore/latest/ignore/types/struct.TypesBuilder.html

Initializes a new TypesBuilder instance. The builder starts with no type definitions and requires explicit addition of defaults or custom definitions.

```rust
pub fn new() -> TypesBuilder
```

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

### Get File Type Definitions

Source: https://docs.rs/ignore/latest/ignore/types/struct.TypesBuilder.html

Retrieves the current file type definitions managed by the builder. The returned definitions and their associated globs are sorted.

```rust
pub fn definitions(&self) -> Vec<FileTypeDef>
```

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

### Empty Types Initializer

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

Creates a new file type matcher that initially matches no paths and contains no file type definitions. This is useful for starting with a clean state.

```rust
pub fn empty() -> Types {
    Types {
        defs: vec![],
        selections: vec![],
        has_selected: false,
        glob_to_selection: vec![],
        set: GlobSetBuilder::new().build().unwrap(),
        matches: Arc::new(Pool::new(|| vec![])),
    }
}
```

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

### Create and Use Default File Type Matcher

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

Demonstrates creating a file type matcher using default definitions and selecting a specific type like 'rust'. Use this to quickly match common file types.

```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());
```

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

### Creating a Temporary Directory

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

This snippet demonstrates the creation of a temporary directory using `TempDir::new()`. It returns a `Result` which can be `Ok(TempDir)` on success or an error if creation fails after multiple attempts.

```rust
pub fn new() -> Result<TempDir, io::Error> {
    for _ in 0..TRIES {
        let path = env::temp_dir();
        let mut path = path.join("rust-tempdir-XXXXXX");
        if let Ok(path) = mkdtemp(path.as_os_str()) {
            let path = PathBuf::from(path);
            return Ok(TempDir(path));
        }
    }
    Err(err!("failed to create temp dir after {} tries", TRIES))
}
```

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

### Set Maximum Traversal Depth

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

Configures the maximum depth for directory traversal. `max_depth(Some(0))` includes only the starting directory, `max_depth(Some(1))` includes the starting directory and its immediate children, and so on.

```rust
let mut 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"],
);
assert_paths(td.path(), builder.max_depth(Some(0)), &[]);
assert_paths(td.path(), builder.max_depth(Some(1)), &["a", "foo"]);
assert_paths(
    td.path(),
    builder.max_depth(Some(2)),
    &["a", "a/b", "foo", "a/foo"],
);
```

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

### Building and Matching Ignore Rules

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

Demonstrates creating an IgnoreBuilder, adding parent and child directories, and matching files against the ignore rules. This is useful for setting up ignore configurations programmatically.

```rust
let td = tmpdir();
mkdirp(td.path().join(".git"));
mkdirp(td.path().join("src/llvm"));
wfile(td.path().join(".gitignore"), "/llvm/\nfoo");

let ig0 = IgnoreBuilder::new().build();
let (ig1, err) = ig0.add_parents(td.path().join("src"));
assert!(err.is_none());
let (ig2, err) = ig1.add_child("src");
assert!(err.is_none());

assert!(ig1.matched("llvm", true).is_none());
assert!(ig2.matched("llvm", true).is_none());
assert!(ig2.matched("src/llvm", true).is_none());
assert!(ig2.matched("foo", false).is_ignore());
assert!(ig2.matched("src/foo", false).is_ignore());
```

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

### T::type_id

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

Gets the `TypeId` of the current type. This is useful for runtime type identification.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
type_id

### Parameters
- `&self`: A reference to the instance.

### Returns
- `TypeId`: The unique identifier for the type of `self`.
```

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

### Get DirEntry Depth

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

Returns the depth of the DirEntry relative to the root directory.

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

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

### Create Gitignore from File Path

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

Initializes a Gitignore matcher from a specified file path. Handles potential I/O errors by ignoring them. For granular error control, use GitignoreBuilder.

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

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

### Basic Gitignore Pattern Matching

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

Demonstrates various patterns for ignoring and not ignoring files, including wildcards, directory patterns, and negation.

```rust
not_ignored!(ignot3, ROOT, "/src/*.rs", "src/grep/src/main.rs");
not_ignored!(ignot4, ROOT, "/*.c", "mozilla-sha1/sha1.c");
not_ignored!(ignot5, ROOT, "/src/*.rs", "src/grep/src/main.rs");
not_ignored!(ignot6, ROOT, "*.rs\n!src/main.rs", "src/main.rs");
not_ignored!(ignot7, ROOT, "foo/", "foo", false);
not_ignored!(ignot8, ROOT, "**/foo/**", "wat/src/afoo/bar/baz");
not_ignored!(ignot9, ROOT, "**/foo/**", "wat/src/fooa/bar/baz");
not_ignored!(ignot10, ROOT, "**/foo/bar", "foo/src/bar");
not_ignored!(ignot11, ROOT, "#foo", "#foo");
not_ignored!(ignot12, ROOT, "\n\n\n", "foo");
not_ignored!(ignot13, ROOT, "foo/**", "foo", true);
not_ignored!(ignot14, ROOT, "m4/ltoptions.m4", "./third_party/protobuf/csharp/src/packages/repositories.config");
not_ignored!(ignot15, ROOT, "!/bar", "foo/bar");
not_ignored!(ignot16, ROOT, "*\n!**/", "foo", true);
not_ignored!(ignot17, ROOT, "src/*.rs", "src/grep/src/main.rs");
not_ignored!(ignot18, ROOT, "path1/*", "path2/path1/foo");
not_ignored!(ignot19, ROOT, "s*.rs", "src/foo.rs")
```

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

### T::deref_mut

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

Dereferences a raw pointer to get a mutable reference to the value. This is an unsafe operation.

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

### Description
Mutably dereferences the given pointer.

### Method
deref_mut

### Parameters
- `ptr`: A `usize` representing the raw pointer.

### Returns
- `&'a mut T`: A mutable reference to the value at the pointer.
```

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

### Generic Pointable Implementation - Init Function

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

Safely initializes a Glob instance at a given pointer address.

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

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

### T::deref

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

Dereferences a raw pointer to get an immutable reference to the value. This is an unsafe operation.

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

### Description
Dereferences the given pointer.

### Method
deref

### Parameters
- `ptr`: A `usize` representing the raw pointer.

### Returns
- `&'a T`: An immutable reference to the value at the pointer.
```

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

### Walk Directory with Symlinks

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

Demonstrates walking a directory containing symlinks. The first assertion shows behavior without following links, and the second shows behavior when links are followed.

```rust
    #[cfg(unix)] // because symlinks on windows are weird
    #[test]
    fn symlinks() {
        let td = tmpdir();
        mkdirp(td.path().join("a/b"));
        symlink(td.path().join("a/b"), td.path().join("z"));
        wfile(td.path().join("a/b/foo"), "");

        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"],
        );
    }
```

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

### min_depth

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

Sets the minimum depth from which the traversal should start. If `None`, there is no minimum depth restriction.

```APIDOC
## min_depth

### Description
Sets the minimum depth from which the traversal should start. If `None`, there is no minimum depth restriction.

### Method
`WalkBuilder::min_depth(&mut self, depth: Option<usize>) -> &mut WalkBuilder`

### Parameters
* **depth** (`Option<usize>`) - The minimum depth for recursion. `None` means no restriction.

### Returns
`&mut WalkBuilder` - A mutable reference to the `WalkBuilder` for chaining.
```

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

### Create New GitignoreBuilder

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

Initializes a new GitignoreBuilder for a specific root path. Paths are matched relative to this root.

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

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

### Get the number of ignore globs

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

Returns the total count of globs that are configured to ignore files.

```rust
pub fn num_ignores(&self) -> u64 {
        self.num_ignores
    }
```

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

### Add Custom File Type Definitions

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

Illustrates extending default file type definitions with custom ones like '*.foo' and '*.bar'. Use this to define and match your own file types.

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

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

assert!(matcher.matched("x.foo", false).is_whitelist());
assert!(matcher.matched("x.bar", false).is_ignore());
```

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

### Get Source Path of Glob

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

Returns the file path that originally defined this glob pattern.

```rust
pub fn from(&self) -> Option<&Path>
```

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

### Build Ignore with Custom Ignore File

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

Demonstrates building an IgnoreBuilder and adding a custom ignore file. This is useful when you need to specify a non-standard ignore file name.

```rust
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());
```

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

### Get Original Glob Pattern

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

Retrieves the original glob pattern string as it was defined in a gitignore file.

```rust
pub fn original(&self) -> &str
```

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

### Provide Error Context (Nightly)

Source: https://docs.rs/ignore/latest/ignore/enum.Error.html

The `provide` method is a nightly-only experimental API for providing type-based access to error context, intended for error reporting.

```rust
fn provide<'a>(&'a self, request: &mut Request<'a>)
```

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

### Get Device Number (Unix)

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

Retrieves the device number for a given path on Unix-like systems using metadata.

```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())
}
```

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

### Handle .ignore File

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

Demonstrates the use of a standard .ignore file for specifying ignore rules. This is an alternative to .gitignore for projects not using Git.

```rust
let td = tmpdir();
wfile(td.path().join(".ignore"), "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());
```

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

### Get DirEntry File Type

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

Returns the file type of the entry, if available. Returns None for stdin entries.

```rust
pub fn file_type(&self) -> Option<FileType>
```

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

### Test Utility: Create Directory Recursively

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

Helper function to create a directory and any necessary parent directories. It unwraps any I/O errors during directory creation.

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

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

### WalkBuilder::new() Constructor

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

Initializes a new WalkBuilder for a specified directory. Use `add` to traverse multiple directories.

```rust
pub fn new<P: AsRef<Path>>(path: P) -> WalkBuilder {
    WalkBuilder {
        paths: vec![path.as_ref().to_path_buf()],
        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(),
    }
}
```

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

### Get DirEntry Metadata

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

Retrieves the metadata for the file pointed to by the DirEntry. Returns a Result containing Metadata or an Error.

```rust
pub fn metadata(&self) -> Result<Metadata, Error>
```

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

### Define File Types Based on Other Definitions

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

Demonstrates creating a new file type definition that includes other definitions, such as 'foo' and 'cpp' for a 'bar' type. This allows for hierarchical or composite file type 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());
```

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

### Get Actual Compiled Glob Pattern

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

Retrieves the actual glob pattern that was compiled to respect gitignore semantics.

```rust
pub fn actual(&self) -> &str
```

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

### Strip Prefix from Path

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

Removes a given prefix from a path if it exists. If the path does not start with the prefix, it is returned unchanged.

```rust
fn strip_if_is_prefix<'a, P: AsRef<Path> + ?Sized>(
    prefix: &'a P,
    path: &'a Path,
) -> &'a Path {
    strip_prefix(prefix, path).map_or(path, |p| p)
}
```

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

### Python Type Matching

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

Demonstrates matching types for Python files.

```rust
matched!(match10, types(), vec!["py"], vec![], "main.py");
matched!(match11, types(), vec!["python"], vec![], "main.py");
```

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

### Select File Type

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

Marks a file type for selection. If 'all' is provided, all currently defined file types are selected. Returns a mutable reference to the builder.

```rust
pub fn select(&mut self, name: &str) -> &mut TypesBuilder {
        if name == "all" {
            for name in self.types.keys() {
                self.selections.push(Selection::Select(name.to_string(), ()));
            }
        } else {
            self.selections.push(Selection::Select(name.to_string(), ()));
        }
        self
    }
```

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

### Get the number of whitelist globs

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

Returns the total count of globs that are configured to whitelist files, overriding ignore rules.

```rust
pub fn num_whitelists(&self) -> u64 {
        self.num_whitelists
    }
```

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

### Windows DirEntry Raw from Entry

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

Creates a DirEntryRaw for Windows systems from a fs::DirEntry, including metadata. Requires `fs::FileType`.

```rust
#[cfg(windows)]
    fn from_entry_os(
        depth: usize,
        ent: &fs::DirEntry,
        ty: fs::FileType,
    ) -> Result<DirEntryRaw, Error> {
        let md = ent.metadata().map_err(|err| {
            let err = Error::Io(io::Error::from(err)).with_path(ent.path());
            Error::WithDepth { depth, err: Box::new(err) }
        })?;
        Ok(DirEntryRaw {
            path: ent.path(),
            ty,
            follow_link: false,
            depth,
            metadata: md,
        })
    }
```

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

### Get Parent Ignore Matcher

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

Returns the parent Ignore matcher if one exists. This allows for traversing up the directory tree.

```rust
/// Return this matcher's parent, if one exists.
    pub(crate) fn parent(&self) -> Option<Ignore> {
        self.inner.parent.as_ref().map(|parent| Ignore {
            inner: parent.clone(),
            absolute_base: self.absolute_base.clone(),
        })
    }
```

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

### Get DirEntry Inode Number

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

Retrieves the inode number of the DirEntry, if it exists. Returns None if no inode number is available.

```rust
pub fn ino(&self) -> Option<u64>
```

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

### Test Utility: Create Temporary Directory

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

Helper function to create a new temporary directory. It unwraps any I/O errors during directory creation.

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

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

### Get DirEntry Path

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

Retrieves the full path represented by the DirEntry. Use `path` for a reference and `into_path` to take ownership.

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

```rust
pub fn into_path(self) -> PathBuf
```

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

### Get Stdout File Handle

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

Retrieves a file handle for stdout if it's redirected to a file. This prevents searching files that are being written to.

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

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

### Create Empty Gitignore Matcher

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

Returns a new, empty Gitignore matcher that will not match any file paths. Its associated path is empty.

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

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

### TypesBuilder::select

Source: https://docs.rs/ignore/latest/ignore/types/struct.TypesBuilder.html

Marks a file type for selection. If 'all' is provided, all currently defined file types are selected.

```APIDOC
## TypesBuilder::select

### Description
Select the file type given by `name`. If `name` is `all`, then all file types currently defined are selected.

### Method
`select(&mut self, name: &str)`

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the file type to select.

### Returns
A mutable reference to the `TypesBuilder`.
```

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

### Get Ignore Matcher Directory Path

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

Retrieves the directory path associated with an Ignore matcher. This is typically used in test scenarios.

```rust
/// Return the directory path of this matcher.
    #[cfg(test)]
    pub(crate) fn path(&self) -> &Path {
        &self.inner.dir
    }
```

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

### Add Custom File Type Definitions

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

Illustrates extending default file type definitions with custom ones, such as '*.foo' and '*.bar', and then selecting only specific types. This is useful for user-defined file patterns.

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

let mut builder = TypesBuilder::new();
builder.add_defaults();
builder.add("foo", "*.foo");
// Another way of adding a file type definition.
// This is useful when accepting input from an end user.
builder.add_def("bar:*.bar");
// Note: we only select `foo`, not `bar`.
builder.select("foo");
let matcher = builder.build().unwrap();

assert!(matcher.matched("x.foo", false).is_whitelist());
// This is ignored because we only selected the `foo` file type.
assert!(matcher.matched("x.bar", false).is_ignore());
```

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

### Get Number of Selections

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

Returns the number of selections used in this matcher. This indicates how many file type rules are currently active.

```rust
pub fn len(&self) -> usize {
    self.selections.len()
}
```

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

### Get Error Cause (Deprecated)

Source: https://docs.rs/ignore/latest/ignore/enum.Error.html

The `cause` method is deprecated and replaced by `Error::source`. It was used to retrieve the underlying cause of an error.

```rust
fn cause(&self) -> Option<&dyn Error>
```

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

### Gitignore::new

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

Creates a new gitignore matcher from a specified file path. It handles potential I/O errors by ignoring them and always returns a valid matcher, even if it's empty or contains invalid globs.

```APIDOC
## Gitignore::new

### Description
Creates a new gitignore matcher from the gitignore file path given. If it’s desirable to include multiple gitignore files in a single matcher, or read gitignore globs from a different source, then use `GitignoreBuilder`. This always returns a valid matcher, even if it’s empty. In particular, a Gitignore file can be partially valid, e.g., when one glob is invalid but the rest aren’t. Note that I/O errors are ignored. For more granular control over errors, use `GitignoreBuilder`.

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

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

### Generic Clone to Uninit (Nightly)

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

Nightly-only experimental API for performing copy-assignment to uninitialized memory.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

### Description
Performs copy-assignment from `self` to `dest`.

### Method
clone_to_uninit

### Parameters
- **dest** (**mut u8*) - A mutable pointer to the destination memory.

### Response
None
```

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

### Get Lower-Level Error Source

Source: https://docs.rs/ignore/latest/ignore/enum.Error.html

The `source` method returns the lower-level source of the error, if any. This is part of the standard `Error` trait implementation.

```rust
fn source(&self) -> Option<&(dyn Error + 'static)>
```

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

### Get Error Description (Deprecated)

Source: https://docs.rs/ignore/latest/ignore/enum.Error.html

The `description` method is deprecated and should not be used. Prefer the `Display` implementation or `to_string()` for obtaining error descriptions.

```rust
fn description(&self) -> &str
```

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

### Select a File Type

Source: https://docs.rs/ignore/latest/ignore/types/struct.TypesBuilder.html

Marks a specific file type for inclusion in the matcher. If 'all' is provided, all currently defined file types are selected.

```rust
pub fn select(&mut self, name: &str) -> &mut TypesBuilder
```

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

### Respect .gitignore in Parent Directory

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

Demonstrates how .gitignore files in parent directories are respected when traversing a subdirectory. The .gitignore file in the root affects traversal within the 'a' directory.

```rust
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 Total Number of Globs

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

Returns the total count of globs within the Gitignore matcher, including both ignore and whitelist patterns.

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

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

### Create New OverrideBuilder

Source: https://docs.rs/ignore/latest/ignore/overrides/struct.OverrideBuilder.html

Initializes a new OverrideBuilder. Matching is performed relative to the specified directory path.

```rust
pub fn new<P: AsRef<Path>>(path: P) -> OverrideBuilder
```

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

### Get File Type Name

Source: https://docs.rs/ignore/latest/ignore/types/struct.FileTypeDef.html

Retrieves the name of the file type from a FileTypeDef instance. This is useful for identifying the type of file being matched.

```rust
pub fn name(&self) -> &str
```

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

### Get Override Directory Path

Source: https://docs.rs/ignore/latest/ignore/overrides/struct.Override.html

Retrieves the directory path associated with this Override set. All path matching is performed relative to this directory.

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

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

### Add Globs from File

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

Adds globs from a specified file, formatted as a gitignore file. Partial errors are possible if some globs fail to add.

```rust
pub fn add<P: AsRef<Path>>(&mut self, path: P) -> Option<Error>
```

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

### ParallelVisitorBuilder::build Method

Source: https://docs.rs/ignore/latest/ignore/trait.ParallelVisitorBuilder.html

This method is responsible for creating per-thread ParallelVisitor instances when using WalkParallel.

```rust
fn build(&mut self) -> Box<dyn ParallelVisitor + 's>
```

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

### Get Device Number (Windows)

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

Retrieves the device number (volume serial number) for a given path on Windows systems using winapi_util.

```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())
}
```

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

### Build Global Gitignore Matcher

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

Creates a global gitignore matcher, consuming the builder. Derives the path from git's global configuration.

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

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

### Get Default Excludes File Path

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

Determines the default file 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")
        .and_then(|x| if x.is_empty() { None } else { Some(PathBuf::from(x)) })
        .or_else(|| home_dir().map(|p| p.join(".config")))
        .map(|x| x.join("git/ignore"))
}
```

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

### Get Recursion Depth

Source: https://docs.rs/ignore/latest/ignore/enum.Error.html

Use `depth` to retrieve the depth associated with recursively walking a directory, if the error originated from a recursive directory iterator.

```rust
pub fn depth(&self) -> Option<usize>
```

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

### DirEntry Methods

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

Provides methods to interact with a directory entry, retrieve its path, metadata, file type, and check its properties.

```APIDOC
## DirEntry Methods

### Description
Provides methods to interact with a directory entry, retrieve its path, metadata, file type, and check its properties.

### Methods

- **`path()`** -> `&Path`
  Returns the full path that this entry represents.

- **`into_path()`** -> `PathBuf`
  Moves ownership of the path from the entry.

- **`path_is_symlink()`** -> `bool`
  Returns true if and only if this entry corresponds to a symbolic link.

- **`is_stdin()`** -> `bool`
  Returns true if and only if this entry corresponds to stdin.

- **`metadata()`** -> `Result<Metadata, Error>`
  Returns the metadata for the file that this entry points to.

- **`file_type()`** -> `Option<FileType>`
  Returns the file type for the file that this entry points to. Returns `None` if the entry corresponds to stdin.

- **`file_name()`** -> `&OsStr`
  Returns the file name of this entry. If the entry has no file name (e.g., `/`), the full path is returned.

- **`depth()`** -> `usize`
  Returns the depth at which this entry was created relative to the root.

- **`ino()`** -> `Option<u64>` (Unix only)
  Returns the underlying inode number if one exists.

- **`error()`** -> `Option<&Error>`
  Returns an error, if one exists, associated with processing this entry. This typically refers to problems parsing ignore files.
```

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

### Helper to Create Gitignore from String

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

A test helper function that creates a Gitignore instance from a given root path and a string containing gitignore rules.

```Rust
fn gi_from_str<P: AsRef<Path>>(root: P, s: &str) -> Gitignore {
    let mut builder = GitignoreBuilder::new(root);
    builder.add_str(None, s).unwrap();
    builder.build().unwrap()
}
```

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

### Strip path for matching

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

Prepares a given path for matching by stripping its prefix relative to the gitignore matcher's root. This ensures paths are compared correctly.

```rust
/// Strips the given path such that it's suitable for matching with this
    /// gitignore matcher.
    
```

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

### Get File Type Globs

Source: https://docs.rs/ignore/latest/ignore/types/struct.FileTypeDef.html

Retrieves the list of globs used to recognize this file type. These globs define the patterns for matching files.

```rust
pub fn globs(&self) -> &[String]
```

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

### Get Inner Value of Match

Source: https://docs.rs/ignore/latest/ignore/enum.Match.html

Returns an Option containing a reference to the value inside the match if it exists. Returns None if the match is None.

```rust
pub fn inner(&self) -> Option<&T>
```

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

### Add Glob to Overrides

Source: https://docs.rs/ignore/latest/ignore/overrides/struct.OverrideBuilder.html

Adds a glob pattern to the set of overrides. Globs starting with '!' are treated as ignore rules, while others are whitelist matches.

```rust
pub fn add(&mut self, glob: &str) -> Result<&mut OverrideBuilder, Error>
```

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

### Create an Empty Override Matcher

Source: https://docs.rs/ignore/latest/ignore/overrides/struct.Override.html

Returns an empty Override matcher that will not match any file path. Useful for initializing an override set.

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

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

### Test Helper: Create Directory Recursively

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

Utility function for tests to create a directory and any necessary parent directories.

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

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

### Get the root path of the Gitignore matcher

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

Retrieves the root directory associated with this gitignore matcher. All path matching operations are performed relative to this root.

```rust
pub fn path(&self) -> &Path {
        &*self.root
    }
```

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

### Get Absolute Base Path

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

Retrieves the first absolute path of an absolute parent, if one exists. This is used for resolving relative paths correctly.

```rust
/// Returns the first absolute path of the first absolute parent, if
/// one exists.
fn absolute_base(&self) -> Option<&Path> {
    self.absolute_base.as_ref().map(|p| &***p)
}
```

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

### Windows DirEntry Raw from Path

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

Creates a DirEntryRaw for Windows systems from a PathBuf, including file metadata. Handles potential IO errors.

```rust
#[cfg(windows)]
    fn from_path(
        depth: usize,
        pb: PathBuf,
        link: bool,
    ) -> Result<DirEntryRaw, Error> {
        let md =
            fs::metadata(&pb).map_err(|err| Error::Io(err).with_path(&pb))?;
        Ok(DirEntryRaw {
            path: pb,
            ty: md.file_type(),
            follow_link: link,
            depth,
            metadata: md,
        })
    }
```

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

### Case-Insensitive Matching

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

Demonstrates how to configure and use case-insensitive matching for gitignore patterns. Verifies matching behavior for different cases.

```rust
let gi = GitignoreBuilder::new(ROOT)
    .case_insensitive(true)
    .unwrap()
    .add_str(None, "*.html")
    .unwrap()
    .build()
    .unwrap();
assert!(gi.matched("foo.html", false).is_ignore());
assert!(gi.matched("foo.HTML", false).is_ignore());
assert!(!gi.matched("foo.htm", false).is_ignore());
assert!(!gi.matched("foo.HTM", false).is_ignore())
```

```rust
ignored!(cs1, ROOT, "*.html", "foo.html");
not_ignored!(cs2, ROOT, "*.html", "foo.HTML");
not_ignored!(cs3, ROOT, "*.html", "foo.htm");
not_ignored!(cs4, ROOT, "*.html", "foo.HTM")
```

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

### Get Parent Ignore Matchers Iterator

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

Provides an iterator over all parent ignore matchers, including the current one. This is useful for traversing the ignore hierarchy.

```rust
/// Returns an iterator over parent ignore matchers, including this one.
pub(crate) fn parents(&self) -> Parents<'_> {
    Parents(Some(IgnoreRef { inner: &self.inner }))
}
```

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

### Get file type definitions from Types matcher

Source: https://docs.rs/ignore/latest/ignore/types/struct.Types.html

Use `definitions()` to access the set of current file type definitions. Both definitions and globs are sorted.

```rust
pub fn definitions(&self) -> &[FileTypeDef]
```

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

### Initialize IgnoreBuilder

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

Creates a new IgnoreBuilder with default settings. Note that using this outside of tests without calling `current_dir()` might be a bug.

```rust
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,
            },
        }
```

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

### Get DirEntry File Name

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

Retrieves the file name of the DirEntry. Returns the full path if no specific file name exists (e.g., for '/').

```rust
pub fn file_name(&self) -> &OsStr
```

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

### path

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

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

```APIDOC
## path

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

### Method
GET

### Endpoint
/path

### Parameters
None

### Response
#### Success Response (200)
- **root** (PathBuf) - The root path of the gitignore matcher.

### Response Example
```json
{
  "root": "/path/to/gitignore/root"
}
```
```

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

### OverrideBuilder::new

Source: https://docs.rs/ignore/latest/ignore/overrides/struct.OverrideBuilder.html

Creates a new OverrideBuilder instance. Matching is performed relative to the provided directory path.

```APIDOC
## new

### Description
Create a new override builder.
Matching is done relative to the directory path provided.

### Method
`pub fn new<P: AsRef<Path>>(path: P) -> OverrideBuilder`

### Parameters
* `path` (P): A path to a directory relative to which matching will be performed.
```

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

### Test Case: Wildcard Prefix Match

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

Tests if the gitignore logic correctly ignores files starting with 's' and ending with '.rs', specifically 'sfoo.rs'.

```Rust
ignored!(ig42, ROOT, "s*.rs", "sfoo.rs");
```

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

### Handle .gitignore with .jj Directory

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

Tests the scenario where a .gitignore file is present alongside a .jj directory, which might indicate a different version control system or configuration.

```rust
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());
```

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

### Types::empty

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

Creates a new `Types` instance that initially matches no paths and contains no file type definitions. This is useful for starting with an empty matcher.

```APIDOC
## Types::empty

### Description
Creates a new file type matcher that never matches any path and contains no file type definitions.

### Signature
```rust
pub fn empty() -> Types
```

### Returns
A new, empty `Types` instance.
```

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

### DirEntry Methods

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

This section details the public methods available on the DirEntry struct, allowing users to interact with directory entries.

```APIDOC
## DirEntry Methods

### `path()`

#### Description
Returns the full path that this entry represents.

#### Method
`&self.path()`

### `into_path()`

#### Description
Returns the full path that this entry represents. This method consumes the `DirEntry` and returns ownership of the `PathBuf`.

#### Method
`self.into_path()`

### `path_is_symlink()`

#### Description
Checks if this entry corresponds to a symbolic link.

#### Method
`&self.path_is_symlink()`

### `is_stdin()`

#### Description
Returns `true` if this entry corresponds to standard input (depth 0 and filename '-').

#### Method
`&self.is_stdin()`

### `metadata()`

#### Description
Retrieves the metadata for the file pointed to by this entry.

#### Method
`&self.metadata()`

#### Returns
`Result<Metadata, Error>` - The metadata of the file or an error if it cannot be retrieved.

### `file_type()`

#### Description
Returns the file type for the file pointed to by this entry. Returns `None` if the entry corresponds to stdin.

#### Method
`&self.file_type()`

#### Returns
`Option<FileType>` - The file type of the entry, or `None`.

### `file_name()`

#### Description
Returns the file name of this entry. If the entry has no file name (e.g., root directory), the full path is returned.

#### Method
`&self.file_name()`

### `depth()`

#### Description
Returns the depth of this entry relative to the root.

#### Method
`&self.depth()`

### `ino()`

#### Description
Returns the underlying inode number if it exists. Returns `None` if the entry does not have an inode number.

#### Method
`&self.ino()`

#### Returns
`Option<u64>` - The inode number, or `None`.

### `error()`

#### Description
Returns an error, if one exists, associated with processing this entry. This typically relates to parsing ignore files.

#### Method
`&self.error()`

#### Returns
`Option<&Error>` - A reference to the associated error, or `None`.
```

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

### Filter Directory Entries

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

Demonstrates using the `filter_entry` option to exclude specific entries during traversal. This example filters out any entry whose file name is 'a'.

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

        assert_paths(
            td.path(),
            &WalkBuilder::new(td.path()),
            &["x", "x/y", "x/y/foo", "a", "a/b", "a/b/foo", "a/b/c"],
        );

        assert_paths(
            td.path(),
            &WalkBuilder::new(td.path())
                .filter_entry(|entry| entry.file_name() != OsStr::new("a")),
            &["x", "x/y", "x/y/foo"],
        );
    }
```

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

### Get Global Gitignore Path

Source: https://docs.rs/ignore/latest/ignore/gitignore/fn.gitconfig_excludes_path.html

Returns the file path of the current environment's global gitignore file. The returned path may not necessarily exist.

```rust
pub fn gitconfig_excludes_path() -> Option<PathBuf>
```

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

### Unsupported Platform DirEntry Raw from Entry

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

Placeholder implementation for unsupported platforms (e.g., wasm32) that returns an error. Used when not Windows or Unix.

```rust
// Placeholder implementation to allow compiling on non-standard platforms
    // (e.g. wasm32).
    #[cfg(not(any(windows, unix)))]
    fn from_entry_os(
        depth: usize,
        ent: &fs::DirEntry,
        ty: fs::FileType,
    ) -> Result<DirEntryRaw, Error> {
        Err(Error::Io(io::Error::new(
            io::ErrorKind::Other,
            "unsupported platform",
        )))
    }
```

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

### Prevent Crossing File System Boundaries

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

Disables descending into directories that reside on different file systems than the starting path. This option is supported on Unix and Windows.

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

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

### Temporary Directory Creation

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

Creates a temporary directory for testing purposes. Ensures cleanup after use.

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

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

### TypesBuilder::new

Source: https://docs.rs/ignore/latest/ignore/types/struct.TypesBuilder.html

Creates a new, empty TypesBuilder. Users can then add default definitions, select specific types, or define new types with glob patterns.

```APIDOC
## TypesBuilder::new

### Description
Create a new builder for a file type matcher. The builder contains _no_ type definitions to start with. A set of default type definitions can be added with `add_defaults`, and additional type definitions can be added with `select` and `negate`.

### Method
`new()`

### Returns
A new `TypesBuilder` instance.
```

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

### Check if a directory entry is hidden (Unix)

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

On Unix-like systems, this function checks if the base name of a path starts with a dot (`.`). It uses an optimized check for efficiency.

```rust
use std::{ffi::OsStr, path::Path};

use crate::walk::DirEntry;

/// Returns true if and only if this entry is considered to be hidden.
///
/// This only returns true if the base name of the path starts with a `.`.
///
/// On Unix, this implements a more optimized check.
#[cfg(unix)]
pub(crate) fn is_hidden(dent: &DirEntry) -> bool {
    use std::os::unix::ffi::OsStrExt;

    if let Some(name) = file_name(dent.path()) {
        name.as_bytes().get(0) == Some(&b'.')
    } else {
        false
    }
}
```

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

### DirEntryRaw Metadata Retrieval (Windows)

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

Retrieves metadata for a DirEntryRaw on Windows. If `follow_link` is true, it uses `fs::metadata`; otherwise, it returns the pre-stored metadata.

```rust
#[cfg(windows)]
fn metadata_internal(&self) -> Result<fs::Metadata, Error> {
        if self.follow_link {
            fs::metadata(&self.path)
        } else {
            Ok(self.metadata.clone())
        }
        .map_err(|err| Error::Io(io::Error::from(err)).with_path(&self.path))
    }
```

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

### Get DirEntry Error

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

Returns an optional error associated with processing this DirEntry, such as issues parsing ignore files. Errors related to directory traversal itself are reported separately.

```rust
pub fn error(&self) -> Option<&Error>
```

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

### Create Gitignore from Global Ignore File

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

Creates a Gitignore matcher using the global ignore file defined by Git's configuration. It checks standard locations for the global config.

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

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

### Check if a directory entry is hidden (Windows)

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

On Windows, this function checks if a path is hidden by considering both the base name starting with a dot (`.`) and the file's hidden attribute.

```rust
use std::{ffi::OsStr, path::Path};

use crate::walk::DirEntry;

/// Returns true if and only if this entry is considered to be hidden.
///
/// On Windows, this returns true if one of the following is true:
///
/// * The base name of the path starts with a `.`.
/// * The file attributes have the `HIDDEN` property set.
#[cfg(windows)]
pub(crate) fn is_hidden(dent: &DirEntry) -> bool {
    use std::os::windows::fs::MetadataExt;
    use winapi_util::file;

    // This looks like we're doing an extra stat call, but on Windows, the
    // directory traverser reuses the metadata retrieved from each directory
    // entry and stores it on the DirEntry itself. So this is "free."
    if let Ok(md) = dent.metadata() {
        if file::is_hidden(md.file_attributes() as u64) {
            return true;
        }
    }
    if let Some(name) = file_name(dent.path()) {
        name.to_str().map(|s| s.starts_with(".")).unwrap_or(false)
    } else {
        false
    }
}
```