vm2.Glob.Api 2.0.0

vm2.Glob — Cross-Platform Glob Pattern Matching for .NET

• Overview
  • Features
• Prerequisites
• Install the Package (NuGet)
• Quick Start
• Glob Pattern Syntax
• Get the Code
• Build from the Source Code
• Tests
• Benchmark Tests
• Usage
  • Basic Enumeration
  • Using the Fluent Builder
  • Dependency Injection
  • Advanced Configuration
  • File System Access Control
    • Include Hidden and System Files
    • Skip Only Specific Attributes
    • Handle Access-Denied Scenarios
    • Include Special Directory Entries
• Configuration Options
  • Object Type Selection
  • Case Sensitivity
  • Traversal Order
  • Deduplication
• Real-World Examples
  • Find Source Files, Excluding Build Output
  • Find Test Assemblies
  • Clean Up Old Log Files
  • Load Configuration Files
• Testing with IFileSystem
• Performance
  • Best Practices
  • Memory Usage
  • Benchmarks
• API Reference
  • GlobEnumerator Class
    • Constructor
    • Properties
    • Methods
  • GlobEnumeratorBuilder Class
  • Extension Methods (Dependency Injection)
• Feature Requests & Roadmap
  • Pattern Extensions
  • Tool Enhancements
• Related Packages
• License
• Version History

Overview

Glob patterns provide a concise, human-readable syntax for matching file and directory paths — the same wildcard notation used by Unix shells, .gitignore files, and build systems. This repository provides two .NET packages for working with glob patterns:

• vm2.Glob.Api — A high-performance library for embedding glob-based file enumeration in .NET applications.
• vm2.GlobTool — A cross-platform command-line tool for finding files and directories from the terminal.

Both implement the POSIX.2 glob specification with extensions for Windows and Unix-like systems, including environment variable expansion and platform-aware case sensitivity.

Features

• ✅ POSIX.2 glob specification compliant with Windows extensions
• ✅ Cross-platform — identical behavior on Windows, Linux, and macOS
• ✅ Environment variables — automatic expansion of $HOME, %USERPROFILE%, and ~
• ✅ Flexible API — fluent builder pattern for easy configuration
• ✅ High performance — optimized enumeration with minimal allocations
• ✅ Lazy evaluation — IEnumerable-based streaming of results
• ✅ Testable — IFileSystem abstraction for unit testing without touching the disk
• ✅ Multiple traversal modes — depth-first or breadth-first
• ✅ Deduplication — optional removal of duplicate results from multi-globstar patterns

Prerequisites

• .NET 10.0 or later

Install the Package (NuGet)

• Using the dotnet CLI:

  dotnet add package vm2.Glob.Api
  

• From Visual Studio Package Manager Console:

  Install-Package vm2.Glob.Api
  

For the companion command-line tool, see vm2.GlobTool.

Quick Start

using vm2.Glob.Api;

var enumerator = new GlobEnumerator
{
    Glob          = "**/*.cs",
    FromDirectory = "./src",
};

foreach (var path in enumerator.Enumerate())
    Console.WriteLine(path);

Glob Pattern Syntax

Get the Code

Clone the GitHub repository. The library source is in the src/Glob.Api directory.

git clone https://github.com/vmelamed/vm2.Glob.git
cd vm2.Glob

Build from the Source Code

• Command line:

  dotnet build
  

• Visual Studio / VS Code:

  • Open the solution and choose Build Solution (or Rebuild as needed).

Tests

The test projects are in the test directory. They use MTP (Microsoft Testing Platform) with xUnit. Tests are buildable and runnable from the command line and from Visual Studio Code across operating systems.

• Command line:

  dotnet test
  

• The tests can also be run standalone after building:

  dotnet build
  test/Glob.Api.Tests/bin/Debug/net10.0/Glob.Api.Tests
  

Benchmark Tests

The benchmark project is in the benchmarks/Glob.Api.Benchmarks directory. It uses BenchmarkDotNet.

• Command line:

  dotnet run --project benchmarks/Glob.Api.Benchmarks/Glob.Api.Benchmarks.csproj -c Release
  

• Standalone after building:

  dotnet build -c Release benchmarks/Glob.Api.Benchmarks/Glob.Api.Benchmarks.csproj
  benchmarks/Glob.Api.Benchmarks/bin/Release/net10.0/Glob.Api.Benchmarks
  

Usage

Basic Enumeration

Create a GlobEnumerator, set the pattern and starting directory, then call Enumerate():

var enumerator = new GlobEnumerator
{
    Glob          = "**/*.cs",
    FromDirectory = "./src",
};

foreach (var file in enumerator.Enumerate())
    Console.WriteLine(file);

Using the Fluent Builder

The GlobEnumeratorBuilder provides a fluent API for configuring and creating an enumerator in a single expression:

var results = new GlobEnumeratorBuilder()
                    .WithGlob("**/*Tests.cs")
                    .FromDirectory("./test")
                    .SelectFiles()
                    .CaseSensitive()
                    .Build()
                    .Configure(new GlobEnumerator())
                    .Enumerate()
                    .ToList();

Or use Create() to get a pre-configured enumerator directly:

var enumerator = new GlobEnumeratorBuilder()
                        .WithGlob("**/*.cs")
                        .FromDirectory("./src")
                        .SelectFiles()
                        .Build()
                        .Create();

foreach (var file in enumerator.Enumerate())
    Console.WriteLine(file);

Dependency Injection

Register GlobEnumerator with your application's DI container using the provided extension methods:

// In Startup.cs or Program.cs — register with default FileSystem
services.AddGlobEnumerator();

// In your service — resolve a configured enumerator
public class FileService(IServiceProvider sp)
{
    public IEnumerable<string> FindFiles(string pattern)
        => sp.GetGlobEnumerator(b => b.WithGlob(pattern).SelectFiles())
             .Enumerate();
}

Advanced Configuration

The builder exposes the full range of enumerator options:

var enumerator = new GlobEnumeratorBuilder()
                        .WithGlob("**/docs/**/*.md")
                        .FromDirectory("/usr/share")
                        .SelectFiles()
                        .CaseInsensitive()
                        .DepthFirst()
                        .Distinct()                   // remove duplicates from multi-globstar patterns
                        .Build()
                        .Configure(new GlobEnumerator());

foreach (var file in enumerator.Enumerate())
    ProcessFile(file);

File System Access Control

Include Hidden and System Files

By default, the enumerator skips hidden and system files. On Unix-like systems this also excludes dotfiles (e.g., .gitignore). Set AttributesToSkip to None to include everything:

var enumerator = new GlobEnumerator
{
    Glob             = "**/*",
    FromDirectory    = "./src",
    AttributesToSkip = FileAttributes.None,   // include all files
};

Skip Only Specific Attributes

// Skip only temporary files
enumerator.AttributesToSkip = FileAttributes.Temporary;

// Skip multiple attributes
enumerator.AttributesToSkip = FileAttributes.Hidden
                            | FileAttributes.System
                            | FileAttributes.Temporary;

Handle Access-Denied Scenarios

// Throw on inaccessible files (strict mode)
enumerator.IgnoreInaccessible = false;

try
{
    foreach (var file in enumerator.Enumerate())
        ProcessFile(file);
}
catch (UnauthorizedAccessException ex)
{
    Console.WriteLine($"Access denied: {ex.Message}");
}

// Skip inaccessible files silently (default, permissive mode)
enumerator.IgnoreInaccessible = true;

Include Special Directory Entries

var enumerator = new GlobEnumerator
{
    Glob                     = "*",
    FromDirectory            = "./src",
    Enumerated               = Objects.Directories,
    ReturnSpecialDirectories = true,   // include "." and ".."
};

Note: ReturnSpecialDirectories is rarely needed and defaults to false for cleaner results.

Configuration Options

Object Type Selection

enumerator.Enumerated = Objects.Files;                // files only (default)
enumerator.Enumerated = Objects.Directories;          // directories only
enumerator.Enumerated = Objects.FilesAndDirectories;  // both

Case Sensitivity

enumerator.MatchCasing = MatchCasing.PlatformDefault;  // insensitive on Windows, sensitive on Unix (default)
enumerator.MatchCasing = MatchCasing.CaseSensitive;    // always case-sensitive
enumerator.MatchCasing = MatchCasing.CaseInsensitive;  // always case-insensitive

Traversal Order

enumerator.DepthFirst = false;  // breadth-first (default) — process siblings before children
enumerator.DepthFirst = true;   // depth-first — fully explore each subtree before moving on

Deduplication

enumerator.Distinct = false;    // allow duplicates (default, faster)
enumerator.Distinct = true;     // remove duplicates (uses a HashSet internally)

Note: Deduplication is only necessary for patterns with multiple globstars (e.g., **/docs/**/*.md) that may enumerate the same path more than once.

Real-World Examples

Find Source Files, Excluding Build Output

public IEnumerable<string> GetSourceFiles(string projectPath)
{
    var enumerator = new GlobEnumeratorBuilder()
                            .WithGlob("**/*.cs")
                            .FromDirectory(projectPath)
                            .SelectFiles()
                            .Build()
                            .Configure(new GlobEnumerator());

    return enumerator.Enumerate()
                     .Where(f => !f.Contains("/obj/") && !f.Contains("/bin/"));
}

Find Test Assemblies

public IEnumerable<string> FindTestAssemblies(string artifactsPath)
{
    var enumerator = new GlobEnumerator
    {
        Glob          = "**/*Tests.dll",
        FromDirectory = artifactsPath,
        Enumerated    = Objects.Files,
    };

    return enumerator.Enumerate();
}

Clean Up Old Log Files

public void CleanupLogs(string logDirectory, int daysOld)
{
    var cutoff = DateTime.Now.AddDays(-daysOld);

    var enumerator = new GlobEnumerator
    {
        Glob          = "**/*.log",
        FromDirectory = logDirectory,
    };

    foreach (var logFile in enumerator.Enumerate())
    {
        if (File.GetLastWriteTime(logFile) < cutoff)
            File.Delete(logFile);
    }
}

Load Configuration Files

public Dictionary<string, string> LoadConfigurations(string configPath)
{
    var enumerator = new GlobEnumeratorBuilder()
                            .WithGlob("**/appsettings*.json")
                            .FromDirectory(configPath)
                            .SelectFiles()
                            .CaseInsensitive()
                            .Build()
                            .Configure(new GlobEnumerator());

    return enumerator.Enumerate()
        .ToDictionary(
            f => Path.GetFileName(f),
            f => File.ReadAllText(f)
        );
}

Testing with IFileSystem

The library provides an IFileSystem abstraction so that code depending on GlobEnumerator can be tested without touching the file system. The repository includes a ready-made FakeFileSystem in the test/Glob.Api.FakeFileSystem project, but you can also supply your own implementation:

public class InMemoryFileSystem : IFileSystem
{
    // Implement: IsWindows, GetFullPath, GetCurrentDirectory,
    //            DirectoryExists, FileExists,
    //            EnumerateDirectories, EnumerateFiles
}

// Pass the custom file system to the enumerator
var enumerator = new GlobEnumerator(new InMemoryFileSystem())
{
    Glob          = "**/*.cs",
    FromDirectory = "/src",
};

var results = enumerator.Enumerate().ToList();

Performance

Best Practices

1. Be specific with patterns — src/**/*.cs is faster than **/*.cs because the search starts deeper in the tree.
2. Use the appropriate object type — Objects.Files avoids directory-enumeration overhead when you only need files.
3. Minimize globstars — each ** increases traversal depth; avoid patterns like **/a/**/b when a/**/b suffices.
4. Enable deduplication only when needed — the internal HashSet has a memory cost proportional to the result count.
5. Choose the right traversal order — breadth-first works well for wide, shallow trees where matches are near the top; depth-first is better for deep hierarchies.

Memory Usage

• Lazy enumeration — results are streamed via IEnumerable, not materialized into a list.
• Minimal allocations — uses Span<T> and stackalloc internally for pattern parsing and transformation.
• Deduplication cost — when Distinct is enabled, a HashSet<string> tracks every returned path.

Benchmarks

Typical performance on GitHub Actions Ubuntu Runner, e.g.

BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
Intel Xeon Platinum 8370C CPU 2.80GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.103
  [Host]     : .NET 10.0.3 (10.0.3, 10.0.326.7603), X64 RyuJIT x86-64-v4
  DefaultJob : .NET 10.0.3 (10.0.3, 10.0.326.7603), X64 RyuJIT x86-64-v4

Legends:

• Pattern : Value of the 'Pattern' parameter
• Mean : Arithmetic mean of all measurements
• Error : Half of 99.9% confidence interval
• StdDev : Standard deviation of all measurements
• Ratio : Mean of the ratio distribution ([Current]/[Baseline])
• RatioSD : Standard deviation of the ratio distribution ([Current]/[Baseline])
• Gen0 : GC Generation 0 collects per 1000 operations
• Allocated : Allocated memory per single operation (managed only, inclusive, 1KB = 1024B)
• Alloc Ratio : Allocated memory ratio distribution ([Current]/[Baseline])
• 1 us : 1 Microsecond (0.000001 sec)

API Reference

GlobEnumerator Class

Constructor

GlobEnumerator(IFileSystem? fileSystem = null, ILogger<GlobEnumerator>? logger = null)

Both parameters are optional. When fileSystem is null, the enumerator uses the real file system.

Properties

Methods

GlobEnumeratorBuilder Class

All builder methods return the builder instance for method chaining.

Extension Methods (Dependency Injection)

// Register GlobEnumerator with default FileSystem
services.AddGlobEnumerator();

// Register with a builder configuration
services.AddGlobEnumerator(b => b.SelectFiles().CaseSensitive());

// Resolve a configured enumerator from the service provider
var enumerator = serviceProvider.GetGlobEnumerator(
    b => b.WithGlob("**/*.cs").FromDirectory("./src"));

Feature Requests & Roadmap

Have a feature you'd like to see? Open an issue or upvote an existing request. The Votes column reflects community interest and helps prioritize development.

Pattern Extensions

Tool Enhancements

Related Packages

• vm2.GlobTool — Cross-platform command-line tool for glob pattern matching
• POSIX.2 Glob Specification — The Linux man-pages project
• Glob (programming) — Wikipedia

License

MIT — See LICENSE

Version History

See CHANGELOG.md for version history and release notes.