šŸŒœ
šŸŒž
globby

globby

v13.1.2

User-friendly glob matching

npm install globby

README

globby

User-friendly glob matching

Based on fast-glob but adds a bunch of useful features.

Features

  • Promise API
  • Multiple patterns
  • Negated patterns: ['foo*', '!foobar']
  • Expands directories: foo ā†’ foo/**/*
  • Supports .gitignore and similar ignore config files
  • Supports URL as cwd

Install

$ npm install globby

Usage

ā”œā”€ā”€ unicorn
ā”œā”€ā”€ cake
ā””ā”€ā”€ rainbow
import {globby} from 'globby';

const paths = await globby(['*', '!cake']);

console.log(paths);
//=> ['unicorn', 'rainbow']

API

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().

globby(patterns, options?)

Returns a Promise<string[]> of matching paths.

patterns

Type: string | string[]

See supported minimatch patterns.

options

Type: object

See the fast-glob options in addition to the ones below.

expandDirectories

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';

(async () => {
    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.

gitignore

Type: boolean
Default: false

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

ignoreFiles

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.

globbySync(patterns, options?)

Returns string[] of matching paths.

globbyStream(patterns, options?)

Returns a stream.Readable of matching paths.

Since Node.js 10, readable streams are iterable, so you can loop over glob matches in a for await...of loop like this:

import {globbyStream} from 'globby';

(async () => {
    for await (const path of globbyStream('*.tmp')) {
        console.log(path);
    }
})();

generateGlobTasks(patterns, options?)

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.

generateGlobTasksSync(patterns, options?)

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.

isDynamicPattern(patterns, options?)

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.

isGitIgnored(options?)

Returns a Promise<(path: URL | string) => boolean> indicating whether a given path is ignored via a .gitignore file.

Takes cwd?: URL | string as options.

import {isGitIgnored} from 'globby';

const isIgnored = await isGitIgnored();

console.log(isIgnored('some/file'));

isGitIgnoredSync(options?)

Returns a (path: URL | string) => boolean indicating whether a given path is ignored via a .gitignore file.

Takes cwd?: URL | string as options.

Globbing patterns

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

Various patterns and expected matches.

globby for enterprise

Available as part of the Tidelift Subscription.

The maintainers of globby and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

  • 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

Release Notes

13.1.2
By Sindre Sorhus ā€¢ Published on June 12, 2022
  • Make ignoreFiles option accept readonly arrays (#235) 810caae

https://github.com/sindresorhus/globby/compare/v13.1.1...v13.1.2

13.1.1
By Sindre Sorhus ā€¢ Published on February 2, 2022
  • Fix duplicated result when using globstar (#231) f9d35ae

https://github.com/sindresorhus/globby/compare/v13.1.0...v13.1.1

13.1.0
By Sindre Sorhus ā€¢ Published on January 25, 2022
13.0.0
By Sindre Sorhus ā€¢ Published on January 24, 2022

Breaking

  • Rename generateGlobTasks to generateGlobTasksSync (#221) 51c8f68
  • Remove ignore option for isGitIgnored and isGitIgnoredSync (#225) 2e43cc4
    • This option never worked correctly.

Improvements

  • Improve performance with mutiple patterns (#222) 04fbd5b
  • Add async generateGlobTasks method (#221) 51c8f68

Fixes

  • Fix bug with objectMode option (#210) 1852fc5

https://github.com/sindresorhus/globby/compare/v12.2.0...v13.0.0

12.2.0
By Sindre Sorhus ā€¢ Published on January 17, 2022
  • Work around TypeScript type problem with URL global (#206) 1224230
  • Accept URL in function returned by isGitIgnored (#207) a9fc794

https://github.com/sindresorhus/globby/compare/v12.1.0...v12.2.0

12.1.0
By Sindre Sorhus ā€¢ Published on January 15, 2022
  • Support URL for the cwd option (#201) 73c0aca

https://github.com/sindresorhus/globby/compare/v12.0.2...v12.1.0

12.0.2
By Sindre Sorhus ā€¢ Published on August 24, 2021
  • Ensure async method is completely async e167725

https://github.com/sindresorhus/globby/compare/v12.0.1...v12.0.2

12.0.1
By Sindre Sorhus ā€¢ Published on August 16, 2021
12.0.0
By Sindre Sorhus ā€¢ Published on July 22, 2021

Breaking

  • Require Node.js 12.20 (#181) 5c32b4a
  • This package is now pure ESM. Please read this.
  • This package now uses named exports instead of a default export
    • globby ā†’ {globby}
    • globby.sync ā†’ {globbySync}
    • globby.stream ā†’ {globbyStream}
    • globby.generateGlobTasks ā†’ {generateGlobTasks}
    • globby.hasMagic ā†’ {isDynamicPattern}
    • globby.gitignore ā†’ {isGitIgnored}
    • globby.gitignore.sync ā†’ {isGitIgnoredSync} ```diff

-const globby = require('globby'); +import {globby} from 'globby';

```

https://github.com/sindresorhus/globby/compare/v11.0.4...v12.0.0

11.1.0
By Sindre Sorhus ā€¢ Published on January 8, 2022
  • Update dependencies to fix some npm audit notices

https://github.com/sindresorhus/globby/compare/v11.0.4...v11.1.0

General

License
MIT
Typescript Types
Built-in
Tree-shakeable
Yes

Popularity

GitHub Stargazers
2,131
Community Interest
1,991
Number of Forks
144

Maintenance

Commits
10/219/22035
Last Commit
Jun 12, 2022
Open Issues
26
Closed Issues
87
Open Pull Requests
1
Closed Pull Requests
45

Versions

Versions Released
10/219/2205
Latest Version Released
Current Tags
latest13.1.2
version1111.1.0

Contributors

sindresorhus
sindresorhus
Commits: 85
UltCombo
UltCombo
Commits: 14
kevva
kevva
Commits: 9
schnittstabil
schnittstabil
Commits: 5
marionebl
marionebl
Commits: 4
BendingBender
BendingBender
Commits: 2
jamiekyle-eb
jamiekyle-eb
Commits: 2
LKummer
LKummer
Commits: 2
rwjblue
rwjblue
Commits: 1
brandon93s
brandon93s
Commits: 1
pvdlg
pvdlg
Commits: 1
futpib
futpib
Commits: 1
tbroadley
tbroadley
Commits: 1
sinchang
sinchang
Commits: 1
coreyfarrell
coreyfarrell
Commits: 1