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

\href{https://travis-ci.org/isaacs/node-glob/}{\texttt{ }} \href{https://ci.appveyor.com/project/isaacs/node-glob}{\texttt{ }} \href{https://coveralls.io/github/isaacs/node-glob?branch=master}{\texttt{ }}

This is a glob implementation in Java\+Script. It uses the {\ttfamily minimatch} library to do its matching.

\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11345}{}\doxysection{Usage}\label{md_sfcode_node_modules_glob_README_autotoc_md11345}
Install with npm


\begin{DoxyCode}{0}
\DoxyCodeLine{npm i glob }

\end{DoxyCode}



\begin{DoxyCode}{0}
\DoxyCodeLine{var glob = require("{}glob"{})}
\DoxyCodeLine{}
\DoxyCodeLine{// options is optional}
\DoxyCodeLine{glob("{}**/*.js"{}, options, function (er, files) \{}
\DoxyCodeLine{  // files is an array of filenames.}
\DoxyCodeLine{  // If the `nonull` option is set, and nothing}
\DoxyCodeLine{  // was found, then files is ["{}**/*.js"{}]}
\DoxyCodeLine{  // er is an error object or null.}
\DoxyCodeLine{\}) }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11346}{}\doxysection{Glob Primer}\label{md_sfcode_node_modules_glob_README_autotoc_md11346}
\char`\"{}\+Globs\char`\"{} are the patterns you type when you do stuff like {\ttfamily ls $\ast$.js} on the command line, or put {\ttfamily build/$\ast$} in a {\ttfamily .gitignore} file.

Before parsing the path part patterns, braced sections are expanded into a set. Braced sections start with {\ttfamily \{} and end with {\ttfamily \}}, with any number of comma-\/delimited sections within. Braced sections may contain slash characters, so {\ttfamily a\{/b/c,bcd\}} would expand into {\ttfamily a/b/c} and {\ttfamily abcd}.

The following characters have special magic meaning when used in a path portion\+:


\begin{DoxyItemize}
\item {\ttfamily $\ast$} Matches 0 or more characters in a single path portion
\item {\ttfamily ?} Matches 1 character
\item {\ttfamily \mbox{[}...\mbox{]}} Matches a range of characters, similar to a Reg\+Exp range. If the first character of the range is {\ttfamily !} or {\ttfamily $^\wedge$} then it matches any character not in the range.
\item {\ttfamily !(pattern$\vert$pattern$\vert$pattern)} Matches anything that does not match any of the patterns provided.
\item {\ttfamily ?(pattern$\vert$pattern$\vert$pattern)} Matches zero or one occurrence of the patterns provided.
\item {\ttfamily +(pattern$\vert$pattern$\vert$pattern)} Matches one or more occurrences of the patterns provided.
\item {\ttfamily $\ast$(a$\vert$b$\vert$c)} Matches zero or more occurrences of the patterns provided
\item {\ttfamily @(pattern$\vert$pat$\ast$$\vert$pat?erN)} Matches exactly one of the patterns provided
\item {\ttfamily $\ast$$\ast$} If a \char`\"{}globstar\char`\"{} is alone in a path portion, then it matches zero or more directories and subdirectories searching for matches. It does not crawl symlinked directories.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11347}{}\doxysubsection{Dots}\label{md_sfcode_node_modules_glob_README_autotoc_md11347}
If a file or directory path portion has a {\ttfamily .} as the first character, then it will not match any glob pattern unless that pattern\textquotesingle{}s corresponding path part also has a {\ttfamily .} as its first character.

For example, the pattern {\ttfamily a/.$\ast$/c} would match the file at {\ttfamily a/.b/c}. However the pattern {\ttfamily a/$\ast$/c} would not, because {\ttfamily $\ast$} does not start with a dot character.

You can make glob treat dots as normal characters by setting {\ttfamily dot\+:true} in the options.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11348}{}\doxysubsection{Basename Matching}\label{md_sfcode_node_modules_glob_README_autotoc_md11348}
If you set {\ttfamily match\+Base\+: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, {\ttfamily $\ast$.js} would match {\ttfamily test/simple/basic.\+js}.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11349}{}\doxysubsection{Empty Sets}\label{md_sfcode_node_modules_glob_README_autotoc_md11349}
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\+: \begin{DoxyVerb}$ echo a*s*d*f
a*s*d*f
\end{DoxyVerb}
 To get the bash-\/style behavior, set the {\ttfamily nonull\+:true} in the options.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11350}{}\doxysubsection{See Also\+:}\label{md_sfcode_node_modules_glob_README_autotoc_md11350}

\begin{DoxyItemize}
\item {\ttfamily man sh}
\item {\ttfamily man bash} (Search for \char`\"{}\+Pattern Matching\char`\"{})
\item {\ttfamily man 3 fnmatch}
\item {\ttfamily man 5 gitignore}
\item \href{https://github.com/isaacs/minimatch}{\texttt{ minimatch documentation}}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11351}{}\doxysection{glob.\+has\+Magic(pattern, \mbox{[}options\mbox{]})}\label{md_sfcode_node_modules_glob_README_autotoc_md11351}
Returns {\ttfamily true} if there are any special characters in the pattern, and {\ttfamily false} otherwise.

Note that the options affect the results. If {\ttfamily noext\+:true} is set in the options object, then {\ttfamily +(a$\vert$b)} will not be considered a magic pattern. If the pattern has a brace expansion, like {\ttfamily a/\{b/c,x/y\}} then that is considered magical, unless {\ttfamily nobrace\+:true} is set in the options.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11352}{}\doxysection{glob(pattern, \mbox{[}options\mbox{]}, cb)}\label{md_sfcode_node_modules_glob_README_autotoc_md11352}

\begin{DoxyItemize}
\item {\ttfamily pattern} {\ttfamily \{String\}} Pattern to be matched
\item {\ttfamily options} {\ttfamily \{Object\}}
\item {\ttfamily cb} {\ttfamily \{Function\}}
\begin{DoxyItemize}
\item {\ttfamily err} {\ttfamily \{Error $\vert$ null\}}
\item {\ttfamily matches} {\ttfamily \{Array$<$String$>$\}} filenames found matching the pattern
\end{DoxyItemize}
\end{DoxyItemize}

Perform an asynchronous glob search.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11353}{}\doxysection{glob.\+sync(pattern, \mbox{[}options\mbox{]})}\label{md_sfcode_node_modules_glob_README_autotoc_md11353}

\begin{DoxyItemize}
\item {\ttfamily pattern} {\ttfamily \{String\}} Pattern to be matched
\item {\ttfamily options} {\ttfamily \{Object\}}
\item return\+: {\ttfamily \{Array$<$String$>$\}} filenames found matching the pattern
\end{DoxyItemize}

Perform a synchronous glob search.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11354}{}\doxysection{Class\+: glob.\+Glob}\label{md_sfcode_node_modules_glob_README_autotoc_md11354}
Create a Glob object by instantiating the {\ttfamily glob.\+Glob} class.


\begin{DoxyCode}{0}
\DoxyCodeLine{var Glob = require("{}glob"{}).Glob}
\DoxyCodeLine{var mg = new Glob(pattern, options, cb) }

\end{DoxyCode}


It\textquotesingle{}s an Event\+Emitter, and starts walking the filesystem to find matches immediately.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11355}{}\doxysubsection{new glob.\+Glob(pattern, \mbox{[}options\mbox{]}, \mbox{[}cb\mbox{]})}\label{md_sfcode_node_modules_glob_README_autotoc_md11355}

\begin{DoxyItemize}
\item {\ttfamily pattern} {\ttfamily \{String\}} pattern to search for
\item {\ttfamily options} {\ttfamily \{Object\}}
\item {\ttfamily cb} {\ttfamily \{Function\}} Called when an error occurs, or matches are found
\begin{DoxyItemize}
\item {\ttfamily err} {\ttfamily \{Error $\vert$ null\}}
\item {\ttfamily matches} {\ttfamily \{Array$<$String$>$\}} filenames found matching the pattern
\end{DoxyItemize}
\end{DoxyItemize}

Note that if the {\ttfamily sync} flag is set in the options, then matches will be immediately available on the {\ttfamily g.\+found} member.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11356}{}\doxysubsection{Properties}\label{md_sfcode_node_modules_glob_README_autotoc_md11356}

\begin{DoxyItemize}
\item {\ttfamily minimatch} The minimatch object that the glob uses.
\item {\ttfamily options} The options object passed in.
\item {\ttfamily aborted} Boolean which is set to true when calling {\ttfamily abort()}. There is no way at this time to continue a glob search after aborting, but you can re-\/use the stat\+Cache to avoid having to duplicate syscalls.
\item {\ttfamily cache} Convenience object. Each field has the following possible values\+:
\begin{DoxyItemize}
\item {\ttfamily false} -\/ Path does not exist
\item {\ttfamily true} -\/ Path exists
\item `\textquotesingle{}FILE'{\ttfamily -\/ Path exists, and is not a directory $\ast$}\textquotesingle{}DIR\textquotesingle{}{\ttfamily -\/ Path exists, and is a directory $\ast$}\mbox{[}file, entries, ...\mbox{]}{\ttfamily -\/ Path exists, is a directory, and the array value is the results of}fs.\+readdir$<$tt$>$ $\ast$stat\+Cache{\ttfamily Cache of}fs.\+stat\`{} results, to prevent statting the same path multiple times.
\end{DoxyItemize}
\item {\ttfamily symlinks} A record of which paths are symbolic links, which is relevant in resolving {\ttfamily $\ast$$\ast$} patterns.
\item {\ttfamily realpath\+Cache} An optional object which is passed to {\ttfamily fs.\+realpath} to minimize unnecessary syscalls. It is stored on the instantiated Glob object, and may be re-\/used.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11357}{}\doxysubsection{Events}\label{md_sfcode_node_modules_glob_README_autotoc_md11357}

\begin{DoxyItemize}
\item {\ttfamily end} When the matching is finished, this is emitted with all the matches found. If the {\ttfamily nonull} option is set, and no match was found, then the {\ttfamily matches} list contains the original pattern. The matches are sorted, unless the {\ttfamily nosort} flag is set.
\item {\ttfamily match} Every time a match is found, this is emitted with the specific thing that matched. It is not deduplicated or resolved to a realpath.
\item {\ttfamily error} Emitted when an unexpected error is encountered, or whenever any fs error occurs if {\ttfamily options.\+strict} is set.
\item {\ttfamily abort} When {\ttfamily abort()} is called, this event is raised.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11358}{}\doxysubsection{Methods}\label{md_sfcode_node_modules_glob_README_autotoc_md11358}

\begin{DoxyItemize}
\item {\ttfamily pause} Temporarily stop the search
\item {\ttfamily resume} Resume the search
\item {\ttfamily abort} Stop the search forever
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11359}{}\doxysubsection{Options}\label{md_sfcode_node_modules_glob_README_autotoc_md11359}
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 {\ttfamily glob} operations, you can pass a Glob object as the {\ttfamily options} argument to a subsequent operation to shortcut some {\ttfamily stat} and {\ttfamily readdir} calls. At the very least, you may pass in shared {\ttfamily symlinks}, {\ttfamily stat\+Cache}, {\ttfamily realpath\+Cache}, and {\ttfamily cache} options, so that parallel glob operations will be sped up by sharing information about the filesystem.


\begin{DoxyItemize}
\item {\ttfamily cwd} The current working directory in which to search. Defaults to {\ttfamily process.\+cwd()}.
\item {\ttfamily root} The place where patterns starting with {\ttfamily /} will be mounted onto. Defaults to {\ttfamily path.\+resolve(options.\+cwd, \char`\"{}/\char`\"{})} ({\ttfamily /} on Unix systems, and {\ttfamily C\+:\textbackslash{}} or some such on Windows.)
\item {\ttfamily dot} Include {\ttfamily .dot} files in normal matches and {\ttfamily globstar} matches. Note that an explicit dot in a portion of the pattern will always match dot files.
\item {\ttfamily nomount} By default, a pattern starting with a forward-\/slash will be \char`\"{}mounted\char`\"{} onto the root setting, so that a valid filesystem path is returned. Set this flag to disable that behavior.
\item {\ttfamily mark} Add a {\ttfamily /} character to directory matches. Note that this requires additional stat calls.
\item {\ttfamily nosort} Don\textquotesingle{}t sort the results.
\item {\ttfamily stat} Set to true to stat {\itshape all} results. This reduces performance somewhat, and is completely unnecessary, unless {\ttfamily readdir} is presumed to be an untrustworthy indicator of file existence.
\item {\ttfamily silent} When an unusual error is encountered when attempting to read a directory, a warning will be printed to stderr. Set the {\ttfamily silent} option to true to suppress these warnings.
\item {\ttfamily 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 {\ttfamily strict} option to raise an error in these cases.
\item {\ttfamily cache} See {\ttfamily cache} property above. Pass in a previously generated cache object to save some fs calls.
\item {\ttfamily stat\+Cache} 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 stat\+Cache from one glob() call to the options object of another, if you know that the filesystem will not change between calls. (See \char`\"{}\+Race Conditions\char`\"{} below.)
\item {\ttfamily symlinks} A cache of known symbolic links. You may pass in a previously generated {\ttfamily symlinks} object to save {\ttfamily lstat} calls when resolving {\ttfamily $\ast$$\ast$} matches.
\item {\ttfamily sync} DEPRECATED\+: use {\ttfamily glob.\+sync(pattern, opts)} instead.
\item {\ttfamily 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.
\item {\ttfamily nonull} Set to never return an empty set, instead returning a set containing the pattern itself. This is the default in glob(3).
\item {\ttfamily debug} Set to enable debug logging in minimatch and glob.
\item {\ttfamily nobrace} Do not expand {\ttfamily \{a,b\}} and {\ttfamily \{1..3\}} brace sets.
\item {\ttfamily noglobstar} Do not match {\ttfamily $\ast$$\ast$} against multiple filenames. (Ie, treat it as a normal {\ttfamily $\ast$} instead.)
\item {\ttfamily noext} Do not match {\ttfamily +(a$\vert$b)} \char`\"{}extglob\char`\"{} patterns.
\item {\ttfamily nocase} Perform a case-\/insensitive match. Note\+: on case-\/insensitive filesystems, non-\/magic patterns will match by default, since {\ttfamily stat} and {\ttfamily readdir} will not raise errors.
\item {\ttfamily match\+Base} Perform a basename-\/only match if the pattern does not contain any slash characters. That is, {\ttfamily $\ast$.js} would be treated as equivalent to {\ttfamily $\ast$$\ast$/$\ast$.js}, matching all js files in all directories.
\item {\ttfamily nodir} Do not match directories, only files. (Note\+: to match {\itshape only} directories, simply put a {\ttfamily /} at the end of the pattern.)
\item {\ttfamily ignore} Add a pattern or an array of glob patterns to exclude matches. Note\+: {\ttfamily ignore} patterns are {\itshape always} in {\ttfamily dot\+:true} mode, regardless of any other settings.
\item {\ttfamily follow} Follow symlinked directories when expanding {\ttfamily $\ast$$\ast$} patterns. Note that this can result in a lot of duplicate references in the presence of cyclic links.
\item {\ttfamily realpath} Set to true to call {\ttfamily fs.\+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)
\item {\ttfamily absolute} Set to true to always receive absolute paths for matched files. Unlike {\ttfamily realpath}, this also affects the values returned in the {\ttfamily match} event.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11360}{}\doxysection{Comparisons to other fnmatch/glob implementations}\label{md_sfcode_node_modules_glob_README_autotoc_md11360}
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 {\ttfamily $\ast$$\ast$} is supported by default, unless the {\ttfamily noglobstar} flag is set. This is supported in the manner of bsdglob and bash 4.\+3, where {\ttfamily $\ast$$\ast$} only has special significance if it is the only thing in a path part. That is, {\ttfamily a/$\ast$$\ast$/b} will match {\ttfamily a/x/y/b}, but {\ttfamily a/$\ast$$\ast$b} will not.

Note that symlinked directories are not crawled as part of a {\ttfamily $\ast$$\ast$}, 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 {\ttfamily nonull} flag is set, then glob returns the pattern as-\/provided, rather than interpreting the character escapes. For example, {\ttfamily glob.\+match(\mbox{[}\mbox{]}, \char`\"{}\textbackslash{}\textbackslash{}$\ast$a\textbackslash{}\textbackslash{}?\char`\"{})} will return {\ttfamily \char`\"{}\textbackslash{}\textbackslash{}$\ast$a\textbackslash{}\textbackslash{}?\char`\"{}} rather than {\ttfamily \char`\"{}$\ast$a?\char`\"{}}. This is akin to setting the {\ttfamily 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 {\ttfamily +(a$\vert$\{b),c)\}}, which would not be valid in bash or zsh, is expanded {\bfseries{first}} into the set of {\ttfamily +(a$\vert$b)} and {\ttfamily +(a$\vert$c)}, and those patterns are checked for validity. Since those two are valid, matching proceeds.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11361}{}\doxysubsection{Comments and Negation}\label{md_sfcode_node_modules_glob_README_autotoc_md11361}
Previously, this module let you mark a pattern as a \char`\"{}comment\char`\"{} if it started with a {\ttfamily \#} character, or a \char`\"{}negated\char`\"{} pattern if it started with a {\ttfamily !} character.

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

To specify things that should not match, use the {\ttfamily ignore} option.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11362}{}\doxysection{Windows}\label{md_sfcode_node_modules_glob_README_autotoc_md11362}
{\bfseries{Please only use forward-\/slashes in glob expressions.}}

Though windows uses either {\ttfamily /} or {\ttfamily \textbackslash{}} as its path separator, only {\ttfamily /} characters are used by this glob implementation. You must use forward-\/slashes {\bfseries{only}} in glob expressions. Back-\/slashes will always be interpreted as escape characters, not path separators.

Results from absolute patterns such as {\ttfamily /foo/$\ast$} are mounted onto the root setting using {\ttfamily path.\+join}. On windows, this will by default result in {\ttfamily /foo/$\ast$} matching {\ttfamily C\+:\textbackslash{}foo\textbackslash{}bar.\+txt}.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11363}{}\doxysection{Race Conditions}\label{md_sfcode_node_modules_glob_README_autotoc_md11363}
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 stat\+Cache 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.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11364}{}\doxysection{Glob Logo}\label{md_sfcode_node_modules_glob_README_autotoc_md11364}
Glob\textquotesingle{}s logo was created by \href{http://tanyabrassie.com/}{\texttt{ Tanya Brassie}}. Logo files can be found \href{https://github.com/isaacs/node-glob/tree/master/logo}{\texttt{ here}}.

The logo is licensed under a \href{https://creativecommons.org/licenses/by-sa/4.0/}{\texttt{ Creative Commons Attribution-\/\+Share\+Alike 4.\+0 International License}}.\hypertarget{md_sfcode_node_modules_glob_README_autotoc_md11365}{}\doxysection{Contributing}\label{md_sfcode_node_modules_glob_README_autotoc_md11365}
Any change to behavior (including bugfixes) must come with a test.

Patches that fail tests or reduce performance will be rejected.


\begin{DoxyCode}{0}
\DoxyCodeLine{\# to run tests}
\DoxyCodeLine{npm test}
\DoxyCodeLine{}
\DoxyCodeLine{\# to re-\/generate test fixtures}
\DoxyCodeLine{npm run test-\/regen}
\DoxyCodeLine{}
\DoxyCodeLine{\# to benchmark against bash/zsh}
\DoxyCodeLine{npm run bench}
\DoxyCodeLine{}
\DoxyCodeLine{\# to profile javascript}
\DoxyCodeLine{npm run prof }

\end{DoxyCode}


 