Quick File Search (QFS)

High-performance file search for Windows with NTFS Master File Table (MFT) acceleration — same core technique used by "Everything" search.

Features

• ⚡ Lightning fast: NTFS MFT/USN enumeration via FSCTL_ENUM_USN_DATA — single sequential scan instead of recursive syscalls
• 🔄 Automatic fallback: Recursive directory walk with thread pool when MFT unavailable (non-NTFS, no admin, network drives)
• 🔍 Flexible patterns: Simple case-insensitive substrings or full ECMAScript regex (/pattern/)
• 🧮 Logical operators: && (AND), || (OR), single pattern
• 🧵 Multithreaded: Configurable thread pool (--threads)
• 💾 Multiple modes: Drive-wide (--drive C) or directory-scoped (--dir path)
• 📊 Output formats: Colored text, JSON, CSV
• 🛑 Limits: --max-results, --timeout
• 🚫 Exclusions: --exclude patterns (repeatable)
• 💬 Interactive mode: Run without arguments for guided setup

Quick Start

# Build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# Search
./build/Release/qfs.exe "report"                    # simple substring
./build/Release/qfs.exe "test&&.exe"                # AND (both patterns)
./build/Release/qfs.exe "hello||world"              # OR (either pattern)
./build/Release/qfs.exe "/.*\.(txt|md)/"            # regex
./build/Release/qfs.exe "config" --dir C:\Projects  # specific directory
./build/Release/qfs.exe "secret" --drive C          # entire drive (needs admin)

Building

Prerequisites

• Windows 10/11
• Visual Studio 2022 (MSVC v143+) with C++20 support
• CMake 3.20+

CMake (recommended)

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Executable: build/Release/qfs.exe

Visual Studio

Open the solution folder in Visual Studio 2022 — CMake integration is built-in.

vcpkg (optional)

vcpkg install gtest
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

Usage

qfs <pattern> [options]

Pattern Syntax

Type	Syntax	Example	Matches
Simple substring	text	document	document.pdf, my_document.txt
Simple AND	a&&b	hello&&.txt	hello.txt, hello_world.txt
Simple OR	a||b	hello||world	hello.txt, world.pdf
Regex single	/regex/	/.*\.txt$/	file.txt, data.txt
Regex AND	/a.*&&b.*/	/test.*&&.*\.exe/	test_app.exe, test123.exe
Regex OR	/a.*||b.*/	/.*\.txt||.*\.md/	readme.txt, notes.md

Regex escaping: Use \. for literal dot, \\ for backslash. In cmd/PowerShell, double-escape: /.*\\.txt/

Options

Option	Description	Default
--threads <N>	Thread count (1 to CPU cores)	All cores
--dir <path>	Starting directory	Current directory
--drive <letter>	Search entire drive via MFT (e.g., C)	—
--save <file>	Save results to file	—
--noverbose	Suppress live output	Verbose
--searchdir	Include directory names	Files only
--no-mft	Disable MFT scan, use recursive walk	MFT first
--max-results <N>	Stop after N matches	Unlimited
--timeout <seconds>	Stop after N seconds	No limit
--exclude <pattern>	Exclude paths matching pattern (repeatable)	None
--format <text|json|csv>	Output format	Text
--help	Show help	—

Examples

# Basic searches
qfs "report"                                    # case-insensitive substring
qfs "test&&.exe"                                # AND: contains "test" AND ends with ".exe"
qfs "hello||world"                              # OR: contains "hello" OR "world"
qfs "/test[0-9]+\.exe/"                         # regex: test1.exe, test42.exe, etc.

# Directory-scoped
qfs "config" --dir C:\Projects --threads 4
qfs "/.*\.(cpp|hpp)/" --dir . --searchdir       # include directories

# Drive-wide (requires Administrator + NTFS)
qfs "secret" --drive C
qfs "log" --drive D --max-results 100 --timeout 30

# Output formats
qfs "error" --format json --save errors.json
qfs "data" --format csv --save results.csv

# Exclusions
qfs "temp" --exclude "*/node_modules/*" --exclude "*/.git/*"
qfs "build" --exclude "*/build/*" --exclude "*/out/*" --no-mft

# Combined
qfs "config&&.json" --dir C:\Projects --threads 8 --format json --save configs.json --max-results 50

How It Works

MFT/USN Scan (Fast Path)

1. Opens volume with CreateFileW("\\\\.\\C:", GENERIC_READ, ...)
2. Verifies NTFS via GetVolumeInformationW
3. Enumerates USN records via DeviceIoControl(FSCTL_ENUM_USN_DATA) in 1 MB chunks
4. Builds in-memory FRN → (name, parent FRN, isDirectory) map
5. Reconstructs full paths via parent-chain traversal with memoization
6. Matches patterns against filenames only (not full paths)

Recursive Walk (Fallback)

• Uses FindFirstFileW/FindNextFileW with thread pool
• Parallelizes subdirectory traversal
• Activated automatically when MFT fails or --no-mft specified

Requirements

Feature	Requirement
MFT scan	NTFS volume + Administrator privileges
Fallback	Any filesystem (FAT32, exFAT, ReFS, network shares)

Performance Notes

• MFT scan: ~10-100x faster than recursive walk on large volumes (millions of files)
• Memory: ~50-200 MB for typical MFT (1M+ records)
• Thread scaling: Near-linear up to physical cores; diminishing returns beyond

Testing

cmake -B build
cmake --build build --config Release
ctest --test-dir build --output-on-failure -C Release

CI/CD

GitHub Actions workflow (.github/workflows/ci.yml):

• ✅ Windows build (Debug/Release × x64)
• ✅ Unit tests
• ✅ Clang-Tidy static analysis
• ✅ Automated releases on version tags (v*)

License

MIT License — see LICENSE for details.

Third-party

• rang — header-only terminal colors (MIT)
• GoogleTest — unit tests (BSD-3-Clause), fetched via CMake FetchContent

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run clang-format and clang-tidy
5. Submit a PR