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