Jeninnet.FileQuery
2.0.0
Requires NuGet 6.0.0 or higher.
dotnet add package Jeninnet.FileQuery --version 2.0.0
NuGet\Install-Package Jeninnet.FileQuery -Version 2.0.0
<PackageReference Include="Jeninnet.FileQuery" Version="2.0.0" />
<PackageVersion Include="Jeninnet.FileQuery" Version="2.0.0" />
<PackageReference Include="Jeninnet.FileQuery" />
paket add Jeninnet.FileQuery --version 2.0.0
#r "nuget: Jeninnet.FileQuery, 2.0.0"
#:package Jeninnet.FileQuery@2.0.0
#addin nuget:?package=Jeninnet.FileQuery&version=2.0.0
#tool nuget:?package=Jeninnet.FileQuery&version=2.0.0
Jeninnet.FileQuery
Deterministic, high-performance file discovery for .NET. One compiled pipeline for
GitIgnore, Glob, and Regex patterns, with metadata results, directory output, .gitignore
ingestion, cancellation, progress, and first-class diagnostics.
using Jeninnet.FileQuery;
using Jeninnet.FileQuery.Enums;
var files = FileQuery.From(@"C:\src\MyProject")
.UsingGlob()
.Where(PatternKind.Glob, ["**/*.cs", "!**/obj/**"])
.IgnoreCase()
.Execute();
foreach (var file in files)
{
Console.WriteLine(file);
}
Why Jeninnet.FileQuery?
Most file-search code starts with Directory.GetFiles and grows into a pile of ad-hoc
EndsWith, StartsWith, and Regex checks. That approach is hard to reason about, hard to test,
and repeats the same filesystem work for every filter.
Jeninnet.FileQuery replaces it with a compile-then-execute pipeline:
- One pattern model. GitIgnore, Glob, and Regex rules coexist with documented precedence.
- Deterministic results. The same tree, patterns, and options always produce the same order.
- One pass. Metadata, size/time filters, directory results, and matching happen during the same enumeration.
- Safe by default. Inaccessible entries are skipped; cancellation and progress are built in.
- AOT-ready. No reflection on the query path, verified by a Native AOT smoke host in CI.
Install
dotnet add package Jeninnet.FileQuery
Requires .NET 10 or later.
Quick start
Path results
using Jeninnet.FileQuery;
using Jeninnet.FileQuery.Enums;
var query = FileQuery.From(repositoryRoot)
.UsingGlob()
.Where(PatternKind.Glob, ["**/*.cs"])
.Build();
foreach (var path in FileQueryRuntime.Create().Execute(query))
{
Console.WriteLine(path);
}
Or use the builder's terminal shortcuts:
var paths = FileQuery.From(repositoryRoot)
.UsingGlob()
.Where(PatternKind.Glob, ["**/*.cs"])
.Execute();
Metadata results
ExecuteEntries() returns FileQueryEntry values populated from the same enumeration — no extra
FileInfo calls:
var entries = FileQuery.From(repositoryRoot)
.UsingGlob()
.Where(PatternKind.Glob, ["**/*.log"])
.MinSize(1024)
.ModifiedAfter(DateTimeOffset.UtcNow.AddDays(-7))
.ExecuteEntries();
foreach (var entry in entries)
{
Console.WriteLine($"{entry.RelativePath} {entry.Length} bytes {entry.LastWriteTimeUtc:O}");
}
FileQueryEntry exposes FullPath, RelativePath, Length, CreationTimeUtc,
LastWriteTimeUtc, Attributes, IsDirectory, and RootPath.
Async streaming and cancellation
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var progress = new Progress<FileQueryProgress>(p =>
Console.WriteLine($"{p.EntriesScanned} scanned, {p.FilesMatched} matched"));
await foreach (var path in FileQuery.From(root)
.UsingHybrid()
.Where("**", "!**/*.cs")
.ExecuteAsync(progress, cts.Token))
{
Console.WriteLine(path);
}
Synchronous Execute/ExecuteEntries overloads accept the same cancellation and progress
arguments.
Pattern dialects
| Dialect | Syntax | Example |
|---|---|---|
| GitIgnore | Negation, anchoring, directory-only rules, last-match-wins | !src/**/*.cs, bin/ |
| Glob | *, **, ?, character classes, POSIX classes, braces |
**/*.{cs,vb}, file[[:digit:]].txt |
| Regex | r: prefix, full normalized relative path |
r:^src/.*\.cs$ |
| Hybrid | Automatic classification per pattern | .UsingHybrid() |
Precedence is GitIgnore → Glob → Regex. A GitIgnore inclusion is final; Glob and Regex can re-include paths excluded by GitIgnore but cannot exclude a GitIgnore inclusion.
var query = FileQuery.From(root)
.UsingHybrid()
.Where(
"**", // exclude everything
"!**/*.cs", // re-include C# files
"r:.*\\.(png|jpg)$") // regex re-include for images
.IgnoreCase()
.Build();
Invalid patterns fail during compilation with a PatternException that carries the reason and,
when known, Position and Segment.
Results and filters
var query = FileQuery.From(root)
.UsingGlob()
.Where(PatternKind.Glob, ["**/*"])
.IncludeDirectories() // yield matching directories too
.MinSize(1) // inclusive
.MaxSize(10 * 1024 * 1024) // inclusive
.ModifiedAfter(cutoff) // exclusive
.ModifiedBefore(DateTimeOffset.UtcNow) // exclusive
.AttributesToSkip(FileAttributes.System)
.Build();
Filters run before matching and reuse the metadata already reported by the OS enumeration.
.gitignore ingestion
var query = FileQuery.From(repositoryRoot)
.UseGitIgnoreFiles()
.Build();
This loads, with Git-compatible scoping and negation:
- the root
.gitignore; - nested
.gitignorefiles, parent before child; .git/info/excludewhen the root is inside a Git working tree;- an optional global excludes file via
GitIgnoreOptions.GlobalExcludesFile.
No Git executable is required. The CLI exposes the same behavior with --ignore-files.
Incremental scans
Restrict a query to paths reported by a diff, watcher, or external index:
var query = FileQuery.From(root)
.UsingGitIgnore()
.RestrictToPaths(changedPaths)
.Build();
Paths use forward slashes and are relative to the query root. The engine skips unrelated files and prunes directories that cannot contain a listed path.
Single-path matching without traversal
For linters, IDE actions, and path classifiers:
var patternSet = FileQueryPatternSet.Compile(
new PatternInput(
TypedPatterns: new Dictionary<PatternKind, IEnumerable<string>>
{
[PatternKind.GitIgnore] = ["**", "!*.cs", "!bin/"]
},
InterpretationMode: PatternInterpretationMode.Specific),
PatternMatchingMode.GitIgnore);
bool match = patternSet.IsMatch("src/Program.cs");
var explanation = patternSet.Explain("src/Program.cs");
Console.WriteLine(explanation.Outcome); // Include
Console.WriteLine(explanation.Reason); // Include by GitIgnore pattern.
IsMatch(ReadOnlySpan<char>) performs no allocation on the matching path.
Multiple roots
var batch = FileQueryBatch.From(
FileQuery.From(firstRoot).UsingGlob().Where(PatternKind.Glob, ["**/*.cs"]),
FileQuery.From(secondRoot).UsingGlob().Where(PatternKind.Glob, ["**/*.cs"]));
foreach (var entry in batch.ExecuteEntries())
{
Console.WriteLine($"{entry.RootPath}: {entry.RelativePath}");
}
Results are emitted in root order, and RootPath disambiguates identical relative paths.
Telemetry and diagnostics
- Progress:
IProgress<FileQueryProgress>on sync and async execution. - Match audit:
WithDiagnostics(IProgress<FileQueryDiagnostic>)reports the deciding pattern. - OpenTelemetry-ready:
ActivitySourceandMeterinstrumentation under theJeninnet.FileQueryname. No OpenTelemetry package is required; attach your own exporter.
var query = FileQuery.From(root)
.UsingGlob()
.Where(PatternKind.Glob, ["**/*.cs"])
.WithDiagnostics(new Progress<FileQueryDiagnostic>(d =>
Console.WriteLine($"{d.RelativePath}: {d.Outcome} ({d.Reason})")))
.Build();
Architecture at a glance
FileQueryBuilder
→ pattern classification
→ structural validation
→ immutable compiled pattern set
→ traversal plan
→ single-pass enumeration
→ metadata filters
→ compiled matcher
→ diagnostics / progress
→ path or FileQueryEntry result
- Builder: mutable configuration;
Build()validates and produces an immutableFileQuery. - Pattern pipeline: classification → lexical/structural/semantic invariants → compiled instruction sets.
- Traversal: DFS or BFS, depth limits, symlink policies (
Ignore,Follow,FollowWithCycleDetection), error recovery (Skip,Retry,Abort). - IO boundary:
IFileSystemkeepsSystem.IOout of the engine and enables virtual/mock filesystems. The separateJeninnet.FileQuery.FileProviderspackage adaptsIFileProvider.
See the architecture overview for the full design.
API at a glance
| Surface | Purpose |
|---|---|
FileQuery.From(root) |
Start a query with the physical filesystem |
FileQueryBuilder.Where(...) |
Add untyped, typed, or delimited patterns |
UsingHybrid/UsingGitIgnore/UsingGlob/UsingRegex |
Select interpretation and matching mode |
IgnoreCase / IgnoreInaccessible |
Case and inaccessible-entry policy |
WithRecursion / WithMaxDepth / WithTraversal |
Depth limit, DFS/BFS strategy, symlink policy |
MinSize / MaxSize / ModifiedAfter / ModifiedBefore / AttributesToSkip |
Metadata filters |
UseGitIgnoreFiles |
Load Git ignore files |
RestrictToPaths |
Diff-aware allow-list |
IncludeDirectories |
Yield directories from the same walk |
WithDiagnostics / WithErrorRecovery |
Diagnostics and IO recovery |
Build |
Produce an immutable FileQuery |
Execute / ExecuteAsync |
Path results |
ExecuteEntries / ExecuteEntriesAsync |
FileQueryEntry metadata results |
FileQueryBatch |
Multiple roots as one ordered stream |
FileQueryPatternSet |
In-memory IsMatch / Explain |
FileQueryRuntime.Create() |
Compose the default engine without DI |
Package family
| Package | Use it for |
|---|---|
| Jeninnet.FileQuery | Core engine |
Jeninnet.FileQuery.CommandLine |
System.CommandLine pattern options |
Jeninnet.FileQuery.DependencyInjection |
AddFileQuery() composition |
Jeninnet.FileQuery.FileProviders |
Query ASP.NET Core / in-memory IFileProvider sources |
Jeninnet.FileQuery.Tooling |
Pattern inspection without execution |
Jeninnet.FileQuery.Analyzers |
Design-time JNQ1001 diagnostics and code fix |
Jeninnet.FileQuery.Build |
MSBuild validation and SARIF export |
Jeninnet.FileQuery.Tool |
dotnet-filequery global tool |
Test projects use the standalone
Jeninnet.Assertions package.
Documentation
- Quick start
- Pattern language
- Entry metadata and filters
- Git ignore files
- Directory results
- Observability and diagnostics
- Native AOT
License
MIT. See LICENSE.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
NuGet packages (4)
Showing the top 4 NuGet packages that depend on Jeninnet.FileQuery:
| Package | Downloads |
|---|---|
|
Jeninnet.FileQuery.CommandLine
CLI tool for high-performance file system querying. |
|
|
Jeninnet.FileQuery.DependencyInjection
Dependency Injection integration for Jeninnet.FileQuery |
|
|
Jeninnet.FileQuery.FileProviders
Query Microsoft.Extensions.FileProviders sources with Jeninnet.FileQuery: physical, embedded, and in-memory providers share the same matching, filtering, and metadata pipeline. |
|
|
Jeninnet.FileQuery.Tooling
Build-tooling SDK for Jeninnet.FileQuery: classify, validate, and tokenize patterns without executing a query. |
GitHub repositories
This package is not used by any popular GitHub repositories.
See CHANGELOG.md and Migration.md at https://github.com/TarekNajem04/Jeninnet.FileQuery