🚀 fast-glob

Is a faster node-glob alternative.

💡 Highlights

🚀 Fast by using Streams and Promises. Used readdir-enhanced and micromatch.
🔰 User-friendly, since it supports multiple and negated patterns (['*', '!*.md']).
🚦 Rational, because it doesn't read excluded directories (!**/node_modules/**).
⚙️ Universal, because it supports Synchronous, Promise and Stream API.
💸 Economy, because it provides fs.Stats for matched path if you wanted.

Donate

If you want to thank me, or promote your Issue.

Sorry, but I have work and support for packages requires some time after work. I will be glad of your support and PR's.

Install

$ npm install --save fast-glob

Usage

Asynchronous

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

fg(['src/**/*.js', '!src/**/*.spec.js']).then((entries) => console.log(entries));
fg.async(['src/**/*.js', '!src/**/*.spec.js']).then((entries) => console.log(entries));

Synchronous

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

const entries = fg.sync(['src/**/*.js', '!src/**/*.spec.js']);
console.log(entries);

Stream

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

const stream = fg.stream(['src/**/*.js', '!src/**/*.spec.js']);

const entries = [];

stream.on('data', (entry) => entries.push(entry));
stream.once('error', console.log);
stream.once('end', () => console.log(entries));

API

fg(patterns, [options])

fg.async(patterns, [options])

Returns a Promise with an array of matching entries.

fg.sync(patterns, [options])

Returns an array of matching entries.

fg.stream(patterns, [options])

Returns a ReadableStream when the data event will be emitted with Entry.

patterns

Type: string|string[]

This package does not respect the order of patterns. First, all the negative patterns are applied, and only then the positive patterns.

options

Type: Object

See options section for more detailed information.

fg.generateTasks(patterns, [options])

Return a set of tasks based on provided patterns. All tasks satisfy the Task interface:

interface Task {
  /**
   * Parent directory for all patterns inside this task.
   */
  base: string;
  /**
   * Dynamic or static patterns are in this task.
   */
  dynamic: boolean;
  /**
   * All patterns.
   */
  patterns: string[];
  /**
   * Only positive patterns.
   */
  positive: string[];
  /**
   * Only negative patterns without ! symbol.
   */
  negative: string[];
}

Entry

The entry which can be a string if the stats option is disabled, otherwise fs.Stats with two additional path and depth properties.

Options

concurrency

Type: number
Default: Infinity

The maximum number of concurrent calls to fs.readdir.

See more more detailed description in the fs.walk repository.

cwd

Type: string
Default: process.cwd()

The current working directory in which to search.

deep

Type: number|boolean
Default: true

The deep option can be set to true to traverse the entire directory structure, or it can be set to a number to only traverse that many levels deep.

For example, you have the following tree:

test
└── one
    └── two
        └── index.js

📖 If you specify a pattern with some base directory, this directory will not participate in the calculation of the depth of the found directories. Think of it as a cwd option.

fg('test/**', { onlyFiles: false, deep: 0 });
// -> ['test/one']
fg('test/**', { onlyFiles: false, deep: 1 });
// -> ['test/one', 'test/one/two']

fg('**', { onlyFiles: false, cwd: 'test', deep: 0 });
// -> ['one']
fg('**', { onlyFiles: false, cwd: 'test', deep: 1 });
// -> ['one', 'one/two']

ignore

Type: string[]
Default: []

An array of glob patterns to exclude matches.

dot

Type: boolean
Default: false

Allow patterns to match filenames starting with a period (files & directories), even if the pattern does not explicitly have a period in that spot.

stats

Type: boolean
Default: false

Return fs.Stats with two additional path and depth properties instead of a string.

onlyFiles

Type: boolean
Default: true

Return only files.

onlyDirectories

Type: boolean
Default: false

Return only directories.

followSymbolicLinks

Type: boolean
Default: true

Indicates whether to traverse descendants of symbolic link directories.

📖 Also, if the stats option is specified, it tries to get fs.Stats for symbolic link file.

throwErrorOnBrokenSymbolicLink

Type: boolean
Default: true

Throw an error when symbolic link is broken if true or safely return lstat call if false. Always false when the stats option is disabled.

📖 This option has no effect on errors when reading the symbolic link directory.

unique

Type: boolean
Default: true

Prevent duplicate results.

markDirectories

Type: boolean
Default: false

Add a / character to directory entries.

absolute

Type: boolean
Default: false

Return absolute paths for matched entries.

📖 Note that you need to use this option if you want to use absolute negative patterns like ${__dirname}/*.md.

braceExpansion

Type: boolean
Default: true

Enable expansion of brace patterns.

globstar

Type: boolean
Default: true

Enable matching with globstars (**).

extglob

Type: boolean
Default: true

Enable extglob support, so that extglobs are regarded as literal characters.

caseSensitiveMatch

Type: boolean
Default: true

Enable a case-sensitive mode for matching files.

Examples

File System: test/file.md, test/File.md
Case-sensitive for test/file.* pattern: test/file.md
Case-insensitive for test/file.* pattern: test/file.md, test/File.md

matchBase

Type: boolean
Default: false

Allow glob patterns without slashes to match a file path based on its basename. For example, a?b would match the path /xyz/123/acb, but not /xyz/acb/123.

suppressErrors

Type: boolean
Default: false

Suppress any errors from reader. Works only with Node.js 10.10+. Can be useful when the directory has entries with a special level of access.

transform

Type: Function
Default: null

Allows you to transform a path or fs.Stats object before sending to the array.

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

const entries1 = fg.sync(['**/*.scss']);
const entries2 = fg.sync(['**/*.scss'], { transform: (entry) => '_' + entry });

console.log(entries1); // ['a.scss', 'b.scss']
console.log(entries2); // ['_a.scss', '_b.scss']

If you are using TypeScript, you probably want to specify your own type of the returned array.

import * as fg from 'fast-glob';

interface IMyOwnEntry {
	path: string;
}

const entries: IMyOwnEntry[] = fg.sync<IMyOwnEntry>(['*.md'], {
	transform: (entry) => typeof entry === 'string' ? { path: entry } : { path: entry.path }
	// Will throw compilation error for non-IMyOwnEntry types (boolean, for example)
});

fs

Type: FileSystemAdapter
Default: fs.*

Custom implementation of methods for working with the file system.

interface FileSystemAdapter {
    lstat: typeof fs.lstat;
    stat: typeof fs.stat;
    lstatSync: typeof fs.lstatSync;
    statSync: typeof fs.statSync;
    readdir: typeof fs.readdir;
    readdirSync: typeof fs.readdirSync;
}

How to exclude directory from reading?

You can use a negative pattern like this: !**/node_modules or !**/node_modules/**. Also you can use ignore option. Just look at the example below.

first/
├── file.md
└── second
    └── file.txt

If you don't want to read the second directory, you must write the following pattern: !**/second or !**/second/**.

fg.sync(['**/*.md', '!**/second']); // ['first/file.md']
fg.sync(['**/*.md'], { ignore: ['**/second/**'] }); // ['first/file.md']

⚠️ When you write !**/second/**/* it means that the directory will be read, but all the entries will not be included in the results.

You have to understand that if you write the pattern to exclude directories, then the directory will not be read under any circumstances.

Why are parentheses match wrong?

fg.sync(['(special-*file).txt']) // → [] for files: ['(special-*file).txt']

Refers to Bash. You need to escape special characters:

fg.sync(['\\(special-*file\\).txt']) // → ['(special-*file).txt']

How to write patterns on Windows?

Always use forward-slashes in glob expressions (patterns and ignore option). Use backslashes for escaping characters. With the cwd option use a convenient format.

Bad

[
	'directory\\*',
	path.join(process.cwd(), '**')
]

Good

[
	'directory/*',
	path.join(process.cwd(), '**').replace(/\\/g, '/')
]

📖 Use the normalize-path or the unixify package to convert Windows-style path to a Unix-style path.

Read more about matching with backslashes.

How to use UNC path?

You cannot use UNC paths as patterns (due to syntax), but you can use them as cwd directory.

fg.sync('*', { cwd: '\\\\?\\C:\\Python27' /* or //?/C:/Python27 */ });
fg.sync('Python27/*', { cwd: '\\\\?\\C:\\' /* or //?/C:/ */ });

Compatible with `node-glob`?

Not fully, because fast-glob does not implement all options of node-glob. See table below.

node-glob	fast-glob
`cwd`	`cwd`
`root`	–
`dot`	`dot`
`nomount`	–
`mark`	`markDirectories`
`nosort`	–
`nounique`	`unique`
`nobrace`	`braceExpansion`
`noglobstar`	`globstar`
`noext`	`extglob`
`nocase`	`caseSensitiveMatch`
`matchBase`	`matchbase`
`nodir`	`onlyFiles`
`ignore`	`ignore`
`follow`	`followSymbolicLinks`
`realpath`	–
`absolute`	`absolute`

Benchmarks

Tech specs:

Server: Vultr Bare Metal

Processor: E3-1270v6 (8 CPU)
RAM: 32GB
Disk: SSD

You can see results here for latest release.

readdir-enhanced – Fast functional replacement for fs.readdir().
globby – User-friendly glob matching.
node-glob – «Standard» glob functionality for Node.js
bash-glob – Bash-powered globbing for node.js.
glob-stream – A Readable Stream interface over node-glob that used in the gulpjs.
tiny-glob – Tiny and extremely fast library to match files and folders using glob patterns.

Changelog

See the Releases section of our GitHub project for changelogs for each release version.

License

This software is released under the terms of the MIT license.

sipayRT/fast-glob