ferralk 1.0.0

Glob matching and parallel filesystem walking, byte-first, with an unsafe-free matcher.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# ferralk

`ferralk` finds files. Give it a glob such as `{src,packages}/**/*.{ts,tsx}`
and it walks the tree in parallel, applies `.gitignore` the way Git does, and
opens only the directories the pattern can reach. It re-exports
`ferralk-glob`, so walker patterns and standalone matchers use the same
component-aware language.

```rust,no_run
use std::error::Error;

use ferralk::{ErrorPolicy, WalkOptions, Walker};

let result = Walker::new(".")
    .include("src/**/*.rs")?
    .exclude("**/generated/**")?
    .respect_git_ignore(true)
    .threads(4)
    .error_policy(ErrorPolicy::Collect)
    .options(WalkOptions::default().files_only(true).sort(true))
    .collect()?;

// `collect()?` succeeded, but that does not mean the walk did: under the
// default `ErrorPolicy::Collect` even a root that does not exist is reported
// in `errors()` below rather than as `Err`.
for entry in result.entries() {
    println!("{}", entry.path().display());
}

for error in result.errors() {
    // `Display` names the operation and path; `source()` says why it failed.
    match error.source() {
        Some(cause) => eprintln!("{error}: {cause}"),
        None => eprintln!("{error}"),
    }
}
# Ok::<(), Box<dyn std::error::Error>>(())
```

Paths remain native `Path` values throughout traversal; use
`WalkEntry::path_bytes()` only when passing a path to a byte-first matcher.
Hidden-entry matching, symlink following, Git ignores, metadata, and sorting
are off until asked for, and recoverable errors are collected next to the
entries by default. Portable `std::fs` traversal is the default, with optional
native Linux and macOS backends for platform-specific performance work.

See the [crate documentation](https://docs.rs/ferralk) for the full API and
[tested recipes](https://docs.rs/ferralk/latest/ferralk/#recipes) (Git ignore
rules, include and exclude lists, stopping early, errors, async use), the
[usage guide](https://github.com/sebastian-software/ferralk/blob/main/docs/usage.md)
for every default and switch, and the
[Ferralk repository](https://github.com/sebastian-software/ferralk) for
benchmarks, compatibility, and development documentation.

<!-- ferramenta-family:start -->
**ferralk** is part of the [Ferramenta](https://ferramenta.dev) family — A family of Rust tools.

Siblings: [ferroni](https://sebastian-software.github.io/ferroni/) — Oniguruma-compatible regex engine · [ferriki](https://github.com/sebastian-software/ferriki) — Shiki-compatible syntax highlighting · [ferromark](https://sebastian-software.github.io/ferromark/) — Markdown to HTML with a secure default and every GFM extension included. · [ferrolex](https://github.com/sebastian-software/ferrolex) — Spell checking for text and code · [ferrocat](https://ferrocat.dev) — Translation catalog engine · [palamedes](https://palamedes.dev) — Internationalization for TypeScript applications · [ferrovia](https://github.com/sebastian-software/ferrovia) — SVGO-compatible SVG optimizer · [ferrugo](https://github.com/sebastian-software/ferrugo) — PDF previews for untrusted files.
<!-- ferramenta-family:end -->

Built by [Sebastian Software](https://oss.sebastian-software.com).