UNPKG

4.89 kBMarkdownView Raw
1<p align="center">
2 <img src="https://github.com/terkelg/tiny-glob/raw/master/tiny-glob.png" alt="Tiny Glob" width="450" height="288" />
3</p>
4
5<h1 align="center">tiny glob</h1>
6
7<p align="center">
8 <a href="https://npmjs.org/package/tiny-glob">
9 <img src="https://img.shields.io/npm/v/tiny-glob.svg" alt="version" />
10 </a>
11 <a href="https://travis-ci.org/terkelg/tiny-glob">
12 <img src="https://img.shields.io/travis/terkelg/tiny-glob.svg" alt="travis" />
13 </a>
14 <a href="https://ci.appveyor.com/project/terkelg/tiny-glob/branch/master">
15 <img src="https://ci.appveyor.com/api/projects/status/qe8sm2c7mwm0hxud/branch/master?svg=true" alt="AppVeyor"/>
16 </a>
17 <a href="https://npmjs.org/package/tiny-glob">
18 <img src="https://img.shields.io/npm/dm/tiny-glob.svg" alt="downloads" />
19 </a>
20</p>
21
22<p align="center"><b>Tiny and extremely fast library to match files and folders using glob patterns.</b></p>
23
24<br />
25
26
27"Globs" is the common name for a specific type of pattern used to match files and folders. It's the patterns you type when you do stuff like `ls *.js` in your shell or put `src/*` in a `.gitignore` file. When used to match filenames, it's sometimes called a "wildcard".
28
29
30## Install
31
32```
33npm install tiny-glob
34```
35
36
37## Core Features
38
39- 🔥 **extremely fast:** ~350% faster than [node-glob](https://github.com/isaacs/node-glob) and ~230% faster than [fast-glob](https://github.com/mrmlnc/fast-glob)
40- 💪 **powerful:** supports advanced globbing patterns (`ExtGlob`)
41- 📦 **tiny**: only ~70 LOC with 2 small dependencies
42- 👫 **friendly**: simple and easy to use api
43- 🎭 **cross-platform**: supports both unix and windows
44
45
46## Usage
47
48```js
49const glob = require('tiny-glob');
50
51(async function(){
52 let files = await glob('src/*/*.{js,md}');
53 // => [ ... ] array of matching files
54})();
55```
56
57
58## API
59
60
61### glob(str, options)
62
63Type: `function`<br>
64Returns: `Array`
65
66Return array of matching files and folders
67This function is `async` and returns a promise.
68
69#### str
70
71Type: `String`
72
73The glob pattern to match against.
74> **OBS**: Please only use forward-slashes in glob expressions. Even on [windows](#windows)
75
76#### options.cwd
77
78Type: `String`<br>
79Default: `'.'`
80
81Change default working directory.
82
83#### options.dot
84
85Type: `Boolean`<br>
86Default: `false`
87
88Allow patterns to match filenames or directories that begin with a period (`.`).
89
90#### options.absolute
91
92Type: `Boolean`<br>
93Default: `false`
94
95Return matches as absolute paths.
96
97#### options.filesOnly
98
99Type: `Boolean`<br>
100Default: `false`
101
102Skip directories and return matched files only.
103
104#### options.flush
105
106Type: `Boolean`<br>
107Default: `false`
108
109Flush the internal cache object.
110
111
112## Windows
113
114Though Windows may use `/`, `\`, or `\\` as path separators, you can **only** use forward-slashes (`/`) when specifying glob expressions. Any back-slashes (`\`) will be interpreted as escape characters instead of path separators.
115
116This is common across many glob-based modules; see [`node-glob`](https://github.com/isaacs/node-glob#windows) for corroboration.
117
118
119## Benchmarks
120
121```
122glob x 13,405 ops/sec ±1.80% (85 runs sampled)
123fast-glob x 25,745 ops/sec ±2.76% (59 runs sampled)
124tiny-glob x 102,658 ops/sec ±0.79% (91 runs sampled)
125Fastest is tiny-glob
126┌───────────┬─────────────────────────┬─────────────┬────────────────┐
127│ Name │ Mean time │ Ops/sec │ Diff │
128├───────────┼─────────────────────────┼─────────────┼────────────────┤
129│ glob │ 0.00007459990597268128 │ 13,404.843 │ N/A │
130├───────────┼─────────────────────────┼─────────────┼────────────────┤
131│ fast-glob │ 0.000038842529587611705 │ 25,744.976 │ 92.06% faster │
132├───────────┼─────────────────────────┼─────────────┼────────────────┤
133│ tiny-glob │ 0.00000974110141018254 │ 102,657.796 │ 298.75% faster │
134└───────────┴─────────────────────────┴─────────────┴────────────────┘
135```
136
137## Advanced Globbing
138
139Learn more about advanced globbing
140
141 - [Greg's Wiki](https://mywiki.wooledge.org/glob)
142 - [Bash Extended Globbing](https://www.linuxjournal.com/content/bash-extended-globbing)
143
144
145## License
146
147MIT © [Terkel Gjervig](https://terkel.com)