User-friendly glob matching
Based on fast-glob but adds a bunch of useful features.
- Promise API
- Multiple patterns
- Negated patterns:
['foo*', '!foobar'] - Negation-only patterns:
['!foobar']→ matches all files exceptfoobar - Expands directories:
foo→foo/**/* - Supports
.gitignoreand similar ignore config files - Supports
URLascwd
npm install globby├── unicorn
├── cake
└── rainbow
import {globby} from 'globby';
const paths = await globby(['*', '!cake']);
console.log(paths);
//=> ['unicorn', 'rainbow']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().
Returns a Promise<string[]> of matching paths.
Type: string | string[]
See supported minimatch patterns.
Type: object
See the fast-glob options in addition to the ones below.
Type: boolean | string[] | object
Default: true
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 below:
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']Note that if you set this option to false, you won't get back matched directories unless you set onlyFiles: false.
Type: boolean
Default: false
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.
Type: string | string[]
Default: undefined
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. 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.
Type: FileSystemAdapter
Default: undefined
Custom file system implementation (useful for testing or virtual file systems).
Note: When using gitignore or ignoreFiles, the custom fs must also provide readFile/readFileSync methods.
Returns string[] of matching paths.
Returns a stream.Readable of matching paths.
For example, loop over glob matches in a for await...of loop like this:
import {globbyStream} from 'globby';
for await (const path of globbyStream('*.tmp')) {
console.log(path);
}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.
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']Returns an Promise<object[]> in the format {patterns: string[], options: Object}, which can be passed as arguments to fast-glob. This is useful for other globbing-related packages.
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.
Returns an object[] in the format {patterns: string[], options: Object}, which can be passed as arguments to fast-glob. This is useful for other globbing-related packages.
Takes the same arguments as generateGlobTasks.
Returns a boolean of whether there are any special glob characters in the patterns.
Note that the options affect the results.
This function is backed by fast-glob.
Returns a Promise<(path: URL | string) => boolean> indicating whether a given path is ignored via a .gitignore file.
Type: object
Type: URL | string
Default: process.cwd()
The current working directory in which to search.
Type: boolean
Default: false
Suppress errors when encountering directories or files without read permissions.
Type: number
Default: Infinity
Maximum depth to search for .gitignore files.
0- Only search in the start directory1- Search in the start directory and one level of subdirectories2- Search in the start directory and two levels of subdirectories
Type: string | string[]
Default: []
Glob patterns to exclude from .gitignore file search.
Type: boolean
Default: true
Indicates whether to traverse descendants of symbolic link directories.
Type: number
Default: os.cpus().length
Specifies the maximum number of concurrent requests from a reader to read directories.
Type: boolean
Default: false
Throw an error when symbolic link is broken if true or safely return lstat call if false.
Type: FileSystemAdapter
Default: undefined
Custom file system implementation (useful for testing or virtual file systems).
Note: The custom fs must provide readFile/readFileSync methods for reading .gitignore files.
import {isGitIgnored} from 'globby';
const isIgnored = await isGitIgnored();
console.log(isIgnored('some/file'));// Suppress errors when encountering unreadable directories
const isIgnored = await isGitIgnored({suppressErrors: true});// Limit search depth and exclude certain directories
const isIgnored = await isGitIgnored({
deep: 2,
ignore: ['**/node_modules/**', '**/dist/**']
});Returns a (path: URL | string) => boolean indicating whether a given path is ignored via a .gitignore file.
See isGitIgnored for options.
Returns a Promise<(path: URL | string) => boolean> 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. For instance, this works with Babel's .babelignore, Prettier's .prettierignore, or ESLint's .eslintignore files.
Type: string | string[]
Glob patterns to look for ignore files.
Type: object
See isGitIgnored options for all available options.
import {isIgnoredByIgnoreFiles} from 'globby';
const isIgnored = await isIgnoredByIgnoreFiles("**/.gitignore");
console.log(isIgnored('some/file'));// Suppress errors when encountering unreadable directories
const isIgnored = await isIgnoredByIgnoreFiles("**/.eslintignore", {suppressErrors: true});// Limit search depth and concurrency
const isIgnored = await isIgnoredByIgnoreFiles("**/.prettierignore", {
deep: 3,
concurrency: 4
});Returns a (path: URL | string) => boolean indicating whether a given path is ignored via the ignore files.
This is a more generic form of the isGitIgnoredSync function, allowing you to find ignore files with a compatible syntax. For instance, this works with Babel's .babelignore, Prettier's .prettierignore, or ESLint's .eslintignore files.
See isIgnoredByIgnoreFiles for patterns and options.
import {isIgnoredByIgnoreFilesSync} from 'globby';
const isIgnored = isIgnoredByIgnoreFilesSync("**/.gitignore");
console.log(isIgnored('some/file'));Just a quick overview.
*matches any number of characters, but not/?matches a single character, but not/**matches any number of characters, including/, as long as it's the only thing in a path part{}allows for a comma-separated list of "or" expressions!at the beginning of a pattern will negate the match
Globby supports negation patterns to exclude files. There are two ways to use them:
With positive patterns:
await globby(['src/**/*.js', '!src/**/*.test.js']);
// Matches all .js files except test filesNegation-only patterns:
await globby(['!*.json', '!*.xml'], {cwd: 'config'});
// Matches all files in config/ except .json and .xml filesWhen using only negation patterns, globby implicitly prepends **/* to match all files, then applies the negations. This means ['!*.json', '!*.xml'] is equivalent to ['**/*', '!*.json', '!*.xml'].
Note: The prepended **/* pattern respects the dot option. By default, dotfiles (files starting with .) are not matched unless you set dot: true.
Various patterns and expected matches.
- multimatch - Match against a list instead of the filesystem
- matcher - Simple wildcard matching
- del - Delete files and directories
- make-dir - Make a directory and its parents if needed
