Projekt

Obecné

Profil

Stáhnout (14.7 KB) Statistiky
| Větev: | Revize:
1 3a515b92 cagy
# Glob
2
3
Match files using the patterns the shell uses, like stars and stuff.
4
5
[![Build Status](https://travis-ci.org/isaacs/node-glob.svg?branch=master)](https://travis-ci.org/isaacs/node-glob/) [![Build Status](https://ci.appveyor.com/api/projects/status/kd7f3yftf7unxlsx?svg=true)](https://ci.appveyor.com/project/isaacs/node-glob) [![Coverage Status](https://coveralls.io/repos/isaacs/node-glob/badge.svg?branch=master&service=github)](https://coveralls.io/github/isaacs/node-glob?branch=master)
6
7
This is a glob implementation in JavaScript.  It uses the `minimatch`
8
library to do its matching.
9
10
![](logo/glob.png)
11
12
## Usage
13
14
Install with npm
15
16
```
17
npm i glob
18
```
19
20
```javascript
21
var glob = require("glob")
22
23
// options is optional
24
glob("**/*.js", options, function (er, files) {
25
  // files is an array of filenames.
26
  // If the `nonull` option is set, and nothing
27
  // was found, then files is ["**/*.js"]
28
  // er is an error object or null.
29
})
30
```
31
32
## Glob Primer
33
34
"Globs" are the patterns you type when you do stuff like `ls *.js` on
35
the command line, or put `build/*` in a `.gitignore` file.
36
37
Before parsing the path part patterns, braced sections are expanded
38
into a set.  Braced sections start with `{` and end with `}`, with any
39
number of comma-delimited sections within.  Braced sections may contain
40
slash characters, so `a{/b/c,bcd}` would expand into `a/b/c` and `abcd`.
41
42
The following characters have special magic meaning when used in a
43
path portion:
44
45
* `*` Matches 0 or more characters in a single path portion
46
* `?` Matches 1 character
47
* `[...]` Matches a range of characters, similar to a RegExp range.
48
  If the first character of the range is `!` or `^` then it matches
49
  any character not in the range.
50
* `!(pattern|pattern|pattern)` Matches anything that does not match
51
  any of the patterns provided.
52
* `?(pattern|pattern|pattern)` Matches zero or one occurrence of the
53
  patterns provided.
54
* `+(pattern|pattern|pattern)` Matches one or more occurrences of the
55
  patterns provided.
56
* `*(a|b|c)` Matches zero or more occurrences of the patterns provided
57
* `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns
58
  provided
59
* `**` If a "globstar" is alone in a path portion, then it matches
60
  zero or more directories and subdirectories searching for matches.
61
  It does not crawl symlinked directories.
62
63
### Dots
64
65
If a file or directory path portion has a `.` as the first character,
66
then it will not match any glob pattern unless that pattern's
67
corresponding path part also has a `.` as its first character.
68
69
For example, the pattern `a/.*/c` would match the file at `a/.b/c`.
70
However the pattern `a/*/c` would not, because `*` does not start with
71
a dot character.
72
73
You can make glob treat dots as normal characters by setting
74
`dot:true` in the options.
75
76
### Basename Matching
77
78
If you set `matchBase:true` in the options, and the pattern has no
79
slashes in it, then it will seek for any file anywhere in the tree
80
with a matching basename.  For example, `*.js` would match
81
`test/simple/basic.js`.
82
83
### Empty Sets
84
85
If no matching files are found, then an empty array is returned.  This
86
differs from the shell, where the pattern itself is returned.  For
87
example:
88
89
    $ echo a*s*d*f
90
    a*s*d*f
91
92
To get the bash-style behavior, set the `nonull:true` in the options.
93
94
### See Also:
95
96
* `man sh`
97
* `man bash` (Search for "Pattern Matching")
98
* `man 3 fnmatch`
99
* `man 5 gitignore`
100
* [minimatch documentation](https://github.com/isaacs/minimatch)
101
102
## glob.hasMagic(pattern, [options])
103
104
Returns `true` if there are any special characters in the pattern, and
105
`false` otherwise.
106
107
Note that the options affect the results.  If `noext:true` is set in
108
the options object, then `+(a|b)` will not be considered a magic
109
pattern.  If the pattern has a brace expansion, like `a/{b/c,x/y}`
110
then that is considered magical, unless `nobrace:true` is set in the
111
options.
112
113
## glob(pattern, [options], cb)
114
115
* `pattern` `{String}` Pattern to be matched
116
* `options` `{Object}`
117
* `cb` `{Function}`
118
  * `err` `{Error | null}`
119
  * `matches` `{Array<String>}` filenames found matching the pattern
120
121
Perform an asynchronous glob search.
122
123
## glob.sync(pattern, [options])
124
125
* `pattern` `{String}` Pattern to be matched
126
* `options` `{Object}`
127
* return: `{Array<String>}` filenames found matching the pattern
128
129
Perform a synchronous glob search.
130
131
## Class: glob.Glob
132
133
Create a Glob object by instantiating the `glob.Glob` class.
134
135
```javascript
136
var Glob = require("glob").Glob
137
var mg = new Glob(pattern, options, cb)
138
```
139
140
It's an EventEmitter, and starts walking the filesystem to find matches
141
immediately.
142
143
### new glob.Glob(pattern, [options], [cb])
144
145
* `pattern` `{String}` pattern to search for
146
* `options` `{Object}`
147
* `cb` `{Function}` Called when an error occurs, or matches are found
148
  * `err` `{Error | null}`
149
  * `matches` `{Array<String>}` filenames found matching the pattern
150
151
Note that if the `sync` flag is set in the options, then matches will
152
be immediately available on the `g.found` member.
153
154
### Properties
155
156
* `minimatch` The minimatch object that the glob uses.
157
* `options` The options object passed in.
158
* `aborted` Boolean which is set to true when calling `abort()`.  There
159
  is no way at this time to continue a glob search after aborting, but
160
  you can re-use the statCache to avoid having to duplicate syscalls.
161
* `cache` Convenience object.  Each field has the following possible
162
  values:
163
  * `false` - Path does not exist
164
  * `true` - Path exists
165
  * `'FILE'` - Path exists, and is not a directory
166
  * `'DIR'` - Path exists, and is a directory
167
  * `[file, entries, ...]` - Path exists, is a directory, and the
168
    array value is the results of `fs.readdir`
169
* `statCache` Cache of `fs.stat` results, to prevent statting the same
170
  path multiple times.
171
* `symlinks` A record of which paths are symbolic links, which is
172
  relevant in resolving `**` patterns.
173
* `realpathCache` An optional object which is passed to `fs.realpath`
174
  to minimize unnecessary syscalls.  It is stored on the instantiated
175
  Glob object, and may be re-used.
176
177
### Events
178
179
* `end` When the matching is finished, this is emitted with all the
180
  matches found.  If the `nonull` option is set, and no match was found,
181
  then the `matches` list contains the original pattern.  The matches
182
  are sorted, unless the `nosort` flag is set.
183
* `match` Every time a match is found, this is emitted with the specific
184
  thing that matched. It is not deduplicated or resolved to a realpath.
185
* `error` Emitted when an unexpected error is encountered, or whenever
186
  any fs error occurs if `options.strict` is set.
187
* `abort` When `abort()` is called, this event is raised.
188
189
### Methods
190
191
* `pause` Temporarily stop the search
192
* `resume` Resume the search
193
* `abort` Stop the search forever
194
195
### Options
196
197
All the options that can be passed to Minimatch can also be passed to
198
Glob to change pattern matching behavior.  Also, some have been added,
199
or have glob-specific ramifications.
200
201
All options are false by default, unless otherwise noted.
202
203
All options are added to the Glob object, as well.
204
205
If you are running many `glob` operations, you can pass a Glob object
206
as the `options` argument to a subsequent operation to shortcut some
207
`stat` and `readdir` calls.  At the very least, you may pass in shared
208
`symlinks`, `statCache`, `realpathCache`, and `cache` options, so that
209
parallel glob operations will be sped up by sharing information about
210
the filesystem.
211
212
* `cwd` The current working directory in which to search.  Defaults
213
  to `process.cwd()`.
214
* `root` The place where patterns starting with `/` will be mounted
215
  onto.  Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix
216
  systems, and `C:\` or some such on Windows.)
217
* `dot` Include `.dot` files in normal matches and `globstar` matches.
218
  Note that an explicit dot in a portion of the pattern will always
219
  match dot files.
220
* `nomount` By default, a pattern starting with a forward-slash will be
221
  "mounted" onto the root setting, so that a valid filesystem path is
222
  returned.  Set this flag to disable that behavior.
223
* `mark` Add a `/` character to directory matches.  Note that this
224
  requires additional stat calls.
225
* `nosort` Don't sort the results.
226
* `stat` Set to true to stat *all* results.  This reduces performance
227
  somewhat, and is completely unnecessary, unless `readdir` is presumed
228
  to be an untrustworthy indicator of file existence.
229
* `silent` When an unusual error is encountered when attempting to
230
  read a directory, a warning will be printed to stderr.  Set the
231
  `silent` option to true to suppress these warnings.
232
* `strict` When an unusual error is encountered when attempting to
233
  read a directory, the process will just continue on in search of
234
  other matches.  Set the `strict` option to raise an error in these
235
  cases.
236
* `cache` See `cache` property above.  Pass in a previously generated
237
  cache object to save some fs calls.
238
* `statCache` A cache of results of filesystem information, to prevent
239
  unnecessary stat calls.  While it should not normally be necessary
240
  to set this, you may pass the statCache from one glob() call to the
241
  options object of another, if you know that the filesystem will not
242
  change between calls.  (See "Race Conditions" below.)
243
* `symlinks` A cache of known symbolic links.  You may pass in a
244
  previously generated `symlinks` object to save `lstat` calls when
245
  resolving `**` matches.
246
* `sync` DEPRECATED: use `glob.sync(pattern, opts)` instead.
247
* `nounique` In some cases, brace-expanded patterns can result in the
248
  same file showing up multiple times in the result set.  By default,
249
  this implementation prevents duplicates in the result set.  Set this
250
  flag to disable that behavior.
251
* `nonull` Set to never return an empty set, instead returning a set
252
  containing the pattern itself.  This is the default in glob(3).
253
* `debug` Set to enable debug logging in minimatch and glob.
254
* `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.
255
* `noglobstar` Do not match `**` against multiple filenames.  (Ie,
256
  treat it as a normal `*` instead.)
257
* `noext` Do not match `+(a|b)` "extglob" patterns.
258
* `nocase` Perform a case-insensitive match.  Note: on
259
  case-insensitive filesystems, non-magic patterns will match by
260
  default, since `stat` and `readdir` will not raise errors.
261
* `matchBase` Perform a basename-only match if the pattern does not
262
  contain any slash characters.  That is, `*.js` would be treated as
263
  equivalent to `**/*.js`, matching all js files in all directories.
264
* `nodir` Do not match directories, only files.  (Note: to match
265
  *only* directories, simply put a `/` at the end of the pattern.)
266
* `ignore` Add a pattern or an array of glob patterns to exclude matches.
267
  Note: `ignore` patterns are *always* in `dot:true` mode, regardless
268
  of any other settings.
269
* `follow` Follow symlinked directories when expanding `**` patterns.
270
  Note that this can result in a lot of duplicate references in the
271
  presence of cyclic links.
272
* `realpath` Set to true to call `fs.realpath` on all of the results.
273
  In the case of a symlink that cannot be resolved, the full absolute
274
  path to the matched entry is returned (though it will usually be a
275
  broken symlink)
276
* `absolute` Set to true to always receive absolute paths for matched
277
  files.  Unlike `realpath`, this also affects the values returned in
278
  the `match` event.
279
280
## Comparisons to other fnmatch/glob implementations
281
282
While strict compliance with the existing standards is a worthwhile
283
goal, some discrepancies exist between node-glob and other
284
implementations, and are intentional.
285
286
The double-star character `**` is supported by default, unless the
287
`noglobstar` flag is set.  This is supported in the manner of bsdglob
288
and bash 4.3, where `**` only has special significance if it is the only
289
thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
290
`a/**b` will not.
291
292
Note that symlinked directories are not crawled as part of a `**`,
293
though their contents may match against subsequent portions of the
294
pattern.  This prevents infinite loops and duplicates and the like.
295
296
If an escaped pattern has no matches, and the `nonull` flag is set,
297
then glob returns the pattern as-provided, rather than
298
interpreting the character escapes.  For example,
299
`glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
300
`"*a?"`.  This is akin to setting the `nullglob` option in bash, except
301
that it does not resolve escaped pattern characters.
302
303
If brace expansion is not disabled, then it is performed before any
304
other interpretation of the glob pattern.  Thus, a pattern like
305
`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
306
**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
307
checked for validity.  Since those two are valid, matching proceeds.
308
309
### Comments and Negation
310
311
Previously, this module let you mark a pattern as a "comment" if it
312
started with a `#` character, or a "negated" pattern if it started
313
with a `!` character.
314
315
These options were deprecated in version 5, and removed in version 6.
316
317
To specify things that should not match, use the `ignore` option.
318
319
## Windows
320
321
**Please only use forward-slashes in glob expressions.**
322
323
Though windows uses either `/` or `\` as its path separator, only `/`
324
characters are used by this glob implementation.  You must use
325
forward-slashes **only** in glob expressions.  Back-slashes will always
326
be interpreted as escape characters, not path separators.
327
328
Results from absolute patterns such as `/foo/*` are mounted onto the
329
root setting using `path.join`.  On windows, this will by default result
330
in `/foo/*` matching `C:\foo\bar.txt`.
331
332
## Race Conditions
333
334
Glob searching, by its very nature, is susceptible to race conditions,
335
since it relies on directory walking and such.
336
337
As a result, it is possible that a file that exists when glob looks for
338
it may have been deleted or modified by the time it returns the result.
339
340
As part of its internal implementation, this program caches all stat
341
and readdir calls that it makes, in order to cut down on system
342
overhead.  However, this also makes it even more susceptible to races,
343
especially if the cache or statCache objects are reused between glob
344
calls.
345
346
Users are thus advised not to use a glob result as a guarantee of
347
filesystem state in the face of rapid changes.  For the vast majority
348
of operations, this is never a problem.
349
350
## Glob Logo
351
Glob's logo was created by [Tanya Brassie](http://tanyabrassie.com/). Logo files can be found [here](https://github.com/isaacs/node-glob/tree/master/logo).
352
353
The logo is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).
354
355
## Contributing
356
357
Any change to behavior (including bugfixes) must come with a test.
358
359
Patches that fail tests or reduce performance will be rejected.
360
361
```
362
# to run tests
363
npm test
364
365
# to re-generate test fixtures
366
npm run test-regen
367
368
# to benchmark against bash/zsh
369
npm run bench
370
371
# to profile javascript
372
npm run prof
373
```
374
375
![](oh-my-glob.gif)