www.aleph1.co.uk Git - yaffs-website/blob - node_modules/globule/node_modules/glob/README.md

   1 # Glob
   2
   3 This is a glob implementation in JavaScript.  It uses the `minimatch`
   4 library to do its matching.
   5
   6 ## Attention: node-glob users!
   7
   8 The API has changed dramatically between 2.x and 3.x. This library is
   9 now 100% JavaScript, and the integer flags have been replaced with an
  10 options object.
  11
  12 Also, there's an event emitter class, proper tests, and all the other
  13 things you've come to expect from node modules.
  14
  15 And best of all, no compilation!
  16
  17 ## Usage
  18
  19 ```javascript
  20 var glob = require("glob")
  21
  22 // options is optional
  23 glob("**/*.js", options, function (er, files) {
  24   // files is an array of filenames.
  25   // If the `nonull` option is set, and nothing
  26   // was found, then files is ["**/*.js"]
  27   // er is an error object or null.
  28 })
  29 ```
  30
  31 ## Features
  32
  33 Please see the [minimatch
  34 documentation](https://github.com/isaacs/minimatch) for more details.
  35
  36 Supports these glob features:
  37
  38 * Brace Expansion
  39 * Extended glob matching
  40 * "Globstar" `**` matching
  41
  42 See:
  43
  44 * `man sh`
  45 * `man bash`
  46 * `man 3 fnmatch`
  47 * `man 5 gitignore`
  48 * [minimatch documentation](https://github.com/isaacs/minimatch)
  49
  50 ## glob(pattern, [options], cb)
  51
  52 * `pattern` {String} Pattern to be matched
  53 * `options` {Object}
  54 * `cb` {Function}
  55   * `err` {Error | null}
  56   * `matches` {Array<String>} filenames found matching the pattern
  57
  58 Perform an asynchronous glob search.
  59
  60 ## glob.sync(pattern, [options]
  61
  62 * `pattern` {String} Pattern to be matched
  63 * `options` {Object}
  64 * return: {Array<String>} filenames found matching the pattern
  65
  66 Perform a synchronous glob search.
  67
  68 ## Class: glob.Glob
  69
  70 Create a Glob object by instanting the `glob.Glob` class.
  71
  72 ```javascript
  73 var Glob = require("glob").Glob
  74 var mg = new Glob(pattern, options, cb)
  75 ```
  76
  77 It's an EventEmitter, and starts walking the filesystem to find matches
  78 immediately.
  79
  80 ### new glob.Glob(pattern, [options], [cb])
  81
  82 * `pattern` {String} pattern to search for
  83 * `options` {Object}
  84 * `cb` {Function} Called when an error occurs, or matches are found
  85   * `err` {Error | null}
  86   * `matches` {Array<String>} filenames found matching the pattern
  87
  88 Note that if the `sync` flag is set in the options, then matches will
  89 be immediately available on the `g.found` member.
  90
  91 ### Properties
  92
  93 * `minimatch` The minimatch object that the glob uses.
  94 * `options` The options object passed in.
  95 * `error` The error encountered.  When an error is encountered, the
  96   glob object is in an undefined state, and should be discarded.
  97 * `aborted` Boolean which is set to true when calling `abort()`.  There
  98   is no way at this time to continue a glob search after aborting, but
  99   you can re-use the statCache to avoid having to duplicate syscalls.
 100
 101 ### Events
 102
 103 * `end` When the matching is finished, this is emitted with all the
 104   matches found.  If the `nonull` option is set, and no match was found,
 105   then the `matches` list contains the original pattern.  The matches
 106   are sorted, unless the `nosort` flag is set.
 107 * `match` Every time a match is found, this is emitted with the matched.
 108 * `error` Emitted when an unexpected error is encountered, or whenever
 109   any fs error occurs if `options.strict` is set.
 110 * `abort` When `abort()` is called, this event is raised.
 111
 112 ### Methods
 113
 114 * `abort` Stop the search.
 115
 116 ### Options
 117
 118 All the options that can be passed to Minimatch can also be passed to
 119 Glob to change pattern matching behavior.  Also, some have been added,
 120 or have glob-specific ramifications.
 121
 122 All options are false by default, unless otherwise noted.
 123
 124 All options are added to the glob object, as well.
 125
 126 * `cwd` The current working directory in which to search.  Defaults
 127   to `process.cwd()`.
 128 * `root` The place where patterns starting with `/` will be mounted
 129   onto.  Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix
 130   systems, and `C:\` or some such on Windows.)
 131 * `nomount` By default, a pattern starting with a forward-slash will be
 132   "mounted" onto the root setting, so that a valid filesystem path is
 133   returned.  Set this flag to disable that behavior.
 134 * `mark` Add a `/` character to directory matches.  Note that this
 135   requires additional stat calls.
 136 * `nosort` Don't sort the results.
 137 * `stat` Set to true to stat *all* results.  This reduces performance
 138   somewhat, and is completely unnecessary, unless `readdir` is presumed
 139   to be an untrustworthy indicator of file existence.  It will cause
 140   ELOOP to be triggered one level sooner in the case of cyclical
 141   symbolic links.
 142 * `silent` When an unusual error is encountered
 143   when attempting to read a directory, a warning will be printed to
 144   stderr.  Set the `silent` option to true to suppress these warnings.
 145 * `strict` When an unusual error is encountered
 146   when attempting to read a directory, the process will just continue on
 147   in search of other matches.  Set the `strict` option to raise an error
 148   in these cases.
 149 * `statCache` A cache of results of filesystem information, to prevent
 150   unnecessary stat calls.  While it should not normally be necessary to
 151   set this, you may pass the statCache from one glob() call to the
 152   options object of another, if you know that the filesystem will not
 153   change between calls.  (See "Race Conditions" below.)
 154 * `sync` Perform a synchronous glob search.
 155 * `nounique` In some cases, brace-expanded patterns can result in the
 156   same file showing up multiple times in the result set.  By default,
 157   this implementation prevents duplicates in the result set.
 158   Set this flag to disable that behavior.
 159 * `nonull` Set to never return an empty set, instead returning a set
 160   containing the pattern itself.  This is the default in glob(3).
 161 * `nocase` Perform a case-insensitive match.  Note that case-insensitive
 162   filesystems will sometimes result in glob returning results that are
 163   case-insensitively matched anyway, since readdir and stat will not
 164   raise an error.
 165 * `debug` Set to enable debug logging in minimatch and glob.
 166 * `globDebug` Set to enable debug logging in glob, but not minimatch.
 167
 168 ## Comparisons to other fnmatch/glob implementations
 169
 170 While strict compliance with the existing standards is a worthwhile
 171 goal, some discrepancies exist between node-glob and other
 172 implementations, and are intentional.
 173
 174 If the pattern starts with a `!` character, then it is negated.  Set the
 175 `nonegate` flag to suppress this behavior, and treat leading `!`
 176 characters normally.  This is perhaps relevant if you wish to start the
 177 pattern with a negative extglob pattern like `!(a|B)`.  Multiple `!`
 178 characters at the start of a pattern will negate the pattern multiple
 179 times.
 180
 181 If a pattern starts with `#`, then it is treated as a comment, and
 182 will not match anything.  Use `\#` to match a literal `#` at the
 183 start of a line, or set the `nocomment` flag to suppress this behavior.
 184
 185 The double-star character `**` is supported by default, unless the
 186 `noglobstar` flag is set.  This is supported in the manner of bsdglob
 187 and bash 4.1, where `**` only has special significance if it is the only
 188 thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
 189 `a/**b` will not.  **Note that this is different from the way that `**` is
 190 handled by ruby's `Dir` class.**
 191
 192 If an escaped pattern has no matches, and the `nonull` flag is set,
 193 then glob returns the pattern as-provided, rather than
 194 interpreting the character escapes.  For example,
 195 `glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
 196 `"*a?"`.  This is akin to setting the `nullglob` option in bash, except
 197 that it does not resolve escaped pattern characters.
 198
 199 If brace expansion is not disabled, then it is performed before any
 200 other interpretation of the glob pattern.  Thus, a pattern like
 201 `+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
 202 **first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
 203 checked for validity.  Since those two are valid, matching proceeds.
 204
 205 ## Windows
 206
 207 **Please only use forward-slashes in glob expressions.**
 208
 209 Though windows uses either `/` or `\` as its path separator, only `/`
 210 characters are used by this glob implementation.  You must use
 211 forward-slashes **only** in glob expressions.  Back-slashes will always
 212 be interpreted as escape characters, not path separators.
 213
 214 Results from absolute patterns such as `/foo/*` are mounted onto the
 215 root setting using `path.join`.  On windows, this will by default result
 216 in `/foo/*` matching `C:\foo\bar.txt`.
 217
 218 ## Race Conditions
 219
 220 Glob searching, by its very nature, is susceptible to race conditions,
 221 since it relies on directory walking and such.
 222
 223 As a result, it is possible that a file that exists when glob looks for
 224 it may have been deleted or modified by the time it returns the result.
 225
 226 As part of its internal implementation, this program caches all stat
 227 and readdir calls that it makes, in order to cut down on system
 228 overhead.  However, this also makes it even more susceptible to races,
 229 especially if the statCache object is reused between glob calls.
 230
 231 Users are thus advised not to use a glob result as a
 232 guarantee of filesystem state in the face of rapid changes.
 233 For the vast majority of operations, this is never a problem.