|
|
@@ -0,0 +1,357 @@
|
|
|
+[](https://travis-ci.org/isaacs/node-glob/) [](https://david-dm.org/isaacs/node-glob) [](https://david-dm.org/isaacs/node-glob#info=devDependencies) [](https://david-dm.org/isaacs/node-glob#info=optionalDependencies)
|
|
|
+
|
|
|
+# Glob
|
|
|
+
|
|
|
+Match files using the patterns the shell uses, like stars and stuff.
|
|
|
+
|
|
|
+This is a glob implementation in JavaScript. It uses the `minimatch`
|
|
|
+library to do its matching.
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+## Usage
|
|
|
+
|
|
|
+```javascript
|
|
|
+var glob = require("glob")
|
|
|
+
|
|
|
+// options is optional
|
|
|
+glob("**/*.js", options, function (er, files) {
|
|
|
+ // files is an array of filenames.
|
|
|
+ // If the `nonull` option is set, and nothing
|
|
|
+ // was found, then files is ["**/*.js"]
|
|
|
+ // er is an error object or null.
|
|
|
+})
|
|
|
+```
|
|
|
+
|
|
|
+## Glob Primer
|
|
|
+
|
|
|
+"Globs" are the patterns you type when you do stuff like `ls *.js` on
|
|
|
+the command line, or put `build/*` in a `.gitignore` file.
|
|
|
+
|
|
|
+Before parsing the path part patterns, braced sections are expanded
|
|
|
+into a set. Braced sections start with `{` and end with `}`, with any
|
|
|
+number of comma-delimited sections within. Braced sections may contain
|
|
|
+slash characters, so `a{/b/c,bcd}` would expand into `a/b/c` and `abcd`.
|
|
|
+
|
|
|
+The following characters have special magic meaning when used in a
|
|
|
+path portion:
|
|
|
+
|
|
|
+* `*` Matches 0 or more characters in a single path portion
|
|
|
+* `?` Matches 1 character
|
|
|
+* `[...]` Matches a range of characters, similar to a RegExp range.
|
|
|
+ If the first character of the range is `!` or `^` then it matches
|
|
|
+ any character not in the range.
|
|
|
+* `!(pattern|pattern|pattern)` Matches anything that does not match
|
|
|
+ any of the patterns provided.
|
|
|
+* `?(pattern|pattern|pattern)` Matches zero or one occurrence of the
|
|
|
+ patterns provided.
|
|
|
+* `+(pattern|pattern|pattern)` Matches one or more occurrences of the
|
|
|
+ patterns provided.
|
|
|
+* `*(a|b|c)` Matches zero or more occurrences of the patterns provided
|
|
|
+* `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns
|
|
|
+ provided
|
|
|
+* `**` If a "globstar" is alone in a path portion, then it matches
|
|
|
+ zero or more directories and subdirectories searching for matches.
|
|
|
+ It does not crawl symlinked directories.
|
|
|
+
|
|
|
+### Dots
|
|
|
+
|
|
|
+If a file or directory path portion has a `.` as the first character,
|
|
|
+then it will not match any glob pattern unless that pattern's
|
|
|
+corresponding path part also has a `.` as its first character.
|
|
|
+
|
|
|
+For example, the pattern `a/.*/c` would match the file at `a/.b/c`.
|
|
|
+However the pattern `a/*/c` would not, because `*` does not start with
|
|
|
+a dot character.
|
|
|
+
|
|
|
+You can make glob treat dots as normal characters by setting
|
|
|
+`dot:true` in the options.
|
|
|
+
|
|
|
+### Basename Matching
|
|
|
+
|
|
|
+If you set `matchBase:true` in the options, and the pattern has no
|
|
|
+slashes in it, then it will seek for any file anywhere in the tree
|
|
|
+with a matching basename. For example, `*.js` would match
|
|
|
+`test/simple/basic.js`.
|
|
|
+
|
|
|
+### Negation
|
|
|
+
|
|
|
+The intent for negation would be for a pattern starting with `!` to
|
|
|
+match everything that *doesn't* match the supplied pattern. However,
|
|
|
+the implementation is weird, and for the time being, this should be
|
|
|
+avoided. The behavior will change or be deprecated in version 5.
|
|
|
+
|
|
|
+### Empty Sets
|
|
|
+
|
|
|
+If no matching files are found, then an empty array is returned. This
|
|
|
+differs from the shell, where the pattern itself is returned. For
|
|
|
+example:
|
|
|
+
|
|
|
+ $ echo a*s*d*f
|
|
|
+ a*s*d*f
|
|
|
+
|
|
|
+To get the bash-style behavior, set the `nonull:true` in the options.
|
|
|
+
|
|
|
+### See Also:
|
|
|
+
|
|
|
+* `man sh`
|
|
|
+* `man bash` (Search for "Pattern Matching")
|
|
|
+* `man 3 fnmatch`
|
|
|
+* `man 5 gitignore`
|
|
|
+* [minimatch documentation](https://github.com/isaacs/minimatch)
|
|
|
+
|
|
|
+## glob.hasMagic(pattern, [options])
|
|
|
+
|
|
|
+Returns `true` if there are any special characters in the pattern, and
|
|
|
+`false` otherwise.
|
|
|
+
|
|
|
+Note that the options affect the results. If `noext:true` is set in
|
|
|
+the options object, then `+(a|b)` will not be considered a magic
|
|
|
+pattern. If the pattern has a brace expansion, like `a/{b/c,x/y}`
|
|
|
+then that is considered magical, unless `nobrace:true` is set in the
|
|
|
+options.
|
|
|
+
|
|
|
+## glob(pattern, [options], cb)
|
|
|
+
|
|
|
+* `pattern` {String} Pattern to be matched
|
|
|
+* `options` {Object}
|
|
|
+* `cb` {Function}
|
|
|
+ * `err` {Error | null}
|
|
|
+ * `matches` {Array<String>} filenames found matching the pattern
|
|
|
+
|
|
|
+Perform an asynchronous glob search.
|
|
|
+
|
|
|
+## glob.sync(pattern, [options])
|
|
|
+
|
|
|
+* `pattern` {String} Pattern to be matched
|
|
|
+* `options` {Object}
|
|
|
+* return: {Array<String>} filenames found matching the pattern
|
|
|
+
|
|
|
+Perform a synchronous glob search.
|
|
|
+
|
|
|
+## Class: glob.Glob
|
|
|
+
|
|
|
+Create a Glob object by instantiating the `glob.Glob` class.
|
|
|
+
|
|
|
+```javascript
|
|
|
+var Glob = require("glob").Glob
|
|
|
+var mg = new Glob(pattern, options, cb)
|
|
|
+```
|
|
|
+
|
|
|
+It's an EventEmitter, and starts walking the filesystem to find matches
|
|
|
+immediately.
|
|
|
+
|
|
|
+### new glob.Glob(pattern, [options], [cb])
|
|
|
+
|
|
|
+* `pattern` {String} pattern to search for
|
|
|
+* `options` {Object}
|
|
|
+* `cb` {Function} Called when an error occurs, or matches are found
|
|
|
+ * `err` {Error | null}
|
|
|
+ * `matches` {Array<String>} filenames found matching the pattern
|
|
|
+
|
|
|
+Note that if the `sync` flag is set in the options, then matches will
|
|
|
+be immediately available on the `g.found` member.
|
|
|
+
|
|
|
+### Properties
|
|
|
+
|
|
|
+* `minimatch` The minimatch object that the glob uses.
|
|
|
+* `options` The options object passed in.
|
|
|
+* `aborted` Boolean which is set to true when calling `abort()`. There
|
|
|
+ is no way at this time to continue a glob search after aborting, but
|
|
|
+ you can re-use the statCache to avoid having to duplicate syscalls.
|
|
|
+* `statCache` Collection of all the stat results the glob search
|
|
|
+ performed.
|
|
|
+* `cache` Convenience object. Each field has the following possible
|
|
|
+ values:
|
|
|
+ * `false` - Path does not exist
|
|
|
+ * `true` - Path exists
|
|
|
+ * `'DIR'` - Path exists, and is not a directory
|
|
|
+ * `'FILE'` - Path exists, and is a directory
|
|
|
+ * `[file, entries, ...]` - Path exists, is a directory, and the
|
|
|
+ array value is the results of `fs.readdir`
|
|
|
+* `statCache` Cache of `fs.stat` results, to prevent statting the same
|
|
|
+ path multiple times.
|
|
|
+* `symlinks` A record of which paths are symbolic links, which is
|
|
|
+ relevant in resolving `**` patterns.
|
|
|
+
|
|
|
+### Events
|
|
|
+
|
|
|
+* `end` When the matching is finished, this is emitted with all the
|
|
|
+ matches found. If the `nonull` option is set, and no match was found,
|
|
|
+ then the `matches` list contains the original pattern. The matches
|
|
|
+ are sorted, unless the `nosort` flag is set.
|
|
|
+* `match` Every time a match is found, this is emitted with the matched.
|
|
|
+* `error` Emitted when an unexpected error is encountered, or whenever
|
|
|
+ any fs error occurs if `options.strict` is set.
|
|
|
+* `abort` When `abort()` is called, this event is raised.
|
|
|
+
|
|
|
+### Methods
|
|
|
+
|
|
|
+* `pause` Temporarily stop the search
|
|
|
+* `resume` Resume the search
|
|
|
+* `abort` Stop the search forever
|
|
|
+
|
|
|
+### Options
|
|
|
+
|
|
|
+All the options that can be passed to Minimatch can also be passed to
|
|
|
+Glob to change pattern matching behavior. Also, some have been added,
|
|
|
+or have glob-specific ramifications.
|
|
|
+
|
|
|
+All options are false by default, unless otherwise noted.
|
|
|
+
|
|
|
+All options are added to the Glob object, as well.
|
|
|
+
|
|
|
+If you are running many `glob` operations, you can pass a Glob object
|
|
|
+as the `options` argument to a subsequent operation to shortcut some
|
|
|
+`stat` and `readdir` calls. At the very least, you may pass in shared
|
|
|
+`symlinks`, `statCache`, and `cache` options, so that parallel glob
|
|
|
+operations will be sped up by sharing information about the
|
|
|
+filesystem.
|
|
|
+
|
|
|
+* `cwd` The current working directory in which to search. Defaults
|
|
|
+ to `process.cwd()`.
|
|
|
+* `root` The place where patterns starting with `/` will be mounted
|
|
|
+ onto. Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix
|
|
|
+ systems, and `C:\` or some such on Windows.)
|
|
|
+* `dot` Include `.dot` files in normal matches and `globstar` matches.
|
|
|
+ Note that an explicit dot in a portion of the pattern will always
|
|
|
+ match dot files.
|
|
|
+* `nomount` By default, a pattern starting with a forward-slash will be
|
|
|
+ "mounted" onto the root setting, so that a valid filesystem path is
|
|
|
+ returned. Set this flag to disable that behavior.
|
|
|
+* `mark` Add a `/` character to directory matches. Note that this
|
|
|
+ requires additional stat calls.
|
|
|
+* `nosort` Don't sort the results.
|
|
|
+* `stat` Set to true to stat *all* results. This reduces performance
|
|
|
+ somewhat, and is completely unnecessary, unless `readdir` is presumed
|
|
|
+ to be an untrustworthy indicator of file existence.
|
|
|
+* `silent` When an unusual error is encountered when attempting to
|
|
|
+ read a directory, a warning will be printed to stderr. Set the
|
|
|
+ `silent` option to true to suppress these warnings.
|
|
|
+* `strict` When an unusual error is encountered when attempting to
|
|
|
+ read a directory, the process will just continue on in search of
|
|
|
+ other matches. Set the `strict` option to raise an error in these
|
|
|
+ cases.
|
|
|
+* `cache` See `cache` property above. Pass in a previously generated
|
|
|
+ cache object to save some fs calls.
|
|
|
+* `statCache` A cache of results of filesystem information, to prevent
|
|
|
+ unnecessary stat calls. While it should not normally be necessary
|
|
|
+ to set this, you may pass the statCache from one glob() call to the
|
|
|
+ options object of another, if you know that the filesystem will not
|
|
|
+ change between calls. (See "Race Conditions" below.)
|
|
|
+* `symlinks` A cache of known symbolic links. You may pass in a
|
|
|
+ previously generated `symlinks` object to save `lstat` calls when
|
|
|
+ resolving `**` matches.
|
|
|
+* `sync` Perform a synchronous glob search.
|
|
|
+* `nounique` In some cases, brace-expanded patterns can result in the
|
|
|
+ same file showing up multiple times in the result set. By default,
|
|
|
+ this implementation prevents duplicates in the result set. Set this
|
|
|
+ flag to disable that behavior.
|
|
|
+* `nonull` Set to never return an empty set, instead returning a set
|
|
|
+ containing the pattern itself. This is the default in glob(3).
|
|
|
+* `debug` Set to enable debug logging in minimatch and glob.
|
|
|
+* `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.
|
|
|
+* `noglobstar` Do not match `**` against multiple filenames. (Ie,
|
|
|
+ treat it as a normal `*` instead.)
|
|
|
+* `noext` Do not match `+(a|b)` "extglob" patterns.
|
|
|
+* `nocase` Perform a case-insensitive match. Note: on
|
|
|
+ case-insensitive filesystems, non-magic patterns will match by
|
|
|
+ default, since `stat` and `readdir` will not raise errors.
|
|
|
+* `matchBase` Perform a basename-only match if the pattern does not
|
|
|
+ contain any slash characters. That is, `*.js` would be treated as
|
|
|
+ equivalent to `**/*.js`, matching all js files in all directories.
|
|
|
+* `nonegate` Suppress `negate` behavior. (See below.)
|
|
|
+* `nocomment` Suppress `comment` behavior. (See below.)
|
|
|
+* `nonull` Return the pattern when no matches are found.
|
|
|
+* `nodir` Do not match directories, only files.
|
|
|
+
|
|
|
+## Comparisons to other fnmatch/glob implementations
|
|
|
+
|
|
|
+While strict compliance with the existing standards is a worthwhile
|
|
|
+goal, some discrepancies exist between node-glob and other
|
|
|
+implementations, and are intentional.
|
|
|
+
|
|
|
+If the pattern starts with a `!` character, then it is negated. Set the
|
|
|
+`nonegate` flag to suppress this behavior, and treat leading `!`
|
|
|
+characters normally. This is perhaps relevant if you wish to start the
|
|
|
+pattern with a negative extglob pattern like `!(a|B)`. Multiple `!`
|
|
|
+characters at the start of a pattern will negate the pattern multiple
|
|
|
+times.
|
|
|
+
|
|
|
+If a pattern starts with `#`, then it is treated as a comment, and
|
|
|
+will not match anything. Use `\#` to match a literal `#` at the
|
|
|
+start of a line, or set the `nocomment` flag to suppress this behavior.
|
|
|
+
|
|
|
+The double-star character `**` is supported by default, unless the
|
|
|
+`noglobstar` flag is set. This is supported in the manner of bsdglob
|
|
|
+and bash 4.3, where `**` only has special significance if it is the only
|
|
|
+thing in a path part. That is, `a/**/b` will match `a/x/y/b`, but
|
|
|
+`a/**b` will not.
|
|
|
+
|
|
|
+Note that symlinked directories are not crawled as part of a `**`,
|
|
|
+though their contents may match against subsequent portions of the
|
|
|
+pattern. This prevents infinite loops and duplicates and the like.
|
|
|
+
|
|
|
+If an escaped pattern has no matches, and the `nonull` flag is set,
|
|
|
+then glob returns the pattern as-provided, rather than
|
|
|
+interpreting the character escapes. For example,
|
|
|
+`glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
|
|
|
+`"*a?"`. This is akin to setting the `nullglob` option in bash, except
|
|
|
+that it does not resolve escaped pattern characters.
|
|
|
+
|
|
|
+If brace expansion is not disabled, then it is performed before any
|
|
|
+other interpretation of the glob pattern. Thus, a pattern like
|
|
|
+`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
|
|
|
+**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
|
|
|
+checked for validity. Since those two are valid, matching proceeds.
|
|
|
+
|
|
|
+## Windows
|
|
|
+
|
|
|
+**Please only use forward-slashes in glob expressions.**
|
|
|
+
|
|
|
+Though windows uses either `/` or `\` as its path separator, only `/`
|
|
|
+characters are used by this glob implementation. You must use
|
|
|
+forward-slashes **only** in glob expressions. Back-slashes will always
|
|
|
+be interpreted as escape characters, not path separators.
|
|
|
+
|
|
|
+Results from absolute patterns such as `/foo/*` are mounted onto the
|
|
|
+root setting using `path.join`. On windows, this will by default result
|
|
|
+in `/foo/*` matching `C:\foo\bar.txt`.
|
|
|
+
|
|
|
+## Race Conditions
|
|
|
+
|
|
|
+Glob searching, by its very nature, is susceptible to race conditions,
|
|
|
+since it relies on directory walking and such.
|
|
|
+
|
|
|
+As a result, it is possible that a file that exists when glob looks for
|
|
|
+it may have been deleted or modified by the time it returns the result.
|
|
|
+
|
|
|
+As part of its internal implementation, this program caches all stat
|
|
|
+and readdir calls that it makes, in order to cut down on system
|
|
|
+overhead. However, this also makes it even more susceptible to races,
|
|
|
+especially if the cache or statCache objects are reused between glob
|
|
|
+calls.
|
|
|
+
|
|
|
+Users are thus advised not to use a glob result as a guarantee of
|
|
|
+filesystem state in the face of rapid changes. For the vast majority
|
|
|
+of operations, this is never a problem.
|
|
|
+
|
|
|
+## Contributing
|
|
|
+
|
|
|
+Any change to behavior (including bugfixes) must come with a test.
|
|
|
+
|
|
|
+Patches that fail tests or reduce performance will be rejected.
|
|
|
+
|
|
|
+```
|
|
|
+# to run tests
|
|
|
+npm test
|
|
|
+
|
|
|
+# to re-generate test fixtures
|
|
|
+npm run test-regen
|
|
|
+
|
|
|
+# to benchmark against bash/zsh
|
|
|
+npm run bench
|
|
|
+
|
|
|
+# to profile javascript
|
|
|
+npm run prof
|
|
|
+```
|