README.md

vm2.GlobTool — Cross-Platform Glob Pattern Matching Tool

• Installation
• Quick Start
• What Are Glob Patterns?
• Command Line Options
• Glob Pattern Syntax
• Examples
  • Basic Usage
  • Directory-Specific Searches
  • Object Type Selection
  • Case Sensitivity
  • Advanced Patterns
  • Deduplication
  • Including Hidden Files
• Output Format
• Environment Variable Support
  • Windows
  • Unix, Linux, macOS
• Real-World Use Cases
  • Development Workflows
  • CI/CD Integration
    • GitHub Actions
    • Azure Pipelines
  • Code Analysis
  • Project Maintenance
• Performance Tips
• Comparison with Alternatives
• Troubleshooting
  • Pattern Not Matching
  • Permission Errors
  • No Results
• Related Packages
• License

A fast, cross-platform CLI tool for finding files and directories using glob patterns. Built on the vm2.Glob.Api library, it brings the familiar wildcard syntax of Unix shells to every operating system — with environment variable expansion, configurable case sensitivity, and clean, pipe-friendly output.

Installation

dotnet tool install -g vm2.GlobTool

Quick Start

# Find all C# files recursively
glob "**/*.cs"

# Find files in a specific directory
glob "**/*.txt" -d ~/documents

# Find only directories
glob "**" -o directories

# Case-sensitive search
glob "[A-Z]*.cs" -c sensitive

# Remove duplicates from multi-globstar patterns
glob "**/docs/**/*.md" -x

What Are Glob Patterns?

Glob patterns are a concise wildcard notation for matching file and directory paths. They originated in early Unix shells and are the same syntax used by .gitignore, build tools, and many editors. The glob tool lets you use these patterns directly from the command line, on any operating system.

Command Line Options

glob <pattern> [options]

Arguments:
  glob                   Glob pattern (e.g., '**/*.txt')

Options:
  -d, --start-from       Start directory (default: current directory)
  -o, --search-objects   What to find: files|f, directories|d, both|b (default: both)
  -c, --case             Case sensitivity: sensitive|s, insensitive|i, platform|p (default: platform)
  -x, --distinct         Remove duplicate results (default: false)
  -a, --show-hidden      Include hidden/system files (default: false)
  --help                 Show help and usage information
  --version              Show version information

Glob Pattern Syntax

Pattern	Meaning
*	Any sequence of characters (except path separator)
?	Any single character
[abc]	Any character in set (a, b, or c)
[a-z]	Any character in range
[!abc]	Any character NOT in set
**	Zero or more directory levels (globstar)
[:alpha:]	Named character class

Examples

Basic Usage

# Find all C# files
glob "**/*.cs"

# Find test files
glob "**/*Tests.cs"

# Find JSON config files in the current directory
glob "*.json"

Directory-Specific Searches

# Search in a specific directory
glob "**/*.txt" -d ~/documents

# Search from home directory
glob "**/*.log" -d ~

# Search with an absolute path
glob "**/*.md" -d /usr/share/doc

Object Type Selection

# Find only files
glob "**/*.dll" -o files

# Find only directories
glob "**" -o directories

# Find both (default)
glob "src/**" -o both

Case Sensitivity

# Case-sensitive (exact match required)
glob "[A-Z]*.cs" -c sensitive

# Case-insensitive (README.md matches readme.md)
glob "readme.md" -c insensitive

# Platform default (insensitive on Windows, sensitive on Unix)
glob "*.TXT" -c platform

Advanced Patterns

# Character classes
glob "**/*[0-9].log"           # Files ending with a digit
glob "**/[a-z]*.cs"            # Files starting with a lowercase letter

# Named character classes
glob "**/*[[:digit:]].txt"     # Files ending with a digit
glob "**/*[[:alpha:]]*.cs"     # Files containing a letter

# Negation in character classes
glob "**/[!.]*.json"           # JSON files whose name does not start with a dot

# Environment variables (expanded before matching)
glob "$HOME/documents/**/*.pdf"              # Unix
glob "%USERPROFILE%\documents\**\*.pdf"      # Windows
glob "~/documents/**/*.pdf"                  # ~ expands to $HOME on Unix

Deduplication

Patterns with multiple ** segments (e.g., **/docs/**/*.md) can enumerate the same path more than once. Use -x to deduplicate:

# Without --distinct (may show duplicates)
glob "**/docs/**/*.md"

# With --distinct (removes duplicates)
glob "**/docs/**/*.md" -x

Including Hidden Files

By default, hidden and system files are excluded. Use -a to include them:

# Exclude hidden/system files (default)
glob "**/*"

# Include hidden/system files (e.g., .gitignore, .env)
glob "**/*" -a

Output Format

Each matched path is printed on a separate line as an absolute path. Directory paths end with the platform's directory separator (/ on Unix, \ on Windows). The output contains no extra formatting or colors, making it ideal for piping into other tools.

Example output:

/home/user/projects/MyApp/src/Program.cs
/home/user/projects/MyApp/src/Models/User.cs
/home/user/projects/MyApp/test/ProgramTests.cs

Environment Variable Support

The tool expands environment variables in the pattern before matching:

Windows

glob "%APPDATA%\**\*.json"
glob "%USERPROFILE%\Documents\**\*.txt"

Unix, Linux, macOS

glob "$HOME/documents/**/*.pdf"
glob "~/projects/**/*.cs"        # ~ expands to $HOME
glob "$XDG_CONFIG_HOME/**/*.conf"

Real-World Use Cases

Development Workflows

# Find all unit test files
glob "**/test/**/*Tests.cs"

# Find configuration files
glob "**/appsettings*.json"

# Find source files in a specific subtree
glob "src/**/*.cs"

CI/CD Integration

GitHub Actions

- name: Find test assemblies
  run: |
    TEST_DLLS=$(glob "**/*Tests.dll" -d ./artifacts/bin)
    dotnet test $TEST_DLLS

Azure Pipelines

- script: |
    FILES=$(glob "**/*.csproj")
    echo "##vso[task.setvariable variable=ProjectFiles]$FILES"

Code Analysis

# Find public interfaces
glob "src/**/I*.cs" | xargs grep "public interface"

# Find deprecated code
glob "**/*.cs" | xargs grep -l "Obsolete"

# Count lines of code
glob "src/**/*.cs" | xargs wc -l

Project Maintenance

# Find package references
glob "**/*.csproj" | xargs grep PackageReference

# Find large files
glob "**/*" | xargs du -h | sort -rh | head -20

# Find old log files
glob "**/*.log" -d /var/log

Performance Tips

1. Be specific — src/**/*.cs is faster than **/*.cs.
2. Select the right object type — use -o files when you only need files.
3. Minimize globstars — docs/**/*.md is faster than **/docs/**/*.md.
4. Use -x only when needed — deduplication has a memory cost proportional to result count.

Comparison with Alternatives

Feature	glob	find (Unix)	Get-ChildItem (PS)	fd
Cross-platform	✅	❌	❌	✅
Glob syntax	✅ Native	❌ Regex	❌ Complex	✅
.NET integration	✅	❌	⚠️	❌
Install	dotnet tool	Pre-installed	Pre-installed	Cargo
Environment vars	✅	❌	✅	❌

Troubleshooting

Pattern Not Matching

Always quote the pattern to prevent the shell from expanding wildcards before the tool sees them:

glob "**/*.cs"     # ✅ Correct — shell passes the literal pattern
glob **/*.cs       # ❌ Wrong — shell expands before the tool runs

Permission Errors

# Use elevated permissions (Windows)
glob "C:\Windows\System32\**\*.dll" -a

# Use sudo (Unix)
sudo glob "/root/**/*"

No Results

# Verify the start directory exists
glob "**/*.cs" -d ~/nonexistent  # Error if path does not exist

# Check case sensitivity
glob "README.md" -c sensitive    # Won't match readme.md
glob "README.md" -c insensitive  # Matches readme.md

Related Packages

• vm2.Glob.Api — Glob pattern matching library for .NET applications
• POSIX.2 Glob Specification — The underlying specification

License

MIT — See LICENSE