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
Usage
Asynchronous
Synchronous
Stream
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:
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
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:
📖 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.
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.
followSymlinkedDirectories
Type:
boolean
Default:
true
Follow symlinked directories when expanding **
patterns.
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
.
nobrace
Type:
boolean
Default:
false
Disable expansion of brace patterns ({a,b}
, {1..3}
).
brace
Type:
boolean
Default:
true
The nobrace
option without double-negation. This option has a higher priority then nobrace
.
noglobstar
Type:
boolean
Default:
false
Disable matching with globstars (**
).
globstar
Type:
boolean
Default:
true
The noglobstar
option without double-negation. This option has a higher priority then noglobstar
.
noext
Type:
boolean
Default:
false
Disable extglob support (patterns like +(a|b)
), so that extglobs are regarded as literal characters.
extension
Type:
boolean
Default:
true
The noext
option without double-negation. This option has a higher priority then noext
.
nocase
Type:
boolean
Default:
false
Disable a case-sensitive mode for matching files.
Examples
File System:
test/file.md
,test/File.md
Case-sensitive for
test/file.*
pattern (false
):test/file.md
Case-insensitive for
test/file.*
pattern (true
):test/file.md
,test/File.md
case
Type:
boolean
Default:
true
The nocase
option without double-negation. This option has a higher priority then nocase
.
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
.
transform
Type:
Function
Default:
null
Allows you to transform a path or fs.Stats
object before sending to the array.
If you are using TypeScript, you probably want to specify your own type of the returned array.
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.
If you don't want to read the second
directory, you must write the following pattern: !**/second
or !**/second/**
.
⚠️ 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.
How to use UNC path?
You cannot use UNC paths as patterns (due to syntax), but you can use them as cwd
directory.
Compatible with node-glob
?
node-glob
?Not fully, because fast-glob
does not implement all options of node-glob
. See table below.
node-glob | fast-glob |
---|---|
| |
| – |
| |
| – |
| |
| – |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| – |
|
Benchmarks
Tech specs:
Server: Vultr Bare Metal
Processor: E3-1270v6 (8 CPU)
RAM: 32GB
Disk: SSD
You can see results here for latest release.
Related
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.
Last updated