DOCSEARCHbyAlgolia
Submit Docs

glob

repository·main·Indexed 27 days ago

https://github.com/isaacs/node-glob

A high-performance JavaScript implementation for matching file paths using shell-style patterns. Version 13.0.6 supports asynchronous (glob()), synchronous (globSync()), streaming (globStream()), and iterative (globIterate()) traversal of file systems. It includes a reusable Glob class for optimized traversals and provides Path objects via the withFileTypes option. The library supports complex glob syntax, including globstar (**), brace expansion, and custom ignore logic.

Tokens
4.9K
Snippets
4
Records
39
Agent score
92%

What's inside glob

  2. Use Glob on Windows

    main

    When using node-glob on Windows, you must use forward-slashes (/) in your glob expressions. Back-slashes (\) are interpreted as escape characters, not path separators.

    Automatic Path Coercion

    To automatically convert all \ characters to / in your pattern strings (which makes it impossible to escape literal glob characters), set the windowsPathsNoEscape option to true.

  3. Run Tests and Benchmarks

    main

    If you are contributing to the project, use the following commands:

    # to run tests
npm test

# to re-generate test fixtures
npm run test-regen

# run the benchmarks
npm run bench

# to profile javascript
npm run prof

  4. Understand Glob Pattern Syntax

    main

    Globs are patterns used to match file paths. Before parsing path portions, braced sections {} are expanded into a set (e.g., a{/b/c,bcd} expands to a/b/c and abcd).

    Special Characters

    • *: Matches 0 or more characters in a single path portion. If alone in a portion, it must match at least 1 character. If dot:true is not set, it won't match leading . characters.
    • ?: Matches exactly 1 character. If dot:true is not set, it won't match leading . characters.
    • [...]: Matches a range of characters (RegExp style). [!...] or [^...] matches anything NOT in the range.
    • !(pattern|...): Matches anything that does NOT match the provided patterns. Cannot contain /.
    • ?(pattern|...): Matches zero or one occurrence of the patterns.
    • +(pattern|...): Matches one or more occurrences of the patterns.
    • *(pattern|...): Matches zero or more occurrences of the patterns.
    • @(pattern|...): Matches exactly one of the patterns.
    • **: (Globstar) Matches zero or more directories and subdirectories. It does not crawl symlinked directories unless {follow:true} is passed. A pattern like a/b/** matches a/b if it is a directory.

  6. Compare node-glob with other JavaScript glob implementations

    main

    When choosing a glob library for your project, consider these three primary options based on your requirements:

    • node-glob: Use this if you need glob matching that is as faithful as possible to Bash pattern expansion semantics and requires high correctness. It handles complex patterns (like .. path portions or specific brace patterns) more reliably than faster alternatives.
    • fast-glob: Use this if you need the absolute fastest glob matcher and your patterns are relatively simple. Note that it may differ from Bash behavior (e.g., ** might only match files, not directories, in some contexts, and it has specific limitations with .. and certain extglob patterns).
    • globby: Use this if you want the convenience of automatically respecting .gitignore files and support for negated globs (patterns starting with !). It is a wrapper around fast-glob and is slightly slower than both fast-glob and node-glob.

  7. Enable Basename Matching

    main

    If you want to find files matching a pattern anywhere in the directory tree regardless of their depth, set matchBase:true in the options. This only works if the pattern contains no slashes.

    Example: *.js with matchBase:true will match test/simple/basic.js.

  8. Configure Dot File Matching

    main

    By default, glob patterns do not match files or directories starting with a . (dot files) unless the pattern itself explicitly starts with a dot. For example, a/*/c will not match a/.b/c.

    To make glob treat dots as normal characters, set dot:true in the options object.

  9. Configure GlobOptions

    main
    The GlobOptions interface defines the configuration for all globbing operations. Options are optional, boolean, and false by default unless otherwise noted. You can pass a GlobOptions object to any exported method or the Glob constructor. To optimize performance when running many operations, you can pass an existing Glob object as the options argument to a subsequent operation to share the loaded cache.