Glob File Matching Utility

Common errors

• TypeError: glob is not a function

  cause Attempting to call `require('glob')()` directly or incorrect destructuring in CommonJS.
  fix For CommonJS, use `const { glob } = require('glob');` then call `glob(...)`. For ESM, use `import { glob } from 'glob';`.

• SyntaxError: await is only valid in async functions and the top level bodies of modules

  cause Using `await glob(...)` outside an `async` function or a module with top-level await enabled.
  fix Define an `async` function and call `glob` inside it, or enable top-level await in your Node.js environment (requires Node.js 14+ and ESM modules).

• Error: EMFILE: too many open files, open '...'

  cause Globbing a very large number of files on systems with low file descriptor limits, especially with `stat: true`.
  fix Increase your system's file descriptor limit (e.g., `ulimit -n 4096` on Unix-like systems) or use `globStream` for memory efficiency and to avoid opening too many files simultaneously.

Warnings

• gotcha The npm package name is `glob`, not `node-glob`. The `node-glob` package is a different, abandoned project. Installing or referencing `node-glob` will lead to using an outdated and unmaintained library.
  Fix: Always use `npm install glob` and `import { ... } from 'glob'` or `require('glob')`.
• breaking Previous major versions might have used different argument signatures or returned different types. For instance, `glob.sync` might have been a direct property on the main `glob` export in older versions, which is not the case in v13.
  Fix: Consult the `glob` v13 documentation for current API signatures and return types. Migrate to named exports for all functions (`glob`, `globSync`, `globStream`, etc.) and the `Glob` class.
• gotcha When using `async`/`await` with `glob` (the default asynchronous function), ensure your code is within an `async` function or top-level `await` is enabled, otherwise, you'll receive a `Promise` instead of the resolved file list.
  Fix: Wrap `await glob(...)` calls in an `async` function or ensure your environment supports top-level `await`.
• gotcha The `ignore` option can accept a string, an array of strings, or an object with `ignored` and/or `childrenIgnored` functions for custom ignore logic. Misunderstanding this flexibility can lead to files not being ignored as expected or performance issues with complex custom ignore functions.
  Fix: Review the documentation for the `ignore` option. For simple patterns, use string/array. For advanced filtering, ensure your `ignored` and `childrenIgnored` functions are efficient and correctly handle `Path` objects if `withFileTypes` is used.

Install

• npm install glob npm
• yarn add glob yarn
• pnpm add glob pnpm

Imports

• glob
  wrong:

  const glob = require('glob').glob

  correct:

  import { glob } from 'glob'

  Primary asynchronous function for matching files, returns a Promise<string[]>. Named export, not default. CommonJS requires destructuring.
• Glob
  wrong:

  import Glob from 'glob'

  correct:

  import { Glob } from 'glob'

  Class for creating reusable glob instances, useful for multiple walks or iterating. This is a named export, not a default import. CommonJS requires destructuring.
• globSync
  wrong:

  require('glob').globSync()

  correct:

  import { globSync } from 'glob'

  Synchronous version of `glob`, returns `string[]`. Similar to `glob`, it's a named export and requires destructuring for CommonJS.

Quickstart

Demonstrates asynchronous glob matching, multi-pattern support, iteration with the `Glob` class, and retrieving detailed file type information with stats.

import { glob, Glob } from 'glob';
import { AbortSignal } from 'node:os'; // Or 'node-abort-controller' for older Node.js

async function runGlobExamples() {
  // Find all JavaScript files, ignoring node_modules
  console.log('Finding JS files (excluding node_modules)...');
  const jsFiles = await glob('**/*.js', { ignore: 'node_modules/**' });
  console.log('Found JS files:', jsFiles.slice(0, 5), '...');

  // Find images with multiple patterns
  console.log('\nFinding image files...');
  const images = await glob(['css/*.{png,jpeg}', 'public/*.{png,jpeg}']);
  console.log('Found images:', images);

  // Using a Glob object for reusability and async iteration
  console.log('\nIterating with Glob object for "**/foo"...');
  const g = new Glob('**/foo', {});
  let fooCount = 0;
  for await (const file of g) {
    console.log('Found foo file:', file);
    fooCount++;
    if (fooCount > 3) break; // Limit output for example
  }
  if (fooCount === 0) console.log('No foo files found in this example.');

  // Find files with detailed file types and stats, sorted by modification time
  console.log('\nFinding all files with stats, sorted by mtime...');
  const results = await glob('**', { stat: true, withFileTypes: true, nodir: true });
  const timeSortedFiles = results
    .sort((a, b) => a.mtimeMs - b.mtimeMs)
    .map(path => ({ path: path.fullpath(), mtime: new Date(path.mtimeMs).toLocaleTimeString() }))
    .slice(0, 5);
  console.log('Top 5 recently modified files:', timeSortedFiles);
}

runGlobExamples().catch(console.error);