Path globbing for strings, arrays, and filesystem traversal.

Supported pattern features:

• * : zero or more characters (within one path segment)
• ? : exactly one character (within one path segment)
• [abc], [a-z], [!abc] : character classes
• ** : zero or more path segments (globstar, segment-only)
• \\ escapes metacharacters for literal matching

The engine is pure Luau and shared by both array matching and filesystem traversal helpers.

Summary

Classes

Functions

API Reference

Classes

Compiled

A compiled glob pattern that can be reused for repeated matching.

Properties

pattern: string

The original pattern string used for compilation.

Compiled:match

Match a candidate path against this compiled pattern.

Compiled:match(path: string) → boolean

Functions

glob.escape

Escape glob metacharacters in literal so the result matches literally.

glob.escape(literal: string) → string

Parameters

literal: string

raw text to treat as a literal path fragment

Returns

string

escaped glob pattern

glob.hasMagic

Return whether pattern contains unescaped glob metacharacters.

glob.hasMagic(pattern: string) → boolean

Parameters

pattern: string

pattern text to inspect

Returns

boolean

true when *, ?, or [ appears unescaped

glob.compile

Compile a glob pattern into a reusable matcher object.

glob.compile(pattern: string, options: MatchOptions?) → Compiled

Parameters

pattern: string

glob pattern to compile

options: MatchOptions?

matching behavior options

Returns

Compiled

frozen compiled matcher with pattern and match

glob.match

Test whether path matches pattern.

glob.match(path: string, pattern: string, options: MatchOptions?) → boolean

Parameters

path: string

candidate path

pattern: string

glob pattern

options: MatchOptions?

matching behavior options

Returns

boolean

true when the path matches

glob.filter

Filter an array of paths, returning only entries that match pattern.

glob.filter(paths: { string }, pattern: string, options: MatchOptions?) → { string }

Parameters

paths: { string }

candidate paths

pattern: string

glob pattern

options: MatchOptions?

matching behavior options

Returns

{ string }

matching paths in original order

glob.gmatch

Create an iterator over entries in paths that match pattern.

glob.gmatch(paths: { string }, pattern: string, options: MatchOptions?) → (() → string?)

Parameters

paths: { string }

candidate paths

pattern: string

glob pattern

options: MatchOptions?

matching behavior options

Returns

(() → string?)

iterator yielding matching paths, then nil

glob.glob

Expand a filesystem glob relative to options.root.

Returned paths are relative to the root and normalized to / separators.

glob.glob(pattern: string, options: GlobOptions?) → { string }

Parameters

pattern: string

glob pattern to evaluate

options: GlobOptions?

traversal and matching options

Returns

{ string }

matched paths

glob.iglob

Create an iterator over filesystem glob results.

glob.iglob(pattern: string, options: GlobOptions?) → (() → string?)

Parameters

pattern: string

glob pattern to evaluate

options: GlobOptions?

traversal and matching options

Returns

(() → string?)

iterator yielding matched paths, then nil

Types

MatchOptions

Options used by string/array-based glob matching.

type MatchOptions = { includeHidden: boolean?, caseSensitive: boolean? }

includeHidden: boolean?

Whether wildcard segments may match names beginning with .. Defaults to false.

caseSensitive: boolean?

Whether comparisons are case-sensitive. Defaults to true.

GlobOptions

Options used by filesystem glob expansion. Extends MatchOptions with traversal controls.

type GlobOptions = MatchOptions & { root: string?, ignore: string | { string }?, followSymlinks: boolean?, onlyFiles: boolean?, onlyDirectories: boolean? }

Implements: MatchOptions

root: string?

Root directory used for filesystem traversal. Defaults to ".".

ignore: string | { string }?

Ignore pattern(s) evaluated against relative paths. Can be a single pattern or an array of patterns.

followSymlinks: boolean?

Whether directory symlinks should be traversed recursively. Defaults to false.

onlyFiles: boolean?

If true, only files are returned.

onlyDirectories: boolean?

If true, only directories are returned.