website/node_modules/glob/README.md

Glob

Match files using the patterns the shell uses, like stars and stuff.

Build Status Build Status Coverage Status

This is a glob implementation in JavaScript. It uses the minimatch library to do its matching.

Usage

Install with npm

npm i glob
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:

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.

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:

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)

Perform an asynchronous glob search.

glob.sync(pattern, [options])

Perform a synchronous glob search.

Class: glob.Glob

Create a Glob object by instantiating the glob.Glob class.

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])

Note that if the sync flag is set in the options, then matches will be immediately available on the g.found member.

Properties

Events

Methods

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, realpathCache, and cache options, so that parallel glob operations will be sped up by sharing information about the filesystem.

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.

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.

Comments and Negation

Previously, this module let you mark a pattern as a "comment" if it started with a # character, or a "negated" pattern if it started with a ! character.

These options were deprecated in version 5, and removed in version 6.

To specify things that should not match, use the ignore option.

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


JohnCoene/chirp documentation built on May 25, 2021, 6:33 p.m.