fast-glob

Uniform Naming Convention (UNC) paths cannot be used directly as patterns due to syntax restrictions. To use them, you must either provide the UNC path as the cwd (current working directory) option or use the fg.convertPathToPattern method to transform the path into a valid pattern.

Using cwd

Pass the UNC path to the cwd option in your glob function.

Using convertPathToPattern

Convert the UNC path to a pattern before appending your glob syntax.

To use fast-glob in your Node.js project, install it using npm:

npm install fast-glob

When working on Windows, always use forward-slashes (/) in glob expressions and the ignore option. Use backslashes only for escaping characters. For the cwd option, convert Windows paths to a compatible format.

Good Practice:

[
	'directory/*',
	fg.convertPathToPattern(process.cwd()) + '/**'
]

To prevent a directory from being read at all, use a negative pattern like !**/directory_name or !**/directory_name/**, or use the ignore option.

Warning: If you use !**/directory/**/*, the directory is still read, but its entries are excluded from the results. To ensure the directory is not read, use !**/directory or !**/directory/**.

fast-glob supports both basic and advanced glob syntax.

Important: Always use forward-slashes (/) in glob expressions and the ignore option. Use backslashes (\) only for escaping characters.

Basic Syntax

• *: Matches everything except slashes and hidden files.
• **: Matches zero or more directories (globstar).
• ?: Matches any single character except slashes.
• [seq]: Matches any character in the sequence.

Advanced Syntax

• \: Escapes special characters ($^*+?()[]).
• [[:digit:]]: POSIX character classes.
• ?(pattern-list): Extended globs.
• {}: Bash style brace expansions.
• [1-5]: Regexp character classes.
• (a|b): Regex groups.

Adjust how patterns are matched against the file system.

• braceExpansion (boolean): Enables Bash-like brace expansion (e.g., a{b,c}d). Defaults to true.
• caseSensitiveMatch (boolean): Enables case-sensitive matching. Defaults to true.
• dot (boolean): Allow patterns to match entries starting with a period (.). Defaults to false.
• extglob (boolean): Enables Bash-like extglob functionality. Defaults to true.
• globstar (boolean): Enables recursive repetition of **. If false, ** behaves like *. Defaults to true.
• baseNameMatch (boolean): If true, patterns without slashes match against the basename of the path. Defaults to false.

Use the cwd and deep options to control the scope of your search.

• cwd (string): The current working directory in which to search. Defaults to process.cwd().
• deep (number): The maximum depth of a read directory relative to the start directory. Defaults to Infinity.

Note: If you specify a pattern with a base directory, that directory does not participate in the depth calculation (it acts like a cwd).

// With base directory
fg.globSync('dir/**', { onlyFiles: false, deep: 1 }); // ['dir/one']
fg.globSync('dir/**', { onlyFiles: false, deep: 2 }); // ['dir/one', 'dir/one/two']

// With cwd option
fg.globSync('**', { onlyFiles: false, cwd: 'dir', deep: 1 }); // ['one']
fg.globSync('**', { onlyFiles: false, cwd: 'dir', deep: 2 }); // ['one', 'one/two']

Control how symbolic links are handled during traversal and stat calls.

• followSymbolicLinks (boolean): Indicates whether to traverse descendants of symbolic link directories when expanding ** patterns. Defaults to true.
• throwErrorOnBrokenSymbolicLink (boolean): If true, throws an error when a symbolic link is broken. If false, it safely returns the lstat call. Defaults to false.

If the stats option is enabled, information about the symbolic link (fs.lstat) will be replaced with information about the entry (fs.stat) behind it when followSymbolicLinks is true.

Use fg.globSync to return an array of matching entries immediately. This will block the event loop until the operation is complete.

const fg = require('fast-glob');

const entries = fg.globSync(['.editorconfig', '**/index.js'], { dot: true });

// ['.editorconfig', 'services/index.js']

Use fg.glob or fg.async to return a Promise that resolves to an array of matching entries. This is the recommended way for non-blocking file system traversal.

const fg = require('fast-glob');

const entries = await fg.glob(['.editorconfig', '**/index.js'], { dot: true });

// ['.editorconfig', 'services/index.js']