.config/coc/extensions/node_modules/coc-prettier/node_modules/fast-glob/README.md

   1 # :rocket: fast-glob
   2
   3 > Is a faster [`node-glob`](https://github.com/isaacs/node-glob) alternative.
   4
   5 ## :bulb: Highlights
   6
   7   * :rocket: Fast by using Streams and Promises. Used [readdir-enhanced](https://github.com/BigstickCarpet/readdir-enhanced) and [micromatch](https://github.com/jonschlinkert/micromatch).
   8   * :beginner: User-friendly, since it supports multiple and negated patterns (`['*', '!*.md']`).
   9   * :vertical_traffic_light: Rational, because it doesn't read excluded directories (`!**/node_modules/**`).
  10   * :gear: Universal, because it supports Synchronous, Promise and Stream API.
  11   * :money_with_wings: Economy, because it provides `fs.Stats` for matched path if you wanted.
  12
  13 ## Donate
  14
  15 If you want to thank me, or promote your Issue.
  16
  17 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://paypal.me/mrmlnc)
  18
  19 > Sorry, but I have work and support for packages requires some time after work. I will be glad of your support and PR's.
  20
  21 ## Install
  22
  23 ```
  24 $ npm install --save fast-glob
  25 ```
  26
  27 ## Usage
  28
  29 #### Asynchronous
  30
  31 ```js
  32 const fg = require('fast-glob');
  33
  34 fg(['src/**/*.js', '!src/**/*.spec.js']).then((entries) => console.log(entries));
  35 fg.async(['src/**/*.js', '!src/**/*.spec.js']).then((entries) => console.log(entries));
  36 ```
  37
  38 #### Synchronous
  39
  40 ```js
  41 const fg = require('fast-glob');
  42
  43 const entries = fg.sync(['src/**/*.js', '!src/**/*.spec.js']);
  44 console.log(entries);
  45 ```
  46
  47 #### Stream
  48
  49 ```js
  50 const fg = require('fast-glob');
  51
  52 const stream = fg.stream(['src/**/*.js', '!src/**/*.spec.js']);
  53
  54 const entries = [];
  55
  56 stream.on('data', (entry) => entries.push(entry));
  57 stream.once('error', console.log);
  58 stream.once('end', () => console.log(entries));
  59 ```
  60
  61 ## API
  62
  63 ### fg(patterns, [options])
  64 ### fg.async(patterns, [options])
  65
  66 Returns a `Promise` with an array of matching [entries](#entry).
  67
  68 ### fg.sync(patterns, [options])
  69
  70 Returns an array of matching [entries](#entry).
  71
  72 ### fg.stream(patterns, [options])
  73
  74 Returns a [`ReadableStream`](https://nodejs.org/api/stream.html#stream_readable_streams) when the `data` event will be emitted with [`Entry`](#entry).
  75
  76 #### patterns
  77
  78   * Type: `string|string[]`
  79
  80 This package does not respect the order of patterns. First, all the negative patterns are applied, and only then the positive patterns.
  81
  82 #### options
  83
  84   * Type: `Object`
  85
  86 See [options](#options-1) section for more detailed information.
  87
  88 ### fg.generateTasks(patterns, [options])
  89
  90 Return a set of tasks based on provided patterns. All tasks satisfy the `Task` interface:
  91
  92 ```ts
  93 interface Task {
  94   /**
  95    * Parent directory for all patterns inside this task.
  96    */
  97   base: string;
  98   /**
  99    * Dynamic or static patterns are in this task.
 100    */
 101   dynamic: boolean;
 102   /**
 103    * All patterns.
 104    */
 105   patterns: string[];
 106   /**
 107    * Only positive patterns.
 108    */
 109   positive: string[];
 110   /**
 111    * Only negative patterns without ! symbol.
 112    */
 113   negative: string[];
 114 }
 115 ```
 116
 117 ## Entry
 118
 119 The entry which can be a `string` if the [`stats`](#stats) option is disabled, otherwise `fs.Stats` with two additional `path` and `depth` properties.
 120
 121 ## Options
 122
 123 #### cwd
 124
 125   * Type: `string`
 126   * Default: `process.cwd()`
 127
 128 The current working directory in which to search.
 129
 130 #### deep
 131
 132   * Type: `number|boolean`
 133   * Default: `true`
 134
 135 The deep option can be set to `true` to traverse the entire directory structure, or it can be set to a *number* to only traverse that many levels deep.
 136
 137 For example, you have the following tree:
 138
 139 ```
 140 test
 141 └── one
 142     └── two
 143         └── index.js
 144 ```
 145
 146 > :book: If you specify a pattern with some base directory, this directory will not participate in the calculation of the depth of the found directories. Think of it as a `cwd` option.
 147
 148 ```js
 149 fg('test/**', { onlyFiles: false, deep: 0 });
 150 // -> ['test/one']
 151 fg('test/**', { onlyFiles: false, deep: 1 });
 152 // -> ['test/one', 'test/one/two']
 153
 154 fg('**', { onlyFiles: false, cwd: 'test', deep: 0 });
 155 // -> ['one']
 156 fg('**', { onlyFiles: false, cwd: 'test', deep: 1 });
 157 // -> ['one', 'one/two']
 158 ```
 159
 160 #### ignore
 161
 162   * Type: `string[]`
 163   * Default: `[]`
 164
 165 An array of glob patterns to exclude matches.
 166
 167 #### dot
 168
 169   * Type: `boolean`
 170   * Default: `false`
 171
 172 Allow patterns to match filenames starting with a period (files & directories), even if the pattern does not explicitly have a period in that spot.
 173
 174 #### stats
 175
 176   * Type: `boolean`
 177   * Default: `false`
 178
 179 Return `fs.Stats` with two additional `path` and `depth` properties instead of a `string`.
 180
 181 #### onlyFiles
 182
 183   * Type: `boolean`
 184   * Default: `true`
 185
 186 Return only files.
 187
 188 #### onlyDirectories
 189
 190   * Type: `boolean`
 191   * Default: `false`
 192
 193 Return only directories.
 194
 195 #### followSymlinkedDirectories
 196
 197   * Type: `boolean`
 198   * Default: `true`
 199
 200 Follow symlinked directories when expanding `**` patterns.
 201
 202 #### unique
 203
 204   * Type: `boolean`
 205   * Default: `true`
 206
 207 Prevent duplicate results.
 208
 209 #### markDirectories
 210
 211   * Type: `boolean`
 212   * Default: `false`
 213
 214 Add a `/` character to directory entries.
 215
 216 #### absolute
 217
 218   * Type: `boolean`
 219   * Default: `false`
 220
 221 Return absolute paths for matched entries.
 222
 223 > :book: Note that you need to use this option if you want to use absolute negative patterns like `${__dirname}/*.md`.
 224
 225 #### nobrace
 226
 227   * Type: `boolean`
 228   * Default: `false`
 229
 230 Disable expansion of brace patterns (`{a,b}`, `{1..3}`).
 231
 232 #### brace
 233
 234   * Type: `boolean`
 235   * Default: `true`
 236
 237 The [`nobrace`](#nobrace) option without double-negation. This option has a higher priority then `nobrace`.
 238
 239 #### noglobstar
 240
 241   * Type: `boolean`
 242   * Default: `false`
 243
 244 Disable matching with globstars (`**`).
 245
 246 #### globstar
 247
 248   * Type: `boolean`
 249   * Default: `true`
 250
 251 The [`noglobstar`](#noglobstar) option without double-negation. This option has a higher priority then `noglobstar`.
 252
 253 #### noext
 254
 255   * Type: `boolean`
 256   * Default: `false`
 257
 258 Disable extglob support (patterns like `+(a|b)`), so that extglobs are regarded as literal characters.
 259
 260 #### extension
 261
 262   * Type: `boolean`
 263   * Default: `true`
 264
 265 The [`noext`](#noext) option without double-negation. This option has a higher priority then `noext`.
 266
 267 #### nocase
 268
 269   * Type: `boolean`
 270   * Default: `false`
 271
 272 Disable a [case-sensitive](https://en.wikipedia.org/wiki/Case_sensitivity) mode for matching files.
 273
 274 ##### Examples
 275
 276 * File System: `test/file.md`, `test/File.md`
 277 * Case-sensitive for `test/file.*` pattern (`false`): `test/file.md`
 278 * Case-insensitive for `test/file.*` pattern (`true`): `test/file.md`, `test/File.md`
 279
 280 #### case
 281
 282   * Type: `boolean`
 283   * Default: `true`
 284
 285 The [`nocase`](#nocase) option without double-negation. This option has a higher priority then `nocase`.
 286
 287 #### matchBase
 288
 289   * Type: `boolean`
 290   * Default: `false`
 291
 292 Allow glob patterns without slashes to match a file path based on its basename. For example, `a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`.
 293
 294 #### transform
 295
 296   * Type: `Function`
 297   * Default: `null`
 298
 299 Allows you to transform a path or `fs.Stats` object before sending to the array.
 300
 301 ```js
 302 const fg = require('fast-glob');
 303
 304 const entries1 = fg.sync(['**/*.scss']);
 305 const entries2 = fg.sync(['**/*.scss'], { transform: (entry) => '_' + entry });
 306
 307 console.log(entries1); // ['a.scss', 'b.scss']
 308 console.log(entries2); // ['_a.scss', '_b.scss']
 309 ```
 310
 311 If you are using **TypeScript**, you probably want to specify your own type of the returned array.
 312
 313 ```ts
 314 import * as fg from 'fast-glob';
 315
 316 interface IMyOwnEntry {
 317         path: string;
 318 }
 319
 320 const entries: IMyOwnEntry[] = fg.sync<IMyOwnEntry>(['*.md'], {
 321         transform: (entry) => typeof entry === 'string' ? { path: entry } : { path: entry.path }
 322         // Will throw compilation error for non-IMyOwnEntry types (boolean, for example)
 323 });
 324 ```
 325
 326 ## How to exclude directory from reading?
 327
 328 You can use a negative pattern like this: `!**/node_modules` or `!**/node_modules/**`. Also you can use `ignore` option. Just look at the example below.
 329
 330 ```
 331 first/
 332 ├── file.md
 333 └── second
 334     └── file.txt
 335 ```
 336
 337 If you don't want to read the `second` directory, you must write the following pattern: `!**/second` or `!**/second/**`.
 338
 339 ```js
 340 fg.sync(['**/*.md', '!**/second']); // ['first/file.txt']
 341 fg.sync(['**/*.md'], { ignore: '**/second/**' }); // ['first/file.txt']
 342 ```
 343
 344 > :warning: When you write `!**/second/**/*` it means that the directory will be **read**, but all the entries will not be included in the results.
 345
 346 You have to understand that if you write the pattern to exclude directories, then the directory will not be read under any circumstances.
 347
 348 ## How to use UNC path?
 349
 350 You cannot use UNC paths as patterns (due to syntax), but you can use them as `cwd` directory.
 351
 352 ```ts
 353 fg.sync('*', { cwd: '\\\\?\\C:\\Python27' /* or //?/C:/Python27 */ });
 354 fg.sync('Python27/*', { cwd: '\\\\?\\C:\\' /* or //?/C:/ */ });
 355 ```
 356
 357 ## Compatible with `node-glob`?
 358
 359 Not fully, because `fast-glob` does not implement all options of `node-glob`. See table below.
 360
 361 | node-glob    | fast-glob |
 362 | :----------: | :-------: |
 363 | `cwd`        | [`cwd`](#cwd) |
 364 | `root`       | – |
 365 | `dot`        | [`dot`](#dot) |
 366 | `nomount`    | – |
 367 | `mark`       | [`markDirectories`](#markdirectories) |
 368 | `nosort`     | – |
 369 | `nounique`   | [`unique`](#unique) |
 370 | `nobrace`    | [`nobrace`](#nobrace) or [`brace`](#brace) |
 371 | `noglobstar` | [`noglobstar`](#noglobstar) or [`globstar`](#globstar) |
 372 | `noext`      | [`noext`](#noext) or [`extension`](#extension) |
 373 | `nocase`     | [`nocase`](#nocase) or [`case`](#case) |
 374 | `matchBase`  | [`matchbase`](#matchbase) |
 375 | `nodir`      | [`onlyFiles`](#onlyfiles) |
 376 | `ignore`     | [`ignore`](#ignore) |
 377 | `follow`     | [`followSymlinkedDirectories`](#followsymlinkeddirectories) |
 378 | `realpath`   | – |
 379 | `absolute`   | [`absolute`](#absolute) |
 380
 381 ## Benchmarks
 382
 383 **Tech specs:**
 384
 385 Server: [Vultr Bare Metal](https://www.vultr.com/pricing/baremetal)
 386
 387   * Processor: E3-1270v6 (8 CPU)
 388   * RAM: 32GB
 389   * Disk: SSD
 390
 391 You can see results [here](https://gist.github.com/mrmlnc/f06246b197f53c356895fa35355a367c) for latest release.
 392
 393 ## Related
 394
 395   * [readdir-enhanced](https://github.com/BigstickCarpet/readdir-enhanced) – Fast functional replacement for `fs.readdir()`.
 396   * [globby](https://github.com/sindresorhus/globby) – User-friendly glob matching.
 397   * [node-glob](https://github.com/isaacs/node-glob) – «Standard» glob functionality for Node.js
 398   * [bash-glob](https://github.com/micromatch/bash-glob) – Bash-powered globbing for node.js.
 399   * [glob-stream](https://github.com/gulpjs/glob-stream) – A Readable Stream interface over node-glob that used in the [gulpjs](https://github.com/gulpjs/gulp).
 400   * [tiny-glob](https://github.com/terkelg/tiny-glob) – Tiny and extremely fast library to match files and folders using glob patterns.
 401
 402 ## Changelog
 403
 404 See the [Releases section of our GitHub project](https://github.com/mrmlnc/fast-glob/releases) for changelogs for each release version.
 405
 406 ## License
 407
 408 This software is released under the terms of the MIT license.