README.md
1 # Glob 2 3 Match files using the patterns the shell uses, like stars and stuff. 4 5 [](https://travis-ci.org/isaacs/node-glob/) [](https://ci.appveyor.com/project/isaacs/node-glob) [](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  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 * `fs` File-system object with Node's `fs` API. By default, the built-in 280 `fs` module will be used. Set to a volume provided by a library like 281 `memfs` to avoid using the "real" file-system. 282 283 ## Comparisons to other fnmatch/glob implementations 284 285 While strict compliance with the existing standards is a worthwhile 286 goal, some discrepancies exist between node-glob and other 287 implementations, and are intentional. 288 289 The double-star character `**` is supported by default, unless the 290 `noglobstar` flag is set. This is supported in the manner of bsdglob 291 and bash 4.3, where `**` only has special significance if it is the only 292 thing in a path part. That is, `a/**/b` will match `a/x/y/b`, but 293 `a/**b` will not. 294 295 Note that symlinked directories are not crawled as part of a `**`, 296 though their contents may match against subsequent portions of the 297 pattern. This prevents infinite loops and duplicates and the like. 298 299 If an escaped pattern has no matches, and the `nonull` flag is set, 300 then glob returns the pattern as-provided, rather than 301 interpreting the character escapes. For example, 302 `glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than 303 `"*a?"`. This is akin to setting the `nullglob` option in bash, except 304 that it does not resolve escaped pattern characters. 305 306 If brace expansion is not disabled, then it is performed before any 307 other interpretation of the glob pattern. Thus, a pattern like 308 `+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded 309 **first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are 310 checked for validity. Since those two are valid, matching proceeds. 311 312 ### Comments and Negation 313 314 Previously, this module let you mark a pattern as a "comment" if it 315 started with a `#` character, or a "negated" pattern if it started 316 with a `!` character. 317 318 These options were deprecated in version 5, and removed in version 6. 319 320 To specify things that should not match, use the `ignore` option. 321 322 ## Windows 323 324 **Please only use forward-slashes in glob expressions.** 325 326 Though windows uses either `/` or `\` as its path separator, only `/` 327 characters are used by this glob implementation. You must use 328 forward-slashes **only** in glob expressions. Back-slashes will always 329 be interpreted as escape characters, not path separators. 330 331 Results from absolute patterns such as `/foo/*` are mounted onto the 332 root setting using `path.join`. On windows, this will by default result 333 in `/foo/*` matching `C:\foo\bar.txt`. 334 335 ## Race Conditions 336 337 Glob searching, by its very nature, is susceptible to race conditions, 338 since it relies on directory walking and such. 339 340 As a result, it is possible that a file that exists when glob looks for 341 it may have been deleted or modified by the time it returns the result. 342 343 As part of its internal implementation, this program caches all stat 344 and readdir calls that it makes, in order to cut down on system 345 overhead. However, this also makes it even more susceptible to races, 346 especially if the cache or statCache objects are reused between glob 347 calls. 348 349 Users are thus advised not to use a glob result as a guarantee of 350 filesystem state in the face of rapid changes. For the vast majority 351 of operations, this is never a problem. 352 353 ## Glob Logo 354 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). 355 356 The logo is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/). 357 358 ## Contributing 359 360 Any change to behavior (including bugfixes) must come with a test. 361 362 Patches that fail tests or reduce performance will be rejected. 363 364 ``` 365 # to run tests 366 npm test 367 368 # to re-generate test fixtures 369 npm run test-regen 370 371 # to benchmark against bash/zsh 372 npm run bench 373 374 # to profile javascript 375 npm run prof 376 ``` 377 378 