1 [![Build Status](https://travis-ci.org/isaacs/node-glob.svg?branch=master)](https://travis-ci.org/isaacs/node-glob/) [![Dependency Status](https://david-dm.org/isaacs/node-glob.svg)](https://david-dm.org/isaacs/node-glob) [![devDependency Status](https://david-dm.org/isaacs/node-glob/dev-status.svg)](https://david-dm.org/isaacs/node-glob#info=devDependencies) [![optionalDependency Status](https://david-dm.org/isaacs/node-glob/optional-status.svg)](https://david-dm.org/isaacs/node-glob#info=optionalDependencies)
5 Match files using the patterns the shell uses, like stars and stuff.
7 This is a glob implementation in JavaScript. It uses the `minimatch`
8 library to do its matching.
15 var glob = require("glob")
17 // options is optional
18 glob("**/*.js", options, function (er, files) {
19 // files is an array of filenames.
20 // If the `nonull` option is set, and nothing
21 // was found, then files is ["**/*.js"]
22 // er is an error object or null.
28 "Globs" are the patterns you type when you do stuff like `ls *.js` on
29 the command line, or put `build/*` in a `.gitignore` file.
31 Before parsing the path part patterns, braced sections are expanded
32 into a set. Braced sections start with `{` and end with `}`, with any
33 number of comma-delimited sections within. Braced sections may contain
34 slash characters, so `a{/b/c,bcd}` would expand into `a/b/c` and `abcd`.
36 The following characters have special magic meaning when used in a
39 * `*` Matches 0 or more characters in a single path portion
40 * `?` Matches 1 character
41 * `[...]` Matches a range of characters, similar to a RegExp range.
42 If the first character of the range is `!` or `^` then it matches
43 any character not in the range.
44 * `!(pattern|pattern|pattern)` Matches anything that does not match
45 any of the patterns provided.
46 * `?(pattern|pattern|pattern)` Matches zero or one occurrence of the
48 * `+(pattern|pattern|pattern)` Matches one or more occurrences of the
50 * `*(a|b|c)` Matches zero or more occurrences of the patterns provided
51 * `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns
53 * `**` If a "globstar" is alone in a path portion, then it matches
54 zero or more directories and subdirectories searching for matches.
55 It does not crawl symlinked directories.
59 If a file or directory path portion has a `.` as the first character,
60 then it will not match any glob pattern unless that pattern's
61 corresponding path part also has a `.` as its first character.
63 For example, the pattern `a/.*/c` would match the file at `a/.b/c`.
64 However the pattern `a/*/c` would not, because `*` does not start with
67 You can make glob treat dots as normal characters by setting
68 `dot:true` in the options.
72 If you set `matchBase:true` in the options, and the pattern has no
73 slashes in it, then it will seek for any file anywhere in the tree
74 with a matching basename. For example, `*.js` would match
75 `test/simple/basic.js`.
79 The intent for negation would be for a pattern starting with `!` to
80 match everything that *doesn't* match the supplied pattern. However,
81 the implementation is weird, and for the time being, this should be
82 avoided. The behavior is deprecated in version 5, and will be removed
83 entirely in version 6.
87 If no matching files are found, then an empty array is returned. This
88 differs from the shell, where the pattern itself is returned. For
94 To get the bash-style behavior, set the `nonull:true` in the options.
99 * `man bash` (Search for "Pattern Matching")
102 * [minimatch documentation](https://github.com/isaacs/minimatch)
104 ## glob.hasMagic(pattern, [options])
106 Returns `true` if there are any special characters in the pattern, and
109 Note that the options affect the results. If `noext:true` is set in
110 the options object, then `+(a|b)` will not be considered a magic
111 pattern. If the pattern has a brace expansion, like `a/{b/c,x/y}`
112 then that is considered magical, unless `nobrace:true` is set in the
115 ## glob(pattern, [options], cb)
117 * `pattern` {String} Pattern to be matched
120 * `err` {Error | null}
121 * `matches` {Array<String>} filenames found matching the pattern
123 Perform an asynchronous glob search.
125 ## glob.sync(pattern, [options])
127 * `pattern` {String} Pattern to be matched
129 * return: {Array<String>} filenames found matching the pattern
131 Perform a synchronous glob search.
135 Create a Glob object by instantiating the `glob.Glob` class.
138 var Glob = require("glob").Glob
139 var mg = new Glob(pattern, options, cb)
142 It's an EventEmitter, and starts walking the filesystem to find matches
145 ### new glob.Glob(pattern, [options], [cb])
147 * `pattern` {String} pattern to search for
149 * `cb` {Function} Called when an error occurs, or matches are found
150 * `err` {Error | null}
151 * `matches` {Array<String>} filenames found matching the pattern
153 Note that if the `sync` flag is set in the options, then matches will
154 be immediately available on the `g.found` member.
158 * `minimatch` The minimatch object that the glob uses.
159 * `options` The options object passed in.
160 * `aborted` Boolean which is set to true when calling `abort()`. There
161 is no way at this time to continue a glob search after aborting, but
162 you can re-use the statCache to avoid having to duplicate syscalls.
163 * `cache` Convenience object. Each field has the following possible
165 * `false` - Path does not exist
166 * `true` - Path exists
167 * `'DIR'` - Path exists, and is not a directory
168 * `'FILE'` - Path exists, and is a directory
169 * `[file, entries, ...]` - Path exists, is a directory, and the
170 array value is the results of `fs.readdir`
171 * `statCache` Cache of `fs.stat` results, to prevent statting the same
173 * `symlinks` A record of which paths are symbolic links, which is
174 relevant in resolving `**` patterns.
175 * `realpathCache` An optional object which is passed to `fs.realpath`
176 to minimize unnecessary syscalls. It is stored on the instantiated
177 Glob object, and may be re-used.
181 * `end` When the matching is finished, this is emitted with all the
182 matches found. If the `nonull` option is set, and no match was found,
183 then the `matches` list contains the original pattern. The matches
184 are sorted, unless the `nosort` flag is set.
185 * `match` Every time a match is found, this is emitted with the matched.
186 * `error` Emitted when an unexpected error is encountered, or whenever
187 any fs error occurs if `options.strict` is set.
188 * `abort` When `abort()` is called, this event is raised.
192 * `pause` Temporarily stop the search
193 * `resume` Resume the search
194 * `abort` Stop the search forever
198 All the options that can be passed to Minimatch can also be passed to
199 Glob to change pattern matching behavior. Also, some have been added,
200 or have glob-specific ramifications.
202 All options are false by default, unless otherwise noted.
204 All options are added to the Glob object, as well.
206 If you are running many `glob` operations, you can pass a Glob object
207 as the `options` argument to a subsequent operation to shortcut some
208 `stat` and `readdir` calls. At the very least, you may pass in shared
209 `symlinks`, `statCache`, `realpathCache`, and `cache` options, so that
210 parallel glob operations will be sped up by sharing information about
213 * `cwd` The current working directory in which to search. Defaults
215 * `root` The place where patterns starting with `/` will be mounted
216 onto. Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix
217 systems, and `C:\` or some such on Windows.)
218 * `dot` Include `.dot` files in normal matches and `globstar` matches.
219 Note that an explicit dot in a portion of the pattern will always
221 * `nomount` By default, a pattern starting with a forward-slash will be
222 "mounted" onto the root setting, so that a valid filesystem path is
223 returned. Set this flag to disable that behavior.
224 * `mark` Add a `/` character to directory matches. Note that this
225 requires additional stat calls.
226 * `nosort` Don't sort the results.
227 * `stat` Set to true to stat *all* results. This reduces performance
228 somewhat, and is completely unnecessary, unless `readdir` is presumed
229 to be an untrustworthy indicator of file existence.
230 * `silent` When an unusual error is encountered when attempting to
231 read a directory, a warning will be printed to stderr. Set the
232 `silent` option to true to suppress these warnings.
233 * `strict` When an unusual error is encountered when attempting to
234 read a directory, the process will just continue on in search of
235 other matches. Set the `strict` option to raise an error in these
237 * `cache` See `cache` property above. Pass in a previously generated
238 cache object to save some fs calls.
239 * `statCache` A cache of results of filesystem information, to prevent
240 unnecessary stat calls. While it should not normally be necessary
241 to set this, you may pass the statCache from one glob() call to the
242 options object of another, if you know that the filesystem will not
243 change between calls. (See "Race Conditions" below.)
244 * `symlinks` A cache of known symbolic links. You may pass in a
245 previously generated `symlinks` object to save `lstat` calls when
246 resolving `**` matches.
247 * `sync` DEPRECATED: use `glob.sync(pattern, opts)` instead.
248 * `nounique` In some cases, brace-expanded patterns can result in the
249 same file showing up multiple times in the result set. By default,
250 this implementation prevents duplicates in the result set. Set this
251 flag to disable that behavior.
252 * `nonull` Set to never return an empty set, instead returning a set
253 containing the pattern itself. This is the default in glob(3).
254 * `debug` Set to enable debug logging in minimatch and glob.
255 * `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.
256 * `noglobstar` Do not match `**` against multiple filenames. (Ie,
257 treat it as a normal `*` instead.)
258 * `noext` Do not match `+(a|b)` "extglob" patterns.
259 * `nocase` Perform a case-insensitive match. Note: on
260 case-insensitive filesystems, non-magic patterns will match by
261 default, since `stat` and `readdir` will not raise errors.
262 * `matchBase` Perform a basename-only match if the pattern does not
263 contain any slash characters. That is, `*.js` would be treated as
264 equivalent to `**/*.js`, matching all js files in all directories.
265 * `nodir` Do not match directories, only files. (Note: to match
266 *only* directories, simply put a `/` at the end of the pattern.)
267 * `ignore` Add a pattern or an array of patterns to exclude matches.
268 * `follow` Follow symlinked directories when expanding `**` patterns.
269 Note that this can result in a lot of duplicate references in the
270 presence of cyclic links.
271 * `realpath` Set to true to call `fs.realpath` on all of the results.
272 In the case of a symlink that cannot be resolved, the full absolute
273 path to the matched entry is returned (though it will usually be a
275 * `nonegate` Suppress deprecated `negate` behavior. (See below.)
277 * `nocomment` Suppress deprecated `comment` behavior. (See below.)
280 ## Comparisons to other fnmatch/glob implementations
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.
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
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.
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.
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.
309 ### Comments and Negation
311 **Note**: In version 5 of this module, negation and comments are
312 **disabled** by default. You can explicitly set `nonegate:false` or
313 `nocomment:false` to re-enable them. They are going away entirely in
316 The intent for negation would be for a pattern starting with `!` to
317 match everything that *doesn't* match the supplied pattern. However,
318 the implementation is weird. It is better to use the `ignore` option
319 to set a pattern or set of patterns to exclude from matches. If you
320 want the "everything except *x*" type of behavior, you can use `**` as
321 the main pattern, and set an `ignore` for the things to exclude.
323 The comments feature is added in minimatch, primarily to more easily
324 support use cases like ignore files, where a `#` at the start of a
325 line makes the pattern "empty". However, in the context of a
326 straightforward filesystem globber, "comments" don't make much sense.
330 **Please only use forward-slashes in glob expressions.**
332 Though windows uses either `/` or `\` as its path separator, only `/`
333 characters are used by this glob implementation. You must use
334 forward-slashes **only** in glob expressions. Back-slashes will always
335 be interpreted as escape characters, not path separators.
337 Results from absolute patterns such as `/foo/*` are mounted onto the
338 root setting using `path.join`. On windows, this will by default result
339 in `/foo/*` matching `C:\foo\bar.txt`.
343 Glob searching, by its very nature, is susceptible to race conditions,
344 since it relies on directory walking and such.
346 As a result, it is possible that a file that exists when glob looks for
347 it may have been deleted or modified by the time it returns the result.
349 As part of its internal implementation, this program caches all stat
350 and readdir calls that it makes, in order to cut down on system
351 overhead. However, this also makes it even more susceptible to races,
352 especially if the cache or statCache objects are reused between glob
355 Users are thus advised not to use a glob result as a guarantee of
356 filesystem state in the face of rapid changes. For the vast majority
357 of operations, this is never a problem.
361 Any change to behavior (including bugfixes) must come with a test.
363 Patches that fail tests or reduce performance will be rejected.
369 # to re-generate test fixtures
372 # to benchmark against bash/zsh
375 # to profile javascript