|
||
---|---|---|
.. | ||
LICENSE | ||
README.md | ||
common.js | ||
glob.js | ||
package.json | ||
sync.js |
README.md
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
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 is deprecated in version 5, and will be removed
entirely in version 6.
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
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 matchedoptions
{Object}cb
{Function}err
{Error | null}matches
{Array} filenames found matching the pattern
Perform an asynchronous glob search.
glob.sync(pattern, [options])
pattern
{String} Pattern to be matchedoptions
{Object}- return: {Array} filenames found matching the pattern
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])
pattern
{String} pattern to search foroptions
{Object}cb
{Function} Called when an error occurs, or matches are founderr
{Error | null}matches
{Array} 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 callingabort()
. 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.cache
Convenience object. Each field has the following possible values:false
- Path does not existtrue
- 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 offs.readdir
statCache
Cache offs.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.realpathCache
An optional object which is passed tofs.realpath
to minimize unnecessary syscalls. It is stored on the instantiated Glob object, and may be re-used.
Events
end
When the matching is finished, this is emitted with all the matches found. If thenonull
option is set, and no match was found, then thematches
list contains the original pattern. The matches are sorted, unless thenosort
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 ifoptions.strict
is set.abort
Whenabort()
is called, this event is raised.
Methods
pause
Temporarily stop the searchresume
Resume the searchabort
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
, realpathCache
, 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 toprocess.cwd()
.root
The place where patterns starting with/
will be mounted onto. Defaults topath.resolve(options.cwd, "/")
(/
on Unix systems, andC:\
or some such on Windows.)dot
Include.dot
files in normal matches andglobstar
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, unlessreaddir
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 thesilent
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 thestrict
option to raise an error in these cases.cache
Seecache
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 generatedsymlinks
object to savelstat
calls when resolving**
matches.sync
DEPRECATED: useglob.sync(pattern, opts)
instead.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, sincestat
andreaddir
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.nodir
Do not match directories, only files. (Note: to match only directories, simply put a/
at the end of the pattern.)ignore
Add a pattern or an array of patterns to exclude matches.follow
Follow symlinked directories when expanding**
patterns. Note that this can result in a lot of duplicate references in the presence of cyclic links.realpath
Set to true to callfs.realpath
on all of the results. In the case of a symlink that cannot be resolved, the full absolute path to the matched entry is returned (though it will usually be a broken symlink)nonegate
Suppress deprecatednegate
behavior. (See below.) Default=truenocomment
Suppress deprecatedcomment
behavior. (See below.) Default=true
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
Note: In version 5 of this module, negation and comments are
disabled by default. You can explicitly set nonegate:false
or
nocomment:false
to re-enable them. They are going away entirely in
version 6.
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. It is better to use the ignore
option
to set a pattern or set of patterns to exclude from matches. If you
want the "everything except x" type of behavior, you can use **
as
the main pattern, and set an ignore
for the things to exclude.
The comments feature is added in minimatch, primarily to more easily
support use cases like ignore files, where a #
at the start of a
line makes the pattern "empty". However, in the context of a
straightforward filesystem globber, "comments" don't make much sense.
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