glob

  • Version 10.4.2
  • Published
  • 475 kB
  • 6 dependencies
  • ISC license

Install

npm i glob
yarn add glob
pnpm add glob

Overview

the most correct and second fastest glob implementation in JavaScript

Index

Variables

variable glob

const glob: {
(pattern: string | string[], options?: GlobOptionsWithFileTypesUnset): Promise<
string[]
>;
(pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Promise<
Path[]
>;
(pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Promise<
string[]
>;
(pattern: string | string[], options: GlobOptions): Promise<string[] | Path[]>;
} & {
glob: typeof glob_;
globSync: typeof globSync;
sync: typeof globSync & {
stream: typeof globStreamSync;
iterate: typeof globIterateSync;
};
globStream: typeof globStream;
stream: typeof globStream & { sync: typeof globStreamSync };
globStreamSync: typeof globStreamSync;
streamSync: typeof globStreamSync;
globIterate: typeof globIterate;
iterate: typeof globIterate & { sync: typeof globIterateSync };
globIterateSync: typeof globIterateSync;
iterateSync: typeof globIterateSync;
Glob: typeof Glob;
hasMagic: (pattern: string | string[], options?: GlobOptions) => boolean;
escape: (
s: string,
{
windowsPathsNoEscape,
}?:
| Pick<import('minimatch').MinimatchOptions, 'windowsPathsNoEscape'>
| undefined
) => string;
unescape: (
s: string,
{
windowsPathsNoEscape,
}?:
| Pick<import('minimatch').MinimatchOptions, 'windowsPathsNoEscape'>
| undefined
) => string;
};

    variable iterate

    const iterate: {
    (
    pattern: string | string[],
    options?: GlobOptionsWithFileTypesUnset
    ): AsyncGenerator<string, void, void>;
    (
    pattern: string | string[],
    options: GlobOptionsWithFileTypesTrue
    ): AsyncGenerator<Path, void, void>;
    (
    pattern: string | string[],
    options: GlobOptionsWithFileTypesFalse
    ): AsyncGenerator<string, void, void>;
    (pattern: string | string[], options: GlobOptions):
    | AsyncGenerator<string, void, void>
    | AsyncGenerator<Path, void, void>;
    } & { sync: typeof globIterateSync };

      variable iterateSync

      const iterateSync: {
      (pattern: string | string[], options?: GlobOptionsWithFileTypesUnset): Generator<
      string,
      void,
      void
      >;
      (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Generator<
      Path,
      void,
      void
      >;
      (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Generator<
      string,
      void,
      void
      >;
      (pattern: string | string[], options: GlobOptions):
      | Generator<string, void, void>
      | Generator<Path, void, void>;
      };

        variable stream

        const stream: {
        (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Minipass<
        string,
        string
        >;
        (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Minipass<
        Path,
        Path
        >;
        (pattern: string | string[], options?: GlobOptionsWithFileTypesUnset): Minipass<
        string,
        string
        >;
        (pattern: string | string[], options: GlobOptions): any;
        } & { sync: typeof globStreamSync };

          variable streamSync

          const streamSync: {
          (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Minipass<
          Path,
          Path
          >;
          (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Minipass<
          string,
          string
          >;
          (pattern: string | string[], options: GlobOptionsWithFileTypesUnset): Minipass<
          string,
          string
          >;
          (pattern: string | string[], options: GlobOptions): any;
          };

            variable sync

            const sync: {
            (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): string[];
            (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Path[];
            (pattern: string | string[], options?: GlobOptionsWithFileTypesUnset): string[];
            (pattern: string | string[], options: GlobOptions): string[] | Path[];
            } & { stream: typeof globStreamSync; iterate: typeof globIterateSync };

              Functions

              function glob_

              glob_: {
              (
              pattern: string | string[],
              options?: GlobOptionsWithFileTypesUnset | undefined
              ): Promise<string[]>;
              (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Promise<
              Path[]
              >;
              (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Promise<
              string[]
              >;
              (pattern: string | string[], options: GlobOptions): Promise<string[] | Path[]>;
              };
              • Perform an asynchronous glob search for the pattern(s) specified. Returns [Path](https://isaacs.github.io/path-scurry/classes/PathBase) objects if the withFileTypes option is set to true. See GlobOptions for full option descriptions.

              function globIterate

              globIterate: {
              (
              pattern: string | string[],
              options?: GlobOptionsWithFileTypesUnset | undefined
              ): AsyncGenerator<string, void, void>;
              (
              pattern: string | string[],
              options: GlobOptionsWithFileTypesTrue
              ): AsyncGenerator<Path, void, void>;
              (
              pattern: string | string[],
              options: GlobOptionsWithFileTypesFalse
              ): AsyncGenerator<string, void, void>;
              (pattern: string | string[], options: GlobOptions):
              | AsyncGenerator<string, void, void>
              | AsyncGenerator<Path, void, void>;
              };
              • Return an async iterator for walking glob pattern matches.

              function globIterateSync

              globIterateSync: {
              (
              pattern: string | string[],
              options?: GlobOptionsWithFileTypesUnset | undefined
              ): Generator<string, void, void>;
              (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Generator<
              Path,
              void,
              void
              >;
              (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Generator<
              string,
              void,
              void
              >;
              (pattern: string | string[], options: GlobOptions):
              | Generator<string, void, void>
              | Generator<Path, void, void>;
              };
              • Return a sync iterator for walking glob pattern matches.

              function globStream

              globStream: {
              (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Minipass<
              string,
              string
              >;
              (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Minipass<
              Path,
              Path
              >;
              (pattern: string | string[], options?: GlobOptionsWithFileTypesUnset): Minipass<
              string,
              string
              >;
              (pattern: string | string[], options: GlobOptions): any;
              };
              • Return a stream that emits all the strings or Path objects and then emits end when completed.

              function globStreamSync

              globStreamSync: {
              (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Minipass<
              Path,
              Path
              >;
              (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): Minipass<
              string,
              string
              >;
              (pattern: string | string[], options: GlobOptionsWithFileTypesUnset): Minipass<
              string,
              string
              >;
              (pattern: string | string[], options: GlobOptions): any;
              };
              • Syncronous form of globStream. Will read all the matches as fast as you consume them, even all in a single tick if you consume them immediately, but will still respond to backpressure if they're not consumed immediately.

              function globSync

              globSync: {
              (pattern: string | string[], options: GlobOptionsWithFileTypesFalse): string[];
              (pattern: string | string[], options: GlobOptionsWithFileTypesTrue): Path[];
              (pattern: string | string[], options?: GlobOptionsWithFileTypesUnset): string[];
              (pattern: string | string[], options: GlobOptions): string[] | Path[];
              };
              • Synchronous form of glob

              function hasMagic

              hasMagic: (pattern: string | string[], options?: GlobOptions) => boolean;
              • Return true if the patterns provided contain any magic glob characters, given the options provided.

                Brace expansion is not considered "magic" unless the magicalBraces option is set, as brace expansion just turns one string into an array of strings. So a pattern like 'x{a,b}y' would return false, because 'xay' and 'xby' both do not contain any magic glob characters, and it's treated the same as if you had called it on ['xay', 'xby']. When magicalBraces:true is in the options, brace expansion _is_ treated as a pattern having magic.

              Classes

              class Glob

              class Glob<Opts extends GlobOptions> implements GlobOptions {}
              • An object that can perform glob pattern traversals.

              constructor

              constructor(pattern: string | string[], opts: GlobOptions);
              • All options are stored as properties on the Glob object.

                See GlobOptions for full options descriptions.

                Note that a previous Glob object can be passed as the GlobOptions to another Glob instantiation to re-use settings and caches with a new pattern.

                Traversal functions can be called multiple times to run the walk again.

              property absolute

              absolute?: boolean;

                property cwd

                cwd: string;

                  property dot

                  dot: boolean;

                    property dotRelative

                    dotRelative: boolean;

                      property follow

                      follow: boolean;

                        property ignore

                        ignore?: string | string[] | IgnoreLike;

                          property includeChildMatches

                          includeChildMatches: boolean;

                            property magicalBraces

                            magicalBraces: boolean;

                              property mark

                              mark?: boolean;

                                property matchBase

                                matchBase: boolean;

                                  property maxDepth

                                  maxDepth: number;

                                    property nobrace

                                    nobrace: boolean;

                                      property nocase

                                      nocase: boolean;

                                        property nodir

                                        nodir: boolean;

                                          property noext

                                          noext: boolean;

                                            property noglobstar

                                            noglobstar: boolean;

                                              property opts

                                              opts: GlobOptions;
                                              • The options provided to the constructor.

                                              property pattern

                                              pattern: string[];

                                                property patterns

                                                patterns: Pattern[];
                                                • An array of parsed immutable Pattern objects.

                                                property platform

                                                platform: NodeJS.Platform;

                                                  property realpath

                                                  realpath: boolean;

                                                    property root

                                                    root?: string;

                                                      property scurry

                                                      scurry: PathScurry;

                                                        property signal

                                                        signal?: AbortSignal;

                                                          property stat

                                                          stat: boolean;

                                                            property windowsPathsNoEscape

                                                            windowsPathsNoEscape: boolean;

                                                              property withFileTypes

                                                              withFileTypes: boolean;

                                                                method [Symbol.asyncIterator]

                                                                [Symbol.asyncIterator]: () => AsyncGenerator<Result<Opts>, void, void>;

                                                                  method [Symbol.iterator]

                                                                  [Symbol.iterator]: () => Generator<Result<Opts>, void, void>;

                                                                    method iterate

                                                                    iterate: () => AsyncGenerator<Result<Opts>, void, void>;
                                                                    • Default async iteration function. Returns an AsyncGenerator that iterates over the results.

                                                                    method iterateSync

                                                                    iterateSync: () => Generator<Result<Opts>, void, void>;
                                                                    • Default sync iteration function. Returns a Generator that iterates over the results.

                                                                    method stream

                                                                    stream: () => Minipass<Result<Opts>, Result<Opts>>;
                                                                    • Stream results asynchronously.

                                                                    method streamSync

                                                                    streamSync: () => Minipass<Result<Opts>, Result<Opts>>;
                                                                    • Stream results synchronously.

                                                                    method walk

                                                                    walk: () => Promise<Results<Opts>>;
                                                                    • Returns a Promise that resolves to the results array.

                                                                    method walkSync

                                                                    walkSync: () => Results<Opts>;

                                                                    class Ignore

                                                                    class Ignore implements IgnoreLike {}
                                                                    • Class used to process ignored patterns

                                                                    constructor

                                                                    constructor(
                                                                    ignored: string[],
                                                                    { nobrace, nocase, noext, noglobstar, platform }: GlobWalkerOpts
                                                                    );

                                                                      property absolute

                                                                      absolute: Minimatch[];

                                                                        property absoluteChildren

                                                                        absoluteChildren: Minimatch[];

                                                                          property mmopts

                                                                          mmopts: MinimatchOptions;

                                                                            property platform

                                                                            platform: NodeJS.Platform;

                                                                              property relative

                                                                              relative: Minimatch[];

                                                                                property relativeChildren

                                                                                relativeChildren: Minimatch[];

                                                                                  method add

                                                                                  add: (ign: string) => void;

                                                                                    method childrenIgnored

                                                                                    childrenIgnored: (p: Path) => boolean;

                                                                                      method ignored

                                                                                      ignored: (p: Path) => boolean;

                                                                                        Interfaces

                                                                                        interface GlobOptions

                                                                                        interface GlobOptions {}
                                                                                        • A GlobOptions object may be provided to any of the exported methods, and must be provided to the Glob constructor.

                                                                                          All options are optional, boolean, and false by default, unless otherwise noted.

                                                                                          All resolved options are added to the Glob object as properties.

                                                                                          If you are running many glob operations, you can pass a Glob object as the options argument to a subsequent operation to share the previously loaded cache.

                                                                                        property absolute

                                                                                        absolute?: boolean;
                                                                                        • Set to true to always receive absolute paths for matched files. Set to false to always return relative paths.

                                                                                          When this option is not set, absolute paths are returned for patterns that are absolute, and otherwise paths are returned that are relative to the cwd setting.

                                                                                          This does _not_ make an extra system call to get the realpath, it only does string path resolution.

                                                                                          Conflicts with withFileTypes

                                                                                        property allowWindowsEscape

                                                                                        allowWindowsEscape?: boolean;

                                                                                        property cwd

                                                                                        cwd?: string | URL;
                                                                                        • The current working directory in which to search. Defaults to process.cwd().

                                                                                          May be eiher a string path or a file:// URL object or string.

                                                                                        property debug

                                                                                        debug?: boolean;
                                                                                        • Just passed along to Minimatch. Note that this makes all pattern matching operations slower and *extremely* noisy.

                                                                                        property dot

                                                                                        dot?: boolean;
                                                                                        • Include .dot files in normal matches and globstar matches. Note that an explicit dot in a portion of the pattern will always match dot files.

                                                                                        property dotRelative

                                                                                        dotRelative?: boolean;
                                                                                        • Prepend all relative path strings with ./ (or .\ on Windows).

                                                                                          Without this option, returned relative paths are "bare", so instead of returning './foo/bar', they are returned as 'foo/bar'.

                                                                                          Relative patterns starting with '../' are not prepended with ./, even if this option is set.

                                                                                        property follow

                                                                                        follow?: boolean;
                                                                                        • Follow symlinked directories when expanding ** patterns. This can result in a lot of duplicate references in the presence of cyclic links, and make performance quite bad.

                                                                                          By default, a ** in a pattern will follow 1 symbolic link if it is not the first item in the pattern, or none if it is the first item in the pattern, following the same behavior as Bash.

                                                                                        property fs

                                                                                        fs?: FSOption;
                                                                                        • An fs implementation to override some or all of the defaults. See http://npm.im/path-scurry for details about what can be overridden.

                                                                                        property ignore

                                                                                        ignore?: string | string[] | IgnoreLike;
                                                                                        • string or string[], or an object with ignore and ignoreChildren methods.

                                                                                          If a string or string[] is provided, then this is treated as a glob pattern or array of glob patterns to exclude from matches. To ignore all children within a directory, as well as the entry itself, append '/**' to the ignore pattern.

                                                                                          **Note** ignore patterns are _always_ in dot:true mode, regardless of any other settings.

                                                                                          If an object is provided that has ignored(path) and/or childrenIgnored(path) methods, then these methods will be called to determine whether any Path is a match or if its children should be traversed, respectively.

                                                                                        property includeChildMatches

                                                                                        includeChildMatches?: boolean;
                                                                                        • Do not match any children of any matches. For example, the pattern **\/foo would match a/foo, but not a/foo/b/foo in this mode.

                                                                                          This is especially useful for cases like "find all node_modules folders, but not the ones in node_modules".

                                                                                          In order to support this, the Ignore implementation must support an add(pattern: string) method. If using the default Ignore class, then this is fine, but if this is set to false, and a custom Ignore is provided that does not have an add() method, then it will throw an error.

                                                                                          **Caveat** It *only* ignores matches that would be a descendant of a previous match, and only if that descendant is matched *after* the ancestor is encountered. Since the file system walk happens in indeterminate order, it's possible that a match will already be added before its ancestor, if multiple or braced patterns are used.

                                                                                          For example:

                                                                                          const results = await glob([
                                                                                          // likely to match first, since it's just a stat
                                                                                          'a/b/c/d/e/f',
                                                                                          // this pattern is more complicated! It must to various readdir()
                                                                                          // calls and test the results against a regular expression, and that
                                                                                          // is certainly going to take a little bit longer.
                                                                                          //
                                                                                          // So, later on, it encounters a match at 'a/b/c/d/e', but it's too
                                                                                          // late to ignore a/b/c/d/e/f, because it's already been emitted.
                                                                                          'a/[bdf]/?/[a-z]/*',
                                                                                          ], { includeChildMatches: false })

                                                                                          It's best to only set this to false if you can be reasonably sure that no components of the pattern will potentially match one another's file system descendants, or if the occasional included child entry will not cause problems.

                                                                                          true

                                                                                        property magicalBraces

                                                                                        magicalBraces?: boolean;
                                                                                        • Treat brace expansion like {a,b} as a "magic" pattern. Has no effect if nobrace is set.

                                                                                          Only has effect on the hasMagic function.

                                                                                        property mark

                                                                                        mark?: boolean;
                                                                                        • Add a / character to directory matches. Note that this requires additional stat calls in some cases.

                                                                                        property matchBase

                                                                                        matchBase?: boolean;
                                                                                        • 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.

                                                                                        property maxDepth

                                                                                        maxDepth?: number;
                                                                                        • Limit the directory traversal to a given depth below the cwd. Note that this does NOT prevent traversal to sibling folders, root patterns, and so on. It only limits the maximum folder depth that the walk will descend, relative to the cwd.

                                                                                        property nobrace

                                                                                        nobrace?: boolean;
                                                                                        • Do not expand {a,b} and {1..3} brace sets.

                                                                                        property nocase

                                                                                        nocase?: boolean;
                                                                                        • Perform a case-insensitive match. This defaults to true on macOS and Windows systems, and false on all others.

                                                                                          **Note** nocase should only be explicitly set when it is known that the filesystem's case sensitivity differs from the platform default. If set true on case-sensitive file systems, or false on case-insensitive file systems, then the walk may return more or less results than expected.

                                                                                        property nodir

                                                                                        nodir?: boolean;
                                                                                        • Do not match directories, only files. (Note: to match _only_ directories, put a / at the end of the pattern.)

                                                                                        property noext

                                                                                        noext?: boolean;
                                                                                        • Do not match "extglob" patterns such as +(a|b).

                                                                                        property noglobstar

                                                                                        noglobstar?: boolean;
                                                                                        • Do not match ** against multiple filenames. (Ie, treat it as a normal * instead.)

                                                                                          Conflicts with matchBase

                                                                                        property platform

                                                                                        platform?: NodeJS.Platform;
                                                                                        • Defaults to value of process.platform if available, or 'linux' if not. Setting platform:'win32' on non-Windows systems may cause strange behavior.

                                                                                        property posix

                                                                                        posix?: boolean;
                                                                                        • Return / delimited paths, even on Windows.

                                                                                          On posix systems, this has no effect. But, on Windows, it means that paths will be / delimited, and absolute paths will be their full resolved UNC forms, eg instead of 'C:\\foo\\bar', it would return '//?/C:/foo/bar'

                                                                                        property realpath

                                                                                        realpath?: boolean;
                                                                                        • Set to true to call fs.realpath on all of the results. In the case of an entry that cannot be resolved, the entry is omitted. This incurs a slight performance penalty, of course, because of the added system calls.

                                                                                        property root

                                                                                        root?: string;
                                                                                        • A string path resolved against the cwd option, which is used as the starting point for absolute patterns that start with /, (but not drive letters or UNC paths on Windows).

                                                                                          Note that this _doesn't_ necessarily limit the walk to the root directory, and doesn't affect the cwd starting point for non-absolute patterns. A pattern containing .. will still be able to traverse out of the root directory, if it is not an actual root directory on the filesystem, and any non-absolute patterns will be matched in the cwd. For example, the pattern /../* with {root:'/some/path'} will return all files in /some, not all files in /some/path. The pattern * with {root:'/some/path'} will return all the entries in the cwd, not the entries in /some/path.

                                                                                          To start absolute and non-absolute patterns in the same path, you can use {root:''}. However, be aware that on Windows systems, a pattern like x:/* or //host/share/* will _always_ start in the x:/ or //host/share directory, regardless of the root setting.

                                                                                        property scurry

                                                                                        scurry?: PathScurry;
                                                                                        • A [PathScurry](http://npm.im/path-scurry) object used to traverse the file system. If the nocase option is set explicitly, then any provided scurry object must match this setting.

                                                                                        property signal

                                                                                        signal?: AbortSignal;
                                                                                        • An AbortSignal which will cancel the Glob walk when triggered.

                                                                                        property stat

                                                                                        stat?: boolean;
                                                                                        • Call lstat() on all entries, whether required or not to determine if it's a valid match. When used with withFileTypes, this means that matches will include data such as modified time, permissions, and so on. Note that this will incur a performance cost due to the added system calls.

                                                                                        property windowsPathsNoEscape

                                                                                        windowsPathsNoEscape?: boolean;
                                                                                        • Use \\ as a path separator _only_, and _never_ as an escape character. If set, all \\ characters are replaced with / in the pattern.

                                                                                          Note that this makes it **impossible** to match against paths containing literal glob pattern characters, but allows matching with patterns constructed using path.join() and path.resolve() on Windows platforms, mimicking the (buggy!) behavior of Glob v7 and before on Windows. Please use with caution, and be mindful of [the caveat below about Windows paths](#windows). (For legacy reasons, this is also set if allowWindowsEscape is set to the exact value false.)

                                                                                        property withFileTypes

                                                                                        withFileTypes?: boolean;
                                                                                        • Return [PathScurry](http://npm.im/path-scurry) Path objects instead of strings. These are similar to a NodeJS Dirent object, but with additional methods and properties.

                                                                                          Conflicts with absolute

                                                                                        interface IgnoreLike

                                                                                        interface IgnoreLike {}

                                                                                          property add

                                                                                          add?: (ignore: string) => void;

                                                                                            property childrenIgnored

                                                                                            childrenIgnored?: (p: Path) => boolean;

                                                                                              property ignored

                                                                                              ignored?: (p: Path) => boolean;

                                                                                                Type Aliases

                                                                                                type GlobOptionsWithFileTypesFalse

                                                                                                type GlobOptionsWithFileTypesFalse = GlobOptions & {
                                                                                                withFileTypes?: false;
                                                                                                };

                                                                                                  type GlobOptionsWithFileTypesTrue

                                                                                                  type GlobOptionsWithFileTypesTrue = GlobOptions & {
                                                                                                  withFileTypes: true;
                                                                                                  absolute?: undefined;
                                                                                                  mark?: undefined;
                                                                                                  posix?: undefined;
                                                                                                  };

                                                                                                    type GlobOptionsWithFileTypesUnset

                                                                                                    type GlobOptionsWithFileTypesUnset = GlobOptions & {
                                                                                                    withFileTypes?: undefined;
                                                                                                    };

                                                                                                      type MatchStream

                                                                                                      type MatchStream<O extends GlobWalkerOpts> = Minipass<Result<O>, Result<O>>;

                                                                                                        Package Files (5)

                                                                                                        Dependencies (6)

                                                                                                        Dev Dependencies (9)

                                                                                                        Peer Dependencies (0)

                                                                                                        No peer dependencies.

                                                                                                        Badge

                                                                                                        To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                                                        You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/glob.

                                                                                                        • Markdown
                                                                                                          [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/glob)
                                                                                                        • HTML
                                                                                                          <a href="https://www.jsdocs.io/package/glob"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>