globby

Functions

• convertPathToPattern()
• generateGlobTasks()
• generateGlobTasksSync()
• globby()
• globbyStream()
• globbySync()
• isDynamicPattern()
• isGitIgnored()
• isGitIgnoredSync()
• isIgnoredByIgnoreFiles()
• isIgnoredByIgnoreFilesSync()

Type Aliases

• AsyncIterableReadable
• ExpandDirectoriesOption
• FastGlobOptionsWithoutCwd
• GitignoreOptions
• GlobbyEntryStream
• GlobbyFilterFunction
• GlobbyStream
• GlobEntry
• GlobTask
• Options

function convertPathToPattern

convertPathToPattern: (source: string) => FastGlob.Pattern;

• Converts a path to a pattern by escaping special glob characters like (), [], {}. On Windows, also converts backslashes to forward slashes.

  Use this when your literal paths contain characters with special meaning in globs.

  Parameter source

  A file system path to convert to a safe glob pattern.

  Returns

  The path with special glob characters escaped.

  Example 1

  import {globby, convertPathToPattern} from 'globby';
  
  // ❌ Fails - parentheses are glob syntax
  await globby('C:/Program Files (x86)/*.txt');
  //=> []
  
  // ✅ Works
  const base = convertPathToPattern('C:/Program Files (x86)');
  await globby(`${base}/*.txt`);
  //=> ['C:/Program Files (x86)/file.txt']

function generateGlobTasks

generateGlobTasks: (
    patterns: string | readonly string[],
    options?: Options
) => Promise<GlobTask[]>;

• Note that you should avoid running the same tasks multiple times as they contain a file system cache. Instead, run this method each time to ensure file system changes are taken into consideration.

  Parameter patterns

  See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns).

  Parameter options

  See the [fast-glob options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones in this package.

  Returns

  An object in the format {pattern: string, options: object}, which can be passed as arguments to [fast-glob](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.

function generateGlobTasksSync

generateGlobTasksSync: (
    patterns: string | readonly string[],
    options?: Options
) => GlobTask[];

• Returns

  An object in the format {pattern: string, options: object}, which can be passed as arguments to [fast-glob](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.

  See Also

  • generateGlobTasks

function globby

globby: {
    (
        patterns: string | readonly string[],
        options: Options & ({ objectMode: true } | { stats: true })
    ): Promise<GlobEntry[]>;
    (patterns: string | readonly string[], options?: Options): Promise<string[]>;
};

• Find files and directories using glob patterns.

  Note that glob patterns can only contain forward-slashes, not backward-slashes, so if you want to construct a glob pattern from path components, you need to use path.posix.join() instead of path.join().

  Windows: Patterns with backslashes will silently fail. Use path.posix.join() or convertPathToPattern().

  Parameter patterns

  See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns). Supports negation patterns to exclude files. When using only negation patterns (like ['!*.json']), globby implicitly prepends a catch-all pattern to match all files before applying negations.

  Parameter options

  See the [fast-glob options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones in this package.

  Returns

  The matching paths.

  Example 1

  import {globby} from 'globby';
  
  const paths = await globby(['*', '!cake']);
  
  console.log(paths);
  //=> ['unicorn', 'rainbow']

  Example 2

  import {globby} from 'globby';
  
  // Negation-only patterns match all files except the negated ones
  const paths = await globby(['!*.json', '!*.xml'], {cwd: 'config'});
  
  console.log(paths);
  //=> ['config.js', 'settings.yaml']

function globbyStream

globbyStream: {
    (
        patterns: string | readonly string[],
        options: Options & ({ objectMode: true } | { stats: true })
    ): GlobbyEntryStream;
    (patterns: string | readonly string[], options?: Options): GlobbyStream;
};

• Find files and directories using glob patterns.

  Note that glob patterns can only contain forward-slashes, not backward-slashes, so if you want to construct a glob pattern from path components, you need to use path.posix.join() instead of path.join().

  Parameter patterns

  See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns).

  Parameter options

  See the [fast-glob options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones in this package.

  Returns

  The stream of matching paths.

  Example 1

  import {globbyStream} from 'globby';
  
  for await (const path of globbyStream('*.tmp')) {
  	console.log(path);
  }

function globbySync

globbySync: {
    (
        patterns: string | readonly string[],
        options: Options & ({ objectMode: true } | { stats: true })
    ): GlobEntry[];
    (patterns: string | readonly string[], options?: Options): string[];
};

• Find files and directories using glob patterns.

  Note that glob patterns can only contain forward-slashes, not backward-slashes, so if you want to construct a glob pattern from path components, you need to use path.posix.join() instead of path.join().

  Parameter patterns

  See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns).

  Parameter options

  See the [fast-glob options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones in this package.

  Returns

  The matching paths.

function isDynamicPattern

isDynamicPattern: (
    patterns: string | readonly string[],
    options?: FastGlobOptionsWithoutCwd & { readonly cwd?: URL | string }
) => boolean;

• Note that the options affect the results.

  This function is backed by [fast-glob](https://github.com/mrmlnc/fast-glob#isdynamicpatternpattern-options).

  Parameter patterns

  See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns).

  Parameter options

  See the [fast-glob options](https://github.com/mrmlnc/fast-glob#options-3).

  Returns

  Whether there are any special glob characters in the patterns.

function isGitIgnored

isGitIgnored: (options?: GitignoreOptions) => Promise<GlobbyFilterFunction>;

• .gitignore files matched by the ignore config are not used for the resulting filter function.

  Returns

  A filter function indicating whether a given path is ignored via a .gitignore file.

  Example 1

  import {isGitIgnored} from 'globby';
  
  const isIgnored = await isGitIgnored();
  
  console.log(isIgnored('some/file'));

function isGitIgnoredSync

isGitIgnoredSync: (options?: GitignoreOptions) => GlobbyFilterFunction;

• Returns

  A filter function indicating whether a given path is ignored via a .gitignore file.

  See Also

  • isGitIgnored

function isIgnoredByIgnoreFiles

isIgnoredByIgnoreFiles: (
    patterns: string | readonly string[],
    options?: Options
) => Promise<GlobbyFilterFunction>;

• Check if a path is ignored by the ignore files.

  Parameter patterns

  See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns).

  Parameter options

  See the [fast-glob options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones in this package.

  Returns

  A filter function indicating whether a given path is ignored via the ignore files.

  This is a more generic form of the isGitIgnored function, allowing you to find ignore files with a [compatible syntax](http://git-scm.com/docs/gitignore). For instance, this works with Babel's .babelignore, Prettier's .prettierignore, or ESLint's .eslintignore files.

  Example 1

  import {isIgnoredByIgnoreFiles} from 'globby';
  
  const isIgnored = await isIgnoredByIgnoreFiles('**\/.gitignore');
  
  console.log(isIgnored('some/file'));

function isIgnoredByIgnoreFilesSync

isIgnoredByIgnoreFilesSync: (
    patterns: string | readonly string[],
    options?: Options
) => GlobbyFilterFunction;

• Check if a path is ignored by the ignore files.

  Parameter patterns

  See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns).

  Parameter options

  See the [fast-glob options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones in this package.

  Returns

  A filter function indicating whether a given path is ignored via the ignore files.

  This is a more generic form of the isGitIgnored function, allowing you to find ignore files with a [compatible syntax](http://git-scm.com/docs/gitignore). For instance, this works with Babel's .babelignore, Prettier's .prettierignore, or ESLint's .eslintignore files.

  Example 1

  import {isIgnoredByIgnoreFilesSync} from 'globby';
  
  const isIgnored = isIgnoredByIgnoreFilesSync('**\/.gitignore');
  
  console.log(isIgnored('some/file'));

  See Also

  • isIgnoredByIgnoreFiles

type AsyncIterableReadable

type AsyncIterableReadable<Value> = Omit<
    NodeJS.ReadableStream,
    typeof Symbol.asyncIterator
> & {
    [Symbol.asyncIterator](): NodeJS.AsyncIterator<Value>;
};

type ExpandDirectoriesOption

type ExpandDirectoriesOption =
    | boolean
    | readonly string[]
    | { files?: readonly string[]; extensions?: readonly string[] };

type FastGlobOptionsWithoutCwd

type FastGlobOptionsWithoutCwd = Omit<FastGlob.Options, 'cwd'>;

type GitignoreOptions

type GitignoreOptions = {
    /**
	The current working directory in which to search.

	@default process.cwd()
	*/
    readonly cwd?: URL | string;

    /**
	Suppress errors when encountering directories or files without read permissions.

	By default, fast-glob only suppresses `ENOENT` errors. Set to `true` to suppress any error.

	@default false
	*/
    readonly suppressErrors?: boolean;

    /**
	Specifies the maximum depth of ignore file search relative to the start directory.

	@default Infinity
	*/
    readonly deep?: number;

    /**
	Glob patterns to exclude from ignore file search.

	@default []
	*/
    readonly ignore?: string | readonly string[];

    /**
	Indicates whether to traverse descendants of symbolic link directories.

	@default true
	*/
    readonly followSymbolicLinks?: boolean;

    /**
	Specifies the maximum number of concurrent requests from a reader to read directories.

	@default os.cpus().length
	*/
    readonly concurrency?: number;

    /**
	Throw an error when symbolic link is broken if `true` or safely return `lstat` call if `false`.

	@default false
	*/
    readonly throwErrorOnBrokenSymbolicLink?: boolean;

    /**
	Custom file system implementation (useful for testing or virtual file systems).

	@default undefined
	*/
    readonly fs?: FastGlob.Options['fs'];
};

type GlobbyEntryStream

type GlobbyEntryStream = AsyncIterableReadable<GlobEntry>;

• A readable stream that yields GlobEntry objects from glob patterns when objectMode is enabled.

type GlobbyFilterFunction

type GlobbyFilterFunction = (path: URL | string) => boolean;

type GlobbyStream

type GlobbyStream = AsyncIterableReadable<string>;

• A readable stream that yields string paths from glob patterns.

type GlobEntry

type GlobEntry = FastGlob.Entry;

type GlobTask

type GlobTask = {
    readonly patterns: string[];
    readonly options: Options;
};

type Options

type Options = {
    /**
	If set to `true`, `globby` will automatically glob directories for you. If you define an `Array` it will only glob files that matches the patterns inside the `Array`. You can also define an `Object` with `files` and `extensions` like in the example below.

	Note that if you set this option to `false`, you won't get back matched directories unless you set `onlyFiles: false`.

	@default true

	@example
	```
	import {globby} from 'globby';

	const paths = await globby('images', {
		expandDirectories: {
			files: ['cat', 'unicorn', '*.jpg'],
			extensions: ['png']
		}
	});

	console.log(paths);
	//=> ['cat.png', 'unicorn.png', 'cow.jpg', 'rainbow.jpg']
	```
	*/
    readonly expandDirectories?: ExpandDirectoriesOption;

    /**
	Respect ignore patterns in `.gitignore` files that apply to the globbed files.

	When enabled, globby searches for `.gitignore` files from the current working directory downward, and if a Git repository is detected (by finding a `.git` directory), it also respects `.gitignore` files in parent directories up to the repository root. This matches Git's actual behavior where patterns from parent `.gitignore` files apply to subdirectories.

	Gitignore patterns take priority over user patterns, matching Git's behavior. To include gitignored files, set this to `false`.

	Performance: Globby reads `.gitignore` files before globbing. When there are no negation patterns (like `!important.log`) and no parent `.gitignore` files are found, it passes ignore patterns to fast-glob to skip traversing ignored directories entirely, which significantly improves performance for large `node_modules` or build directories. When negation patterns or parent `.gitignore` files are present, all filtering is done after traversal to ensure correct Git-compatible behavior. For optimal performance, prefer specific `.gitignore` patterns without negations, or use `ignoreFiles: '.gitignore'` to target only the root ignore file.

	@default false
	*/
    readonly gitignore?: boolean;

    /**
	Glob patterns to look for ignore files, which are then used to ignore globbed files.

	This is a more generic form of the `gitignore` option, allowing you to find ignore files with a [compatible syntax](http://git-scm.com/docs/gitignore). For instance, this works with Babel's `.babelignore`, Prettier's `.prettierignore`, or ESLint's `.eslintignore` files.

	Performance tip: Using a specific path like `'.gitignore'` is much faster than recursive patterns.

	@default undefined
	*/
    readonly ignoreFiles?: string | readonly string[];

    /**
	The current working directory in which to search.

	@default process.cwd()
	*/
    readonly cwd?: URL | string;
} & FastGlobOptionsWithoutCwd;