1 | # globby
|
2 |
|
3 | > User-friendly glob matching
|
4 |
|
5 | Based on [`fast-glob`](https://github.com/mrmlnc/fast-glob) but adds a bunch of useful features.
|
6 |
|
7 | ## Features
|
8 |
|
9 | - Promise API
|
10 | - Multiple patterns
|
11 | - Negated patterns: `['foo*', '!foobar']`
|
12 | - Expands directories: `foo` → `foo/**/*`
|
13 | - Supports `.gitignore` and similar ignore config files
|
14 | - Supports `URL` as `cwd`
|
15 |
|
16 | ## Install
|
17 |
|
18 | ```sh
|
19 | npm install globby
|
20 | ```
|
21 |
|
22 | ## Usage
|
23 |
|
24 | ```
|
25 | ├── unicorn
|
26 | ├── cake
|
27 | └── rainbow
|
28 | ```
|
29 |
|
30 | ```js
|
31 | import {globby} from 'globby';
|
32 |
|
33 | const paths = await globby(['*', '!cake']);
|
34 |
|
35 | console.log(paths);
|
36 | //=> ['unicorn', 'rainbow']
|
37 | ```
|
38 |
|
39 | ## API
|
40 |
|
41 | Note that glob patterns can only contain forward-slashes, not backward-slashes, so if you want to construct a glob pattern from path components, you need to use `path.posix.join()` instead of `path.join()`.
|
42 |
|
43 | ### globby(patterns, options?)
|
44 |
|
45 | Returns a `Promise<string[]>` of matching paths.
|
46 |
|
47 | #### patterns
|
48 |
|
49 | Type: `string | string[]`
|
50 |
|
51 | See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
|
52 |
|
53 | #### options
|
54 |
|
55 | Type: `object`
|
56 |
|
57 | See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones below.
|
58 |
|
59 | ##### expandDirectories
|
60 |
|
61 | Type: `boolean | string[] | object`\
|
62 | Default: `true`
|
63 |
|
64 | If set to `true`, `globby` will automatically glob directories for you. If you define an `Array` it will only glob files that matches the patterns inside the `Array`. You can also define an `object` with `files` and `extensions` like below:
|
65 |
|
66 | ```js
|
67 | import {globby} from 'globby';
|
68 |
|
69 | const paths = await globby('images', {
|
70 | expandDirectories: {
|
71 | files: ['cat', 'unicorn', '*.jpg'],
|
72 | extensions: ['png']
|
73 | }
|
74 | });
|
75 |
|
76 | console.log(paths);
|
77 | //=> ['cat.png', 'unicorn.png', 'cow.jpg', 'rainbow.jpg']
|
78 | ```
|
79 |
|
80 | Note that if you set this option to `false`, you won't get back matched directories unless you set `onlyFiles: false`.
|
81 |
|
82 | ##### gitignore
|
83 |
|
84 | Type: `boolean`\
|
85 | Default: `false`
|
86 |
|
87 | Respect ignore patterns in `.gitignore` files that apply to the globbed files.
|
88 |
|
89 | ##### ignoreFiles
|
90 |
|
91 | Type: `string | string[]`\
|
92 | Default: `undefined`
|
93 |
|
94 | Glob patterns to look for ignore files, which are then used to ignore globbed files.
|
95 |
|
96 | This is a more generic form of the `gitignore` option, allowing you to find ignore files with a [compatible syntax](http://git-scm.com/docs/gitignore). For instance, this works with Babel's `.babelignore`, Prettier's `.prettierignore`, or ESLint's `.eslintignore` files.
|
97 |
|
98 | ### globbySync(patterns, options?)
|
99 |
|
100 | Returns `string[]` of matching paths.
|
101 |
|
102 | ### globbyStream(patterns, options?)
|
103 |
|
104 | Returns a [`stream.Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) of matching paths.
|
105 |
|
106 | For example, loop over glob matches in a [`for await...of` loop](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) like this:
|
107 |
|
108 | ```js
|
109 | import {globbyStream} from 'globby';
|
110 |
|
111 | for await (const path of globbyStream('*.tmp')) {
|
112 | console.log(path);
|
113 | }
|
114 | ```
|
115 |
|
116 | ### convertPathToPattern(path)
|
117 |
|
118 | Convert a path to a pattern. [Learn more.](https://github.com/mrmlnc/fast-glob#convertpathtopatternpath)
|
119 |
|
120 | ### generateGlobTasks(patterns, options?)
|
121 |
|
122 | Returns an `Promise<object[]>` in the format `{patterns: string[], options: Object}`, which can be passed as arguments to [`fast-glob`](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.
|
123 |
|
124 | Note that you should avoid running the same tasks multiple times as they contain a file system cache. Instead, run this method each time to ensure file system changes are taken into consideration.
|
125 |
|
126 | ### generateGlobTasksSync(patterns, options?)
|
127 |
|
128 | Returns an `object[]` in the format `{patterns: string[], options: Object}`, which can be passed as arguments to [`fast-glob`](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.
|
129 |
|
130 | Takes the same arguments as `generateGlobTasks`.
|
131 |
|
132 | ### isDynamicPattern(patterns, options?)
|
133 |
|
134 | Returns a `boolean` of whether there are any special glob characters in the `patterns`.
|
135 |
|
136 | Note that the options affect the results.
|
137 |
|
138 | This function is backed by [`fast-glob`](https://github.com/mrmlnc/fast-glob#isdynamicpatternpattern-options).
|
139 |
|
140 | ### isGitIgnored(options?)
|
141 |
|
142 | Returns a `Promise<(path: URL | string) => boolean>` indicating whether a given path is ignored via a `.gitignore` file.
|
143 |
|
144 | Takes `cwd?: URL | string` as options.
|
145 |
|
146 | ```js
|
147 | import {isGitIgnored} from 'globby';
|
148 |
|
149 | const isIgnored = await isGitIgnored();
|
150 |
|
151 | console.log(isIgnored('some/file'));
|
152 | ```
|
153 |
|
154 | ### isGitIgnoredSync(options?)
|
155 |
|
156 | Returns a `(path: URL | string) => boolean` indicating whether a given path is ignored via a `.gitignore` file.
|
157 |
|
158 | Takes `cwd?: URL | string` as options.
|
159 |
|
160 | ## Globbing patterns
|
161 |
|
162 | Just a quick overview.
|
163 |
|
164 | - `*` matches any number of characters, but not `/`
|
165 | - `?` matches a single character, but not `/`
|
166 | - `**` matches any number of characters, including `/`, as long as it's the only thing in a path part
|
167 | - `{}` allows for a comma-separated list of "or" expressions
|
168 | - `!` at the beginning of a pattern will negate the match
|
169 |
|
170 | [Various patterns and expected matches.](https://github.com/sindresorhus/multimatch/blob/main/test/test.js)
|
171 |
|
172 | ## Related
|
173 |
|
174 | - [multimatch](https://github.com/sindresorhus/multimatch) - Match against a list instead of the filesystem
|
175 | - [matcher](https://github.com/sindresorhus/matcher) - Simple wildcard matching
|
176 | - [del](https://github.com/sindresorhus/del) - Delete files and directories
|
177 | - [make-dir](https://github.com/sindresorhus/make-dir) - Make a directory and its parents if needed
|