Showing preview only (237K chars total). Download the full file or copy to clipboard to get everything.
Repository: isaacs/node-glob
Branch: main
Commit: 5ce582a3365e
Files: 75
Total size: 220.1 KB
Directory structure:
gitextract_aolffhr8/
├── .github/
│ └── workflows/
│ ├── ci.yml
│ └── typedoc.yml
├── .gitignore
├── .oxlint.json
├── .prettierignore
├── .prettierrc.json
├── .taprc
├── .tshy/
│ ├── build.json
│ ├── commonjs.json
│ └── esm.json
├── CONTRIBUTING.md
├── LICENSE.md
├── README.md
├── benchclean.cjs
├── benchmark.sh
├── changelog.md
├── examples/
│ ├── g.js
│ └── usr-local.js
├── make-benchmark-fixture.sh
├── package.json
├── patterns.sh
├── prof.sh
├── scripts/
│ ├── build.sh
│ └── make-big-tree.js
├── src/
│ ├── glob.ts
│ ├── has-magic.ts
│ ├── ignore.ts
│ ├── index.ts
│ ├── pattern.ts
│ ├── processor.ts
│ └── walker.ts
├── tap-snapshots/
│ └── test/
│ ├── bin.ts.test.cjs
│ ├── pattern.ts.test.cjs
│ └── root.ts.test.cjs
├── test/
│ ├── 00-setup.ts
│ ├── absolute-must-be-strings.ts
│ ├── absolute.ts
│ ├── bash-comparison.ts
│ ├── bash-results.ts
│ ├── broken-symlink.ts
│ ├── custom-fs.ts
│ ├── custom-ignore.ts
│ ├── cwd-noent.ts
│ ├── cwd-test.ts
│ ├── dot-relative.ts
│ ├── empty-set.ts
│ ├── escape.ts
│ ├── follow.ts
│ ├── has-magic.ts
│ ├── ignore.ts
│ ├── include-child-matches.ts
│ ├── mark.ts
│ ├── match-base.ts
│ ├── match-parent.ts
│ ├── match-root.ts
│ ├── max-depth.ts
│ ├── memfs.ts
│ ├── nocase-magic-only.ts
│ ├── nodir.ts
│ ├── oom.ts
│ ├── pattern.ts
│ ├── platform.ts
│ ├── progra-tilde.ts
│ ├── readme-issue.ts
│ ├── realpath.ts
│ ├── root.ts
│ ├── signal.ts
│ ├── slash-cwd.ts
│ ├── stat.ts
│ ├── stream.ts
│ ├── url-cwd.ts
│ ├── windows-paths-fs.ts
│ └── windows-paths-no-escape.ts
├── tsconfig.json
└── typedoc.json
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/workflows/ci.yml
================================================
name: CI
on:
push:
branches: ["main"]
pull_request_target:
paths:
- 'src/**'
- 'test/**'
- '*.json'
- '*.js'
- '*.ts'
- 'lib/**'
- 'scripts/**'
- '.github/workflows/ci.yml'
- 'package.json'
workflow_dispatch:
permissions:
contents: read
jobs:
build:
strategy:
matrix:
node-version: [18.x, 20.x, 22.x, 24.x, 25.x]
platform:
- os: ubuntu-latest
shell: bash
- os: macos-latest
shell: bash
- os: windows-latest
shell: bash
- os: windows-latest
shell: powershell
fail-fast: false
runs-on: ${{ matrix.platform.os }}
defaults:
run:
shell: ${{ matrix.platform.shell }}
steps:
- name: Checkout Repository
uses: actions/checkout@v6
- name: Use Nodejs ${{ matrix.node-version }}
uses: actions/setup-node@v6
with:
node-version: ${{ matrix.node-version }}
- name: Install dependencies
run: npm install
- name: Run Tests Windows (incomplete coverage)
if: matrix.platform.os == 'windows-latest'
run: npm test -- -c -t0 --allow-incomplete-coverage
- name: Run Tests Unix (complete coverage)
if: matrix.platform.os != 'windows-latest'
run: npm test -- -c -t0
================================================
FILE: .github/workflows/typedoc.yml
================================================
name: typedoc
on:
push:
branches: ["main"]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Use Nodejs ${{ matrix.node-version }}
uses: actions/setup-node@v6
with:
node-version: 20.x
- name: Install dependencies
run: npm install
- name: Generate typedocs
run: npm run typedoc
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Upload artifact
uses: actions/upload-pages-artifact@v4
with:
path: './docs'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
================================================
FILE: .gitignore
================================================
.*.swp
/deleteme
/old
/*.tap
/dist
/node_modules
/v8.log
/profile.txt
/nyc_output
/.nyc_output
/coverage
/test/fixtures
/bench-working-dir
/scripts/fixture
================================================
FILE: .oxlint.json
================================================
{
"$schema": "./node_modules/oxlint/configuration_schema.json",
"categories": {},
"options": {
"typeAware": true,
"typeCheck": true
},
"rules": {
"no-unneeded-ternary": "error",
"unicorn/prefer-ternary": "error",
"unicorn/prefer-logical-operator-over-ternary": "error",
"no-unused-vars": [
"warn",
{
"argsIgnorePattern": "^_",
"varsIgnorePattern": "^_",
"caughtErrorsIgnorePattern": "^_"
}
],
"no-console": "error",
"no-alert": "error",
"no-param-reassign": "error",
"prefer-template": "error",
"complexity": [
"error",
{
"max": 50
}
],
"no-unused-expressions": [
"error",
{
"allowShortCircuit": true
}
],
"guard-for-in": "error",
"array-callback-return": [
"error",
{
"allowImplicit": true
}
],
"quotes": [
"error",
"single",
{
"avoidEscape": true
}
],
"no-return-await": "error",
"import/namespace": "off",
"import/no-unresolved": "off",
"no-control-regex": "off",
"jsdoc/check-tag-names": "off",
"jsdoc/require-yields": "off",
"no-useless-rename": "off",
"no-constant-binary-expression": "off",
"vitest/hoisted-apis-on-top": "off",
"vitest/no-conditional-tests": "off",
"no-unsafe-optional-chaining": "off",
"no-eval": "off",
"no-import-assign": "off",
"typescript/no-duplicate-type-constituents": "off"
},
"overrides": [
{
"files": ["**/*.ts", "**/*.tsx", "**/*.d.ts"],
"rules": {
"typescript/ban-ts-comment": "error",
"typescript/consistent-type-imports": [
"error",
{
"disallowTypeAnnotations": false
}
],
"typescript/no-unnecessary-type-assertion": "error",
"typescript/prefer-for-of": "error",
"typescript/no-floating-promises": [
"error",
{
"ignoreVoid": true
}
],
"typescript/no-dynamic-delete": "error",
"typescript/no-unsafe-member-access": "error",
"typescript/unbound-method": "error",
"typescript/no-explicit-any": "error",
"typescript/no-empty-function": "off",
"typescript/prefer-optional-chain": ["error"],
"typescript/no-redundant-type-constituents": "off",
"typescript/restrict-template-expressions": "off",
"typescript/await-thenable": "warn",
"typescript/no-base-to-string": "warn"
}
},
{
"files": ["**/*.js", "**/*.mjs", "**/*.cjs"],
"rules": {
"typescript/ban-ts-comment": "off",
"typescript/consistent-type-imports": "off",
"typescript/prefer-optional-chain": "off",
"typescript/no-unnecessary-type-assertion": "off",
"typescript/prefer-for-of": "off",
"typescript/no-floating-promises": "off",
"typescript/no-dynamic-delete": "off",
"typescript/no-unsafe-member-access": "off",
"typescript/unbound-method": "off",
"typescript/no-explicit-any": "off"
}
},
{
"files": [
"**/*.test.ts",
"**/*.test.tsx",
"**/*.test.js",
"**/*.test.jsx",
"**/test/**",
"**/tests/**"
],
"rules": {
"typescript/ban-ts-comment": "off",
"typescript/explicit-function-return-type": "off",
"no-unused-expressions": "off",
"typescript/no-unused-expressions": "off",
"typescript/no-unnecessary-type-assertion": "off",
"typescript/no-unsafe-member-access": "off",
"typescript/no-explicit-any": "off",
"typescript/no-non-null-assertion": "off",
"typescript/no-floating-promises": "off",
"typescript/unbound-method": "off",
"max-lines": "off",
"complexity": "off",
"typescript/prefer-optional-chain": "off",
"typescript/no-misused-spread": "off",
"typescript/require-array-sort-compare": "off",
"typescript/no-base-to-string": "off",
"typescript/await-thenable": "off"
}
},
{
"files": ["*.tsx"],
"rules": {
"jsdoc/require-jsdoc": "off"
}
},
{
"files": [
"*.config.js",
"*.config.mjs",
"*.config.ts",
"vite.config.ts",
".size-limit.js",
"**/test/**",
"**/*.test.ts",
"**/*.test.mts",
"**/*.test.cts",
"**/*.test.mjs",
"**/*.test.cjs"
],
"rules": {
"no-console": "off",
"max-lines": "off"
}
}
],
"settings": {
"jsx-a11y": {
"components": {},
"attributes": {}
},
"next": {
"rootDir": []
},
"react": {
"formComponents": [],
"linkComponents": [],
"componentWrapperFunctions": []
},
"jsdoc": {
"ignorePrivate": false,
"ignoreInternal": false,
"ignoreReplacesDocs": true,
"overrideReplacesDocs": true,
"augmentsExtendsReplacesDocs": false,
"implementsReplacesDocs": false,
"exemptDestructuredRootsFromChecks": false,
"tagNamePreference": {}
},
"vitest": {
"typecheck": false
}
},
"env": {
"builtin": true
},
"globals": {},
"ignorePatterns": [
"**/fixtures/**",
"**/.tap/**",
"**/docs/**",
"**/tap-snapshots/**"
]
}
================================================
FILE: .prettierignore
================================================
/node_modules
/tsconfig.json
/package-lock.json
/package.json
/LICENSE.md
/example
/.github
/dist
/.env
/tap-snapshots
/.nyc_output
/coverage
/benchmark
/.tap
/test/fixture
/test/fixtures
/.tshy
/docs
================================================
FILE: .prettierrc.json
================================================
{
"experimentalTernaries": true,
"semi": false,
"printWidth": 75,
"tabWidth": 2,
"useTabs": false,
"singleQuote": true,
"jsxSingleQuote": false,
"bracketSameLine": true,
"arrowParens": "avoid",
"endOfLine": "lf"
}
================================================
FILE: .taprc
================================================
before: "test/00-setup.ts"
================================================
FILE: .tshy/build.json
================================================
{
"extends": "../tsconfig.json",
"compilerOptions": {
"rootDir": "../src",
"module": "nodenext",
"moduleResolution": "nodenext"
}
}
================================================
FILE: .tshy/commonjs.json
================================================
{
"extends": "./build.json",
"include": [
"../src/**/*.ts",
"../src/**/*.cts",
"../src/**/*.tsx",
"../src/**/*.json"
],
"exclude": [
"../src/**/*.mts",
"../src/package.json"
],
"compilerOptions": {
"outDir": "../.tshy-build/commonjs"
}
}
================================================
FILE: .tshy/esm.json
================================================
{
"extends": "./build.json",
"include": [
"../src/**/*.ts",
"../src/**/*.mts",
"../src/**/*.tsx",
"../src/**/*.json"
],
"exclude": [
"../src/package.json"
],
"compilerOptions": {
"outDir": "../.tshy-build/esm"
}
}
================================================
FILE: CONTRIBUTING.md
================================================
Any change to behavior (including bugfixes) must come with a test.
Patches that fail tests or reduce performance will be rejected.
```sh
# to run tests
npm test
# to re-generate test fixtures
npm run test-regen
# to benchmark against bash/zsh
npm run bench
# to profile javascript
npm run prof
```
================================================
FILE: LICENSE.md
================================================
All packages under `src/` are licensed according to the terms in
their respective `LICENSE` or `LICENSE.md` files.
The remainder of this project is licensed under the Blue Oak
Model License, as follows:
-----
# Blue Oak Model License
Version 1.0.0
## Purpose
This license gives everyone as much permission to work with
this software as possible, while protecting contributors
from liability.
## Acceptance
In order to receive this license, you must agree to its
rules. The rules of this license are both obligations
under that agreement and conditions to your license.
You must not do anything with this software that triggers
a rule that you cannot or will not follow.
## Copyright
Each contributor licenses you to do everything with this
software that would otherwise infringe that contributor's
copyright in it.
## Notices
You must ensure that everyone who gets a copy of
any part of this software from you, with or without
changes, also gets the text of this license or a link to
<https://blueoakcouncil.org/license/1.0.0>.
## Excuse
If anyone notifies you in writing that you have not
complied with [Notices](#notices), you can keep your
license by taking all practical steps to comply within 30
days after the notice. If you do not do so, your license
ends immediately.
## Patent
Each contributor licenses you to do everything with this
software that would otherwise infringe any patent claims
they can license or become able to license.
## Reliability
No contributor can revoke this license.
## No Liability
***As far as the law allows, this software comes as is,
without any warranty or condition, and no contributor
will be liable to anyone for any damages related to this
software or this license, under any kind of legal claim.***
================================================
FILE: README.md
================================================
# Glob
Match files using the patterns the shell uses.
The most correct and second fastest glob implementation in
JavaScript. (See [**Comparison to Other JavaScript Glob
Implementations**](#comparisons-to-other-fnmatchglob-implementations)
at the bottom of this readme.)
## Usage
Install with npm
```
npm i glob
```
> [!NOTE]
> The npm package name is _not_ `node-glob` that's a
> different thing that was abandoned years ago. Just `glob`.
```js
// load using import
import { glob, globSync, globStream, globStreamSync, Glob } from 'glob'
// or using commonjs, that's fine, too
const {
glob,
globSync,
globStream,
globStreamSync,
Glob,
} = require('glob')
// the main glob() and globSync() resolve/return array of filenames
// all js files, but don't look in node_modules
const jsfiles = await glob('**/*.js', { ignore: 'node_modules/**' })
// pass in a signal to cancel the glob walk
const stopAfter100ms = await glob('**/*.css', {
signal: AbortSignal.timeout(100),
})
// multiple patterns supported as well
const images = await glob(['css/*.{png,jpeg}', 'public/*.{png,jpeg}'])
// but of course you can do that with the glob pattern also
// the sync function is the same, just returns a string[] instead
// of Promise<string[]>
const imagesAlt = globSync('{css,public}/*.{png,jpeg}')
// you can also stream them, this is a Minipass stream
const filesStream = globStream(['**/*.dat', 'logs/**/*.log'])
// construct a Glob object if you wanna do it that way, which
// allows for much faster walks if you have to look in the same
// folder multiple times.
const g = new Glob('**/foo', {})
// glob objects are async iterators, can also do globIterate() or
// g.iterate(), same deal
for await (const file of g) {
console.log('found a foo file:', file)
}
// pass a glob as the glob options to reuse its settings and caches
const g2 = new Glob('**/bar', g)
// sync iteration works as well
for (const file of g2) {
console.log('found a bar file:', file)
}
// you can also pass withFileTypes: true to get Path objects
// these are like a fs.Dirent, but with some more added powers
// check out https://isaacs.github.io/path-scurry/classes/PathBase.html
// for more info on their API
const g3 = new Glob('**/baz/**', { withFileTypes: true })
g3.stream().on('data', path => {
console.log(
'got a path object',
path.fullpath(),
path.isDirectory(),
path.readdirSync().map(e => e.name),
)
})
// if you use stat:true and withFileTypes, you can sort results
// by things like modified time, filter by permission mode, etc.
// All Stats fields will be available in that case. Slightly
// slower, though.
// For example:
const results = await glob('**', { stat: true, withFileTypes: true })
const timeSortedFiles = results
.sort((a, b) => a.mtimeMs - b.mtimeMs)
.map(path => path.fullpath())
const groupReadableFiles = results
.filter(path => path.mode & 0o040)
.map(path => path.fullpath())
// custom ignores can be done like this, for example by saying
// you'll ignore all markdown files, and all folders named 'docs'
const customIgnoreResults = await glob('**', {
ignore: {
ignored: p => /\.md$/.test(p.name),
childrenIgnored: p => p.isNamed('docs'),
},
})
// another fun use case, only return files with the same name as
// their parent folder, plus either `.ts` or `.js`
const folderNamedModules = await glob('**/*.{ts,js}', {
ignore: {
ignored: p => {
const pp = p.parent
return !(p.isNamed(pp.name + '.ts') || p.isNamed(pp.name + '.js'))
},
},
})
// find all files edited in the last hour, to do this, we ignore
// all of them that are more than an hour old
const newFiles = await glob('**', {
// need stat so we have mtime
stat: true,
// only want the files, not the dirs
nodir: true,
ignore: {
ignored: p => {
return new Date() - p.mtime > 60 * 60 * 1000
},
// could add similar childrenIgnored here as well, but
// directory mtime is inconsistent across platforms, so
// probably better not to, unless you know the system
// tracks this reliably.
},
})
```
> [!NOTE]
> Glob patterns should always use `/` as a path separator,
> even on Windows systems, as `\` is used to escape glob
> characters. If you wish to use `\` as a path separator _instead
> of_ using it as an escape character on Windows platforms, you may
> set `windowsPathsNoEscape:true` in the options. In this mode,
> special glob characters cannot be escaped, making it impossible
> to match a literal `*` `?` and so on in filenames.
## Command Line Interface
The glob CLI has been moved to the `glob-bin` package, and must
be installed separately, as of version 13.
```
npm install glob-bin
```
## `glob(pattern: string | string[], options?: GlobOptions) => Promise<string[] | Path[]>`
Perform an asynchronous glob search for the pattern(s) specified.
Returns
[Path](https://isaacs.github.io/path-scurry/classes/PathBase)
objects if the `withFileTypes` option is set to `true`. See below
for full options field desciptions.
## `globSync(pattern: string | string[], options?: GlobOptions) => string[] | Path[]`
Synchronous form of `glob()`.
Alias: `glob.sync()`
## `globIterate(pattern: string | string[], options?: GlobOptions) => AsyncGenerator<string>`
Return an async iterator for walking glob pattern matches.
Alias: `glob.iterate()`
## `globIterateSync(pattern: string | string[], options?: GlobOptions) => Generator<string>`
Return a sync iterator for walking glob pattern matches.
Alias: `glob.iterate.sync()`, `glob.sync.iterate()`
## `globStream(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`
Return a stream that emits all the strings or `Path` objects and
then emits `end` when completed.
Alias: `glob.stream()`
## `globStreamSync(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`
Syncronous form of `globStream()`. Will read all the matches as
fast as you consume them, even all in a single tick if you
consume them immediately, but will still respond to backpressure
if they're not consumed immediately.
Alias: `glob.stream.sync()`, `glob.sync.stream()`
## `hasMagic(pattern: string | string[], options?: GlobOptions) => boolean`
Returns `true` if the provided pattern contains any "magic" glob
characters, given the options provided.
Brace expansion is not considered "magic" unless the
`magicalBraces` option is set, as brace expansion just turns one
string into an array of strings. So a pattern like `'x{a,b}y'`
would return `false`, because `'xay'` and `'xby'` both do not
contain any magic glob characters, and it's treated the same as
if you had called it on `['xay', 'xby']`. When
`magicalBraces:true` is in the options, brace expansion _is_
treated as a pattern having magic.
## `escape(pattern: string, options?: GlobOptions) => string`
Escape all magic characters in a glob pattern, so that it will
only ever match literal strings
If the `windowsPathsNoEscape` option is used, then characters are
escaped by wrapping in `[]`, because a magic character wrapped in
a character class can only be satisfied by that exact character.
Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot
be escaped or unescaped.
## `unescape(pattern: string, options?: GlobOptions) => string`
Un-escape a glob string that may contain some escaped characters.
If the `windowsPathsNoEscape` option is used, then square-brace
escapes are removed, but not backslash escapes. For example, it
will turn the string `'[*]'` into `*`, but it will not turn
`'\\*'` into `'*'`, because `\` is a path separator in
`windowsPathsNoEscape` mode.
When `windowsPathsNoEscape` is not set, then both brace escapes
and backslash escapes are removed.
Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot
be escaped or unescaped.
## Class `Glob`
An object that can perform glob pattern traversals.
### `const g = new Glob(pattern: string | string[], options: GlobOptions)`
Options object is required.
See full options descriptions below.
> [!NOTE]
> A previous `Glob` object can be passed as the
> `GlobOptions` to another `Glob` instantiation to re-use settings
> and caches with a new pattern.
Traversal functions can be called multiple times to run the walk
again.
### `g.stream()`
Stream results asynchronously.
### `g.streamSync()`
Stream results synchronously.
### `g.iterate()`
Default async iteration function. Returns an AsyncGenerator that
iterates over the results.
### `g.iterateSync()`
Default sync iteration function. Returns a Generator that
iterates over the results.
### `g.walk()`
Returns a Promise that resolves to the results array.
### `g.walkSync()`
Returns a results array.
### Properties
All options are stored as properties on the `Glob` object.
- `opts` The options provided to the constructor.
- `patterns` An array of parsed immutable `Pattern` objects.
## Options
Exported as `GlobOptions` TypeScript interface. A `GlobOptions`
object may be provided to any of the exported methods, and must
be provided to the `Glob` constructor.
All options are optional, boolean, and false by default, unless
otherwise noted.
All resolved options are added to the Glob object as properties.
If you are running many `glob` operations, you can pass a Glob
object as the `options` argument to a subsequent operation to
share the previously loaded cache.
- `cwd` String path or `file://` string or URL object. The
current working directory in which to search. Defaults to
`process.cwd()`. See also: "Windows, CWDs, Drive Letters, and
UNC Paths", below.
This option may be either a string path or a `file://` URL
object or string.
- `root` A string path resolved against the `cwd` option, which
is used as the starting point for absolute patterns that start
with `/`, (but not drive letters or UNC paths on Windows).
To start absolute and non-absolute patterns in the same path,
you can use `{root:''}`. However, be aware that on Windows
systems, a pattern like `x:/*` or `//host/share/*` will
_always_ start in the `x:/` or `//host/share` directory,
regardless of the `root` setting.
> [!NOTE] This _doesn't_ necessarily limit the walk to the
> `root` directory, and doesn't affect the cwd starting point
> for non-absolute patterns. A pattern containing `..` will
> still be able to traverse out of the root directory, if it
> is not an actual root directory on the filesystem, and any
> non-absolute patterns will be matched in the `cwd`. For
> example, the pattern `/../*` with `{root:'/some/path'}`
> will return all files in `/some`, not all files in
> `/some/path`. The pattern `*` with `{root:'/some/path'}`
> will return all the entries in the cwd, not the entries in
> `/some/path`.
- `windowsPathsNoEscape` Use `\\` as a path separator _only_, and
_never_ as an escape character. If set, all `\\` characters are
replaced with `/` in the pattern.
> [!NOTE]
> This makes it **impossible** to match against paths
> containing literal glob pattern characters, but allows matching
> with patterns constructed using `path.join()` and
> `path.resolve()` on Windows platforms, mimicking the (buggy!)
> behavior of Glob v7 and before on Windows. Please use with
> caution, and be mindful of [the caveat below about Windows
> paths](#windows). (For legacy reasons, this is also set if
> `allowWindowsEscape` is set to the exact value `false`.)
- `dot` Include `.dot` files in normal matches and `globstar`
matches. Note that an explicit dot in a portion of the pattern
will always match dot files.
- `magicalBraces` Treat brace expansion like `{a,b}` as a "magic"
pattern. Has no effect if {@link nobrace} is set.
Only has effect on the {@link hasMagic} function, no effect on
glob pattern matching itself.
- `dotRelative` Prepend all relative path strings with `./` (or
`.\` on Windows).
Without this option, returned relative paths are "bare", so
instead of returning `'./foo/bar'`, they are returned as
`'foo/bar'`.
Relative patterns starting with `'../'` are not prepended with
`./`, even if this option is set.
- `mark` Add a `/` character to directory matches. Note that this
requires additional stat calls.
- `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.
- `noglobstar` Do not match `**` against multiple filenames. (Ie,
treat it as a normal `*` instead.)
- `noext` Do not match "extglob" patterns such as `+(a|b)`.
- `nocase` Perform a case-insensitive match. This defaults to
`true` on macOS and Windows systems, and `false` on all others.
> [!NOTE]
> `nocase` should only be explicitly set when it is known that
> the filesystem's case sensitivity differs from the platform
> default. If set `true` on case-sensitive file systems, or
> `false` on case-insensitive file systems, then the walk may
> return more or less results than expected.
>
> As a shortcut to avoid excessive `RegExp` creations, `Glob`
> will use string portions as-is to `readdir()` calls while doing
> its traversal. If you are setting a `nocase: true` match on a
> file system that is in fact case sensitive, then this will
> result in matches not being found that you might expect,
> because for example the pattern `Foo/*` will fail to read the
> `FOO/` or `foo/` directories.
>
> On the other hand, if you set `nocase: false` on a
> case-_insensitive_ system, then the opposite problem occurs:
> `Foo/*` will match `foo/bar`, but because we only detect the
> existence of the `foo/` folder by successfully performing a
> `readdir`, there's no way to know what the "real" case is, and
> the match will be reported as `Foo/bar`, using the case of the
> string portion of the glob pattern.
>
> The default is usually correct, however it _is_ possible to
> mount file systems with a different case-sensitivity from the
> host system. If you know this is the case, set this flag
> appropriately to the file system you are searching.
- `maxDepth` Specify a number to limit the depth of the directory
traversal to this many levels below the `cwd`.
- `matchBase` Perform a basename-only match if the pattern does
not contain any slash characters. That is, `*.js` would be
treated as equivalent to `**/*.js`, matching all js files in
all directories.
- `nodir` Do not match directories, only files. (Note: to match
_only_ directories, put a `/` at the end of the pattern.)
> [!NOTE]
> When `follow` and `nodir` are both set, then symbolic
> links to directories are also omitted.
- `stat` Call `lstat()` on all entries, whether required or not
to determine whether it's a valid match. When used with
`withFileTypes`, this means that matches will include data such
as modified time, permissions, and so on. Note that this will
incur a performance cost due to the added system calls.
- `ignore` string or string[], or an object with `ignored` and
`childrenIgnored` methods.
If a string or string[] is provided, then this is treated as
a glob pattern or array of glob patterns to exclude from
matches. To ignore all children within a directory, as well
as the entry itself, append `'/**'` to the ignore pattern.
If an object is provided that has `ignored(path)` and/or
`childrenIgnored(path)` methods, then these methods will be
called to determine whether any Path is a match or if its
children should be traversed, respectively.
The `path` argument to the methods will be a
[`path-scurry`](https://isaacs.github.io/path-scurry/index.html)
[`Path`](https://isaacs.github.io/path-scurry/classes/PathBase)
object, which extends
[`fs.Dirent`](https://nodejs.org/docs/latest/api/fs.html#class-fsdirent)
with additional useful methods like
[`.fullpath()`](https://isaacs.github.io/path-scurry/classes/PathBase.html#fullpath),
[`.relative()`](https://isaacs.github.io/path-scurry/classes/PathBase.html#relative),
and more.
> [!NOTE]
> `ignore` patterns are _always_ in `dot:true` mode,
> regardless of any other settings.
- `follow` Follow symlinked directories when expanding `**`
patterns. This can result in a lot of duplicate references in
the presence of cyclic links, and make performance quite bad.
By default, a `**` in a pattern will follow 1 symbolic link if
it is not the first item in the pattern, or none if it is the
first item in the pattern, following the same behavior as Bash.
> [!NOTE]
> When `follow` and `nodir` are both set, then symbolic
> links to directories are also omitted.
- `realpath` Set to true to call `fs.realpath` on all of the
results. In the case of an entry that cannot be resolved, the
entry is omitted. This incurs a slight performance penalty, of
course, because of the added system calls.
- `absolute` Set to true to always receive absolute paths for
matched files. Set to `false` to always receive relative paths
for matched files.
By default, when this option is not set, absolute paths are
returned for patterns that are absolute, and otherwise paths
are returned that are relative to the `cwd` setting.
This does _not_ make an extra system call to get the realpath,
it only does string path resolution.
`absolute` may not be used along with `withFileTypes`.
- `posix` Set to true to use `/` as the path separator in
returned results. On POSIX systems, this has no effect. On
Windows systems, this will return `/` delimited path results,
and absolute paths will be returned in their fully resolved UNC
path form, e.g. instead of `'C:\\foo\\bar'`, it will return
`//?/C:/foo/bar`.
- `platform` Defaults to the value of `process.platform` if
available, or `'linux'` if not. Setting `platform:'win32'` on
non-Windows systems may cause strange behavior.
- `withFileTypes` Return
[`path-scurry`](http://npm.im/path-scurry)
[`Path`](https://isaacs.github.io/path-scurry/classes/PathBase.html)
objects instead of strings. These are similar to a NodeJS
`fs.Dirent` object, but with additional methods and properties.
`withFileTypes` may not be used along with `absolute`.
- `signal` An AbortSignal which will cancel the Glob walk when
triggered.
- `fs` An override object to pass in custom filesystem methods.
See [`path-scurry`
docs](https://isaacs.github.io/path-scurry/interfaces/FSOption.html)
for what can be overridden.
- `scurry` A
[`PathScurry`](https://isaacs.github.io/path-scurry/classes/PathScurryBase.html)
object used to traverse the file system. If the `nocase` option
is set explicitly, then any provided `scurry` object must match
this setting.
- `includeChildMatches` boolean, default `true`. Do not match any
children of any matches. For example, the pattern `**\/foo`
would match `a/foo`, but not `a/foo/b/foo` in this mode.
This is especially useful for cases like "find all
`node_modules` folders, but not the ones in `node_modules`".
In order to support this, the `Ignore` implementation must
support an `add(pattern: string)` method. If using the default
`Ignore` class, then this is fine, but if this is set to
`false`, and a custom `Ignore` is provided that does not have
an `add()` method, then it will throw an error.
For example:
```js
const results = await glob(
[
// likely to match first, since it's just a stat
'a/b/c/d/e/f',
// this pattern is more complicated! It must to various readdir()
// calls and test the results against a regular expression, and that
// is certainly going to take a little bit longer.
//
// So, later on, it encounters a match at 'a/b/c/d/e', but it's too
// late to ignore a/b/c/d/e/f, because it's already been emitted.
'a/[bdf]/?/[a-z]/*',
],
{ includeChildMatches: false },
)
```
It's best to only set this to `false` if you can be reasonably
sure that no components of the pattern will potentially match
one another's file system descendants, or if the occasional
included child entry will not cause problems.
> [!NOTE]
> It _only_ ignores matches that would be a descendant
> of a previous match, and only if that descendant is matched
> _after_ the ancestor is encountered. Since the file system walk
> happens in indeterminate order, it's possible that a match will
> already be added before its ancestor, if multiple or braced
> patterns are used.
- `braceExpandMax` number, defaults to `10_000`. This is the
maximum number of `{x,y,...}` patterns to expand. It is very
unlikely that you'll need more than this, and setting it higher
exposes the system to out-of-memory errors.
## Glob Primer
Much more information about glob pattern expansion can be found
by running `man bash` and searching for `Pattern Matching`.
"Globs" are the patterns you type when you do stuff like `ls
*.js` on the command line, or put `build/*` in a `.gitignore`
file.
Before parsing the path part patterns, braced sections are
expanded into a set. Braced sections start with `{` and end with
`}`, with 2 or more comma-delimited sections within. Braced
sections may contain slash characters, so `a{/b/c,bcd}` would
expand into `a/b/c` and `abcd`.
The following characters have special magic meaning when used in
a path portion. With the exception of `**`, none of these match
path separators (ie, `/` on all platforms, and `\` on Windows).
- `*` Matches 0 or more characters in a single path portion.
When alone in a path portion, it must match at least 1
character. If `dot:true` is not specified, then `*` will not
match against a `.` character at the start of a path portion.
- `?` Matches 1 character. If `dot:true` is not specified, then
`?` will not match against a `.` character at the start of a
path portion.
- `[...]` Matches a range of characters, similar to a RegExp
range. If the first character of the range is `!` or `^` then
it matches any character not in the range. If the first
character is `]`, then it will be considered the same as `\]`,
rather than the end of the character class.
- `!(pattern|pattern|pattern)` Matches anything that does not
match any of the patterns provided. May _not_ contain `/`
characters. Similar to `*`, if alone in a path portion, then
the path portion must have at least one character.
- `?(pattern|pattern|pattern)` Matches zero or one occurrence of
the patterns provided. May _not_ contain `/` characters.
- `+(pattern|pattern|pattern)` Matches one or more occurrences of
the patterns provided. May _not_ contain `/` characters.
- `*(a|b|c)` Matches zero or more occurrences of the patterns
provided. May _not_ contain `/` characters.
- `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns
provided. May _not_ contain `/` characters.
- `**` If a "globstar" is alone in a path portion, then it
matches zero or more directories and subdirectories searching
for matches. It does not crawl symlinked directories, unless
`{follow:true}` is passed in the options object. A pattern
like `a/b/**` will only match `a/b` if it is a directory.
Follows 1 symbolic link if not the first item in the pattern,
or 0 if it is the first item, unless `follow:true` is set, in
which case it follows all symbolic links.
`[:class:]` patterns are supported by this implementation, but
`[=c=]` and `[.symbol.]` style class patterns are not.
### Dots
If a file or directory path portion has a `.` as the first
character, then it will not match any glob pattern unless that
pattern's corresponding path part also has a `.` as its first
character.
For example, the pattern `a/.*/c` would match the file at
`a/.b/c`. However the pattern `a/*/c` would not, because `*` does
not start with a dot character.
You can make glob treat dots as normal characters by setting
`dot:true` in the options.
### Basename Matching
If you set `matchBase:true` in the options, and the pattern has
no slashes in it, then it will seek for any file anywhere in the
tree with a matching basename. For example, `*.js` would match
`test/simple/basic.js`.
### Empty Sets
If no matching files are found, then an empty array is returned.
This differs from the shell, where the pattern itself is
returned. For example:
```sh
$ echo a*s*d*f
a*s*d*f
```
## Comparisons to other fnmatch/glob implementations
While strict compliance with the existing standards is a
worthwhile goal, some discrepancies exist between node-glob and
other implementations, and are intentional.
The double-star character `**` is supported by default, unless
the `noglobstar` flag is set. This is supported in the manner of
bsdglob and bash 5, where `**` only has special significance if
it is the only thing in a path part. That is, `a/**/b` will match
`a/x/y/b`, but `a/**b` will not.
> [!NOTE]
> Symlinked directories are not traversed as part of a
> `**`, though their contents may match against subsequent portions
> of the pattern. This prevents infinite loops and duplicates and
> the like. You can force glob to traverse symlinks with `**` by
> setting `{follow:true}` in the options.
There is no equivalent of the `nonull` option. A pattern that
does not find any matches simply resolves to nothing. (An empty
array, immediately ended stream, etc.)
If brace expansion is not disabled, then it is performed before
any other interpretation of the glob pattern. Thus, a pattern
like `+(a|{b),c)}`, which would not be valid in bash or zsh, is
expanded **first** into the set of `+(a|b)` and `+(a|c)`, and
those patterns are checked for validity. Since those two are
valid, matching proceeds.
The character class patterns `[:class:]` (POSIX standard named
classes) style class patterns are supported and Unicode-aware,
but `[=c=]` (locale-specific character collation weight), and
`[.symbol.]` (collating symbol), are not.
### Repeated Slashes
Unlike Bash and zsh, repeated `/` are always coalesced into a
single path separator.
### Comments and Negation
Previously, this module let you mark a pattern as a "comment" if
it started with a `#` character, or a "negated" pattern if it
started with a `!` character.
These options were deprecated in version 5, and removed in
version 6.
To specify things that should not match, use the `ignore` option.
## Windows
**Please only use forward-slashes in glob expressions.**
Though Windows uses either `/` or `\` as its path separator, only
`/` characters are used by this glob implementation. You must use
forward-slashes **only** in glob expressions. Back-slashes will
always be interpreted as escape characters, not path separators.
Results from absolute patterns such as `/foo/*` are mounted onto
the root setting using `path.join`. On Windows, this will by
default result in `/foo/*` matching `C:\foo\bar.txt`.
To automatically coerce all `\` characters to `/` in pattern
strings, **thus making it impossible to escape literal glob
characters**, you may set the `windowsPathsNoEscape` option to
`true`.
### Windows, CWDs, Drive Letters, and UNC Paths
On POSIX systems, when a pattern starts with `/`, any `cwd`
option is ignored, and the traversal starts at `/`, plus any
non-magic path portions specified in the pattern.
On Windows systems, the behavior is similar, but the concept of
an "absolute path" is somewhat more involved.
#### UNC Paths
A UNC path may be used as the start of a pattern on Windows
platforms. For example, a pattern like: `//?/x:/*` will return
all file entries in the root of the `x:` drive. A pattern like
`//ComputerName/Share/*` will return all files in the associated
share.
UNC path roots are always compared case insensitively.
#### Drive Letters
A pattern starting with a drive letter, like `c:/*`, will search
in that drive, regardless of any `cwd` option provided.
If the pattern starts with `/`, and is not a UNC path, and there
is an explicit `cwd` option set with a drive letter, then the
drive letter in the `cwd` is used as the root of the directory
traversal.
For example, `glob('/tmp', { cwd: 'c:/any/thing' })` will return
`['c:/tmp']` as the result.
If an explicit `cwd` option is not provided, and the pattern
starts with `/`, then the traversal will run on the root of the
drive provided as the `cwd` option. (That is, it is the result of
`path.resolve('/')`.)
## Race Conditions
Glob searching, by its very nature, is susceptible to race
conditions, since it relies on directory walking.
As a result, it is possible that a file that exists when glob
looks for it may have been deleted or modified by the time it
returns the result.
By design, this implementation caches all readdir calls that it
makes, in order to cut down on system overhead. However, this
also makes it even more susceptible to races, especially if the
cache object is reused between glob calls.
Users are thus advised not to use a glob result as a guarantee of
filesystem state in the face of rapid changes. For the vast
majority of operations, this is never a problem.
### See Also:
- `man sh`
- `man bash` [Pattern
Matching](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)
- `man 3 fnmatch`
- `man 5 gitignore`
- [minimatch documentation](https://github.com/isaacs/minimatch)
## Glob Logo
Glob's logo was created by [Tanya
Brassie](http://tanyabrassie.com/). Logo files can be found
[here](https://github.com/isaacs/node-glob/tree/master/logo).
The logo is licensed under a [Creative Commons
Attribution-ShareAlike 4.0 International
License](https://creativecommons.org/licenses/by-sa/4.0/).
## Contributing
Any change to behavior (including bugfixes) must come with a
test.
Patches that fail tests or reduce performance will be rejected.
```sh
# 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
```
## Comparison to Other JavaScript Glob Implementations
**tl;dr**
- If you want glob matching that is as faithful as possible to
Bash pattern expansion semantics, and as fast as possible
within that constraint, _use this module_.
- If you are reasonably sure that the patterns you will encounter
are relatively simple, and want the absolutely fastest glob
matcher out there, _use [fast-glob](http://npm.im/fast-glob)_.
- If you are reasonably sure that the patterns you will encounter
are relatively simple, and want the convenience of
automatically respecting `.gitignore` files, _use
[globby](http://npm.im/globby)_.
There are some other glob matcher libraries on npm, but these
three are (in my opinion, as of 2023) the best.
---
**full explanation**
Every library reflects a set of opinions and priorities in the
trade-offs it makes. Other than this library, I can personally
recommend both [globby](http://npm.im/globby) and
[fast-glob](http://npm.im/fast-glob), though they differ in their
benefits and drawbacks.
Both have very nice APIs and are reasonably fast.
`fast-glob` is, as far as I am aware, the fastest glob
implementation in JavaScript today. However, there are many
cases where the choices that `fast-glob` makes in pursuit of
speed mean that its results differ from the results returned by
Bash and other sh-like shells, which may be surprising.
In my testing, `fast-glob` is around 10-20% faster than this
module when walking over 200k files nested 4 directories
deep[1](#fn-webscale). However, there are some inconsistencies
with Bash matching behavior that this module does not suffer
from:
- `**` only matches files, not directories
- `..` path portions are not handled unless they appear at the
start of the pattern
- `./!(<pattern>)` will not match any files that _start_ with
`<pattern>`, even if they do not match `<pattern>`. For
example, `!(9).txt` will not match `9999.txt`.
- Some brace patterns in the middle of a pattern will result in
failing to find certain matches.
- Extglob patterns are allowed to contain `/` characters.
Globby exhibits all of the same pattern semantics as fast-glob,
(as it is a wrapper around fast-glob) and is slightly slower than
node-glob (by about 10-20% in the benchmark test set, or in other
words, anywhere from 20-50% slower than fast-glob). However, it
adds some API conveniences that may be worth the costs.
- Support for `.gitignore` and other ignore files.
- Support for negated globs (ie, patterns starting with `!`
rather than using a separate `ignore` option).
The priority of this module is "correctness" in the sense of
performing a glob pattern expansion as faithfully as possible to
the behavior of Bash and other sh-like shells, with as much speed
as possible.
> [!NOTE]
> Prior versions of `node-glob` are _not_ on this list.
> Former versions of this module are far too slow for any cases
> where performance matters at all, and were designed with APIs
> that are extremely dated by current JavaScript standards.
---
<small id="fn-webscale">[1]: In the cases where this module
returns results and `fast-glob` doesn't, it's even faster, of
course.</small>
### Benchmark Results
The first number is time, smaller is better.
The second number is the count of results returned.
```
--- pattern: '**' ---
~~ sync ~~
node fast-glob sync 0m0.598s 200364
node globby sync 0m0.765s 200364
node current globSync mjs 0m0.683s 222656
node current glob syncStream 0m0.649s 222656
~~ async ~~
node fast-glob async 0m0.350s 200364
node globby async 0m0.509s 200364
node current glob async mjs 0m0.463s 222656
node current glob stream 0m0.411s 222656
--- pattern: '**/..' ---
~~ sync ~~
node fast-glob sync 0m0.486s 0
node globby sync 0m0.769s 200364
node current globSync mjs 0m0.564s 2242
node current glob syncStream 0m0.583s 2242
~~ async ~~
node fast-glob async 0m0.283s 0
node globby async 0m0.512s 200364
node current glob async mjs 0m0.299s 2242
node current glob stream 0m0.312s 2242
--- pattern: './**/0/**/0/**/0/**/0/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.490s 10
node globby sync 0m0.517s 10
node current globSync mjs 0m0.540s 10
node current glob syncStream 0m0.550s 10
~~ async ~~
node fast-glob async 0m0.290s 10
node globby async 0m0.296s 10
node current glob async mjs 0m0.278s 10
node current glob stream 0m0.302s 10
--- pattern: './**/[01]/**/[12]/**/[23]/**/[45]/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.500s 160
node globby sync 0m0.528s 160
node current globSync mjs 0m0.556s 160
node current glob syncStream 0m0.573s 160
~~ async ~~
node fast-glob async 0m0.283s 160
node globby async 0m0.301s 160
node current glob async mjs 0m0.306s 160
node current glob stream 0m0.322s 160
--- pattern: './**/0/**/0/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.502s 5230
node globby sync 0m0.527s 5230
node current globSync mjs 0m0.544s 5230
node current glob syncStream 0m0.557s 5230
~~ async ~~
node fast-glob async 0m0.285s 5230
node globby async 0m0.305s 5230
node current glob async mjs 0m0.304s 5230
node current glob stream 0m0.310s 5230
--- pattern: '**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.580s 200023
node globby sync 0m0.771s 200023
node current globSync mjs 0m0.685s 200023
node current glob syncStream 0m0.649s 200023
~~ async ~~
node fast-glob async 0m0.349s 200023
node globby async 0m0.509s 200023
node current glob async mjs 0m0.427s 200023
node current glob stream 0m0.388s 200023
--- pattern: '{**/*.txt,**/?/**/*.txt,**/?/**/?/**/*.txt,**/?/**/?/**/?/**/*.txt,**/?/**/?/**/?/**/?/**/*.txt}' ---
~~ sync ~~
node fast-glob sync 0m0.589s 200023
node globby sync 0m0.771s 200023
node current globSync mjs 0m0.716s 200023
node current glob syncStream 0m0.684s 200023
~~ async ~~
node fast-glob async 0m0.351s 200023
node globby async 0m0.518s 200023
node current glob async mjs 0m0.462s 200023
node current glob stream 0m0.468s 200023
--- pattern: '**/5555/0000/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.496s 1000
node globby sync 0m0.519s 1000
node current globSync mjs 0m0.539s 1000
node current glob syncStream 0m0.567s 1000
~~ async ~~
node fast-glob async 0m0.285s 1000
node globby async 0m0.299s 1000
node current glob async mjs 0m0.305s 1000
node current glob stream 0m0.301s 1000
--- pattern: './**/0/**/../[01]/**/0/../**/0/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.484s 0
node globby sync 0m0.507s 0
node current globSync mjs 0m0.577s 4880
node current glob syncStream 0m0.586s 4880
~~ async ~~
node fast-glob async 0m0.280s 0
node globby async 0m0.298s 0
node current glob async mjs 0m0.327s 4880
node current glob stream 0m0.324s 4880
--- pattern: '**/????/????/????/????/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.547s 100000
node globby sync 0m0.673s 100000
node current globSync mjs 0m0.626s 100000
node current glob syncStream 0m0.618s 100000
~~ async ~~
node fast-glob async 0m0.315s 100000
node globby async 0m0.414s 100000
node current glob async mjs 0m0.366s 100000
node current glob stream 0m0.345s 100000
--- pattern: './{**/?{/**/?{/**/?{/**/?,,,,},,,,},,,,},,,}/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.588s 100000
node globby sync 0m0.670s 100000
node current globSync mjs 0m0.717s 200023
node current glob syncStream 0m0.687s 200023
~~ async ~~
node fast-glob async 0m0.343s 100000
node globby async 0m0.418s 100000
node current glob async mjs 0m0.519s 200023
node current glob stream 0m0.451s 200023
--- pattern: '**/!(0|9).txt' ---
~~ sync ~~
node fast-glob sync 0m0.573s 160023
node globby sync 0m0.731s 160023
node current globSync mjs 0m0.680s 180023
node current glob syncStream 0m0.659s 180023
~~ async ~~
node fast-glob async 0m0.345s 160023
node globby async 0m0.476s 160023
node current glob async mjs 0m0.427s 180023
node current glob stream 0m0.388s 180023
--- pattern: './{*/**/../{*/**/../{*/**/../{*/**/../{*/**,,,,},,,,},,,,},,,,},,,,}/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.483s 0
node globby sync 0m0.512s 0
node current globSync mjs 0m0.811s 200023
node current glob syncStream 0m0.773s 200023
~~ async ~~
node fast-glob async 0m0.280s 0
node globby async 0m0.299s 0
node current glob async mjs 0m0.617s 200023
node current glob stream 0m0.568s 200023
--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.485s 0
node globby sync 0m0.507s 0
node current globSync mjs 0m0.759s 200023
node current glob syncStream 0m0.740s 200023
~~ async ~~
node fast-glob async 0m0.281s 0
node globby async 0m0.297s 0
node current glob async mjs 0m0.544s 200023
node current glob stream 0m0.464s 200023
--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.486s 0
node globby sync 0m0.513s 0
node current globSync mjs 0m0.734s 200023
node current glob syncStream 0m0.696s 200023
~~ async ~~
node fast-glob async 0m0.286s 0
node globby async 0m0.296s 0
node current glob async mjs 0m0.506s 200023
node current glob stream 0m0.483s 200023
--- pattern: './0/**/../1/**/../2/**/../3/**/../4/**/../5/**/../6/**/../7/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.060s 0
node globby sync 0m0.074s 0
node current globSync mjs 0m0.067s 0
node current glob syncStream 0m0.066s 0
~~ async ~~
node fast-glob async 0m0.060s 0
node globby async 0m0.075s 0
node current glob async mjs 0m0.066s 0
node current glob stream 0m0.067s 0
--- pattern: './**/?/**/?/**/?/**/?/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.568s 100000
node globby sync 0m0.651s 100000
node current globSync mjs 0m0.619s 100000
node current glob syncStream 0m0.617s 100000
~~ async ~~
node fast-glob async 0m0.332s 100000
node globby async 0m0.409s 100000
node current glob async mjs 0m0.372s 100000
node current glob stream 0m0.351s 100000
--- pattern: '**/*/**/*/**/*/**/*/**' ---
~~ sync ~~
node fast-glob sync 0m0.603s 200113
node globby sync 0m0.798s 200113
node current globSync mjs 0m0.730s 222137
node current glob syncStream 0m0.693s 222137
~~ async ~~
node fast-glob async 0m0.356s 200113
node globby async 0m0.525s 200113
node current glob async mjs 0m0.508s 222137
node current glob stream 0m0.455s 222137
--- pattern: './**/*/**/*/**/*/**/*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.622s 200000
node globby sync 0m0.792s 200000
node current globSync mjs 0m0.722s 200000
node current glob syncStream 0m0.695s 200000
~~ async ~~
node fast-glob async 0m0.369s 200000
node globby async 0m0.527s 200000
node current glob async mjs 0m0.502s 200000
node current glob stream 0m0.481s 200000
--- pattern: '**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.588s 200023
node globby sync 0m0.771s 200023
node current globSync mjs 0m0.684s 200023
node current glob syncStream 0m0.658s 200023
~~ async ~~
node fast-glob async 0m0.352s 200023
node globby async 0m0.516s 200023
node current glob async mjs 0m0.432s 200023
node current glob stream 0m0.384s 200023
--- pattern: './**/**/**/**/**/**/**/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.589s 200023
node globby sync 0m0.766s 200023
node current globSync mjs 0m0.682s 200023
node current glob syncStream 0m0.652s 200023
~~ async ~~
node fast-glob async 0m0.352s 200023
node globby async 0m0.523s 200023
node current glob async mjs 0m0.436s 200023
node current glob stream 0m0.380s 200023
--- pattern: '**/*/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.592s 200023
node globby sync 0m0.776s 200023
node current globSync mjs 0m0.691s 200023
node current glob syncStream 0m0.659s 200023
~~ async ~~
node fast-glob async 0m0.357s 200023
node globby async 0m0.513s 200023
node current glob async mjs 0m0.471s 200023
node current glob stream 0m0.424s 200023
--- pattern: '**/*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.585s 200023
node globby sync 0m0.766s 200023
node current globSync mjs 0m0.694s 200023
node current glob syncStream 0m0.664s 200023
~~ async ~~
node fast-glob async 0m0.350s 200023
node globby async 0m0.514s 200023
node current glob async mjs 0m0.472s 200023
node current glob stream 0m0.424s 200023
--- pattern: '**/[0-9]/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.544s 100000
node globby sync 0m0.636s 100000
node current globSync mjs 0m0.626s 100000
node current glob syncStream 0m0.621s 100000
~~ async ~~
node fast-glob async 0m0.322s 100000
node globby async 0m0.404s 100000
node current glob async mjs 0m0.360s 100000
node current glob stream 0m0.352s 100000
```
================================================
FILE: benchclean.cjs
================================================
var rimraf = require('rimraf')
var bf = './bench-working-dir/fixture'
rimraf.sync(bf)
================================================
FILE: benchmark.sh
================================================
#!/bin/bash
export CDPATH=
set -e
. patterns.sh
bash make-benchmark-fixture.sh
wd=$PWD
mkdir -p "$wd/bench-working-dir/fixture"
cd "$wd/bench-working-dir"
cat > "$wd/bench-working-dir/package.json" <<PJ
{
"dependencies": {
"fast-glob": "3",
"glob7": "npm:glob@7",
"glob8": "npm:glob@8",
"globby": "13"
}
}
PJ
if ! [ -d "$wd/bench-working-dir/node_modules/glob7" ] || \
! [ -d "$wd/bench-working-dir/node_modules/glob8" ] || \
! [ -d "$wd/bench-working-dir/node_modules/globby" ]; then
(cd "$wd/bench-working-dir" &>/dev/null; npm i --silent)
fi
tt () {
time "$@"
}
t () {
rm -f stderr stdout
tt "$@" 2>stderr >stdout || (cat stderr >&2 ; exit 1 )
echo $(cat stderr | grep real | awk -F $'\t' '{ print $2 }' || true)' '\
$(cat stdout)
# rm -f stderr stdout
}
# warm up the fs cache so we don't get a spurious slow first result
bash -c 'for i in **; do :; done'
cd "$wd/bench-working-dir/fixture"
for p in "${patterns[@]}"; do
echo
echo "--- pattern: '$p' ---"
# if [[ "`bash --version`" =~ version\ 4 ]] || [[ "`bash --version`" =~ version\ 5 ]]; then
# echo -n $'bash \t'
# t bash -c 'shopt -s globstar; echo '"$p"' | wc -w'
# fi
# if type zsh &>/dev/null; then
# echo -n $'zsh \t'
# t zsh -c 'echo '"$p"' | wc -w'
# fi
# echo -n $'glob v7 sync \t'
# t node -e '
# var glob=require(process.argv[1])
# console.log(glob.sync(process.argv[2]).length)
# ' "$wd/bench-working-dir/node_modules/glob7" "$p"
# echo -n $'glob v7 async \t'
# t node -e '
# var glob=require(process.argv[1])
# glob(process.argv[2], (er, files) => {
# console.log(files.length)
# })' "$wd/bench-working-dir/node_modules/glob7" "$p"
echo '~~ sync ~~'
echo -n $'fast-glob sync \t'
cat > "$wd"/bench-working-dir/fast-glob-sync.cjs <<CJS
const fg = require('fast-glob')
console.log(fg.sync([process.argv[2]]).length)
CJS
t node "$wd/bench-working-dir/fast-glob-sync.cjs" "$p"
echo -n $'globby sync \t'
cat > "$wd"/bench-working-dir/globby-sync.mjs <<MJS
import { globbySync } from "globby"
console.log(globbySync([process.argv[2]]).length)
MJS
t node "$wd/bench-working-dir/globby-sync.mjs" "$p"
if node -e "require('fs').globSync || process.exit(1)"; then
echo -n $'fs.globSync \t'
cat > "$wd"/bench-working-dir/node-fs-glob-sync.js <<CJS
const { globSync } = require('fs')
console.log(globSync([process.argv[2]]).length)
CJS
t node "$wd/bench-working-dir/node-fs-glob-sync.js" "$p"
fi
# echo -n $'current globSync cjs \t'
# cat > "$wd/bench-working-dir/sync.cjs" <<CJS
# const {globSync} = require("$wd/dist/cjs/index-cjs.js")
# console.log(globSync(process.argv[2]).length)
#CJS
# t node "$wd/bench-working-dir/sync.cjs" "$p"
#
# echo -n $'current glob async cjs \t'
# cat > "$wd/bench-working-dir/async.cjs" <<CJS
# const glob = require("$wd/dist/cjs/index-cjs.js")
# glob(process.argv[2]).then(files => console.log(files.length))
#CJS
# t node "$wd/bench-working-dir/async.cjs" "$p"
# echo -n $'glob v8 sync \t'
# cat > "$wd/bench-working-dir/glob-8-sync.cjs" <<CJS
# var glob=require('glob8')
# console.log(glob.sync(process.argv[2]).length)
# CJS
# t node "$wd/bench-working-dir/glob-8-sync.cjs" "$p"
echo -n $'current globSync mjs \t'
cat > "$wd/bench-working-dir/sync.mjs" <<MJS
import {globSync} from '$wd/dist/esm/index.js'
console.log(globSync(process.argv[2]).length)
MJS
t node "$wd/bench-working-dir/sync.mjs" "$p"
echo -n $'current glob syncStream \t'
cat > "$wd/bench-working-dir/stream-sync.mjs" <<MJS
import {globStreamSync} from '$wd/dist/esm/index.js'
let c = 0
globStreamSync(process.argv[2])
.on('data', () => c++)
.on('end', () => console.log(c))
MJS
t node "$wd/bench-working-dir/stream-sync.mjs" "$p"
echo '~~ async ~~'
echo -n $'fast-glob async \t'
cat > "$wd"/bench-working-dir/fast-glob-async.cjs <<CJS
const fg = require('fast-glob')
fg([process.argv[2]]).then(r => console.log(r.length))
CJS
t node "$wd/bench-working-dir/fast-glob-async.cjs" "$p"
echo -n $'globby async \t'
cat > "$wd"/bench-working-dir/globby-async.mjs <<MJS
import { globby } from "globby"
globby([process.argv[2]]).then((files) => {
console.log(files.length)
})
MJS
t node "$wd/bench-working-dir/globby-async.mjs" "$p"
if node -e "require('fs').glob || process.exit(1)"; then
echo -n $'fs.glob \t'
cat > "$wd"/bench-working-dir/node-fs-glob.js <<CJS
const { glob } = require('fs')
glob(process.argv[2], (er, results) => {
console.log(er ? 0 : results.length)
})
CJS
t node "$wd/bench-working-dir/node-fs-glob.js" "$p"
fi
# echo -n $'glob v8 async \t'
# cat > "$wd/bench-working-dir/glob-8-async.cjs" <<CJS
# var glob=require('glob8')
# glob(process.argv[2], (er, results) =>
# console.log(results.length)
# )
# CJS
# t node "$wd/bench-working-dir/glob-8-async.cjs" "$p"
echo -n $'current glob async mjs \t'
cat > "$wd/bench-working-dir/async.mjs" <<MJS
import { glob } from '$wd/dist/esm/index.js'
glob(process.argv[2]).then(files => console.log(files.length))
MJS
t node "$wd/bench-working-dir/async.mjs" "$p"
echo -n $'current glob stream \t'
cat > "$wd/bench-working-dir/stream.mjs" <<MJS
import {globStream} from '$wd/dist/esm/index.js'
let c = 0
globStream(process.argv[2])
.on('data', () => c++)
.on('end', () => console.log(c))
MJS
t node "$wd/bench-working-dir/stream.mjs" "$p"
# echo -n $'current glob sync cjs -e \t'
# t node -e '
# console.log(require(process.argv[1]).sync(process.argv[2]).length)
# ' "$wd/dist/cjs/index-cjs.js" "$p"
# echo -n $'current glob async cjs -e\t'
# t node -e '
# require(process.argv[1])(process.argv[2]).then((files) => console.log(files.length))
# ' "$wd/dist/cjs/index-cjs.js" "$p"
done
================================================
FILE: changelog.md
================================================
# changeglob
## 13
- Move the CLI program out to a separate package, `glob-bin`.
Install that if you'd like to continue using glob from the
command line.
## 12
- Remove the unsafe `--shell` option. The `--shell` option is now
ONLY supported on known shells where the behavior can be
implemented safely.
## 11.1
[GHSA-5j98-mcp5-4vw2](https://github.com/isaacs/node-glob/security/advisories/GHSA-5j98-mcp5-4vw2)
- Add the `--shell` option for the command line, with a warning
that this is unsafe. (It will be removed in v12.)
- Add the `--cmd-arg`/`-g` as a way to _safely_ add positional
arguments to the command provided to the CLI tool.
- Detect commands with space or quote characters on known shells,
and pass positional arguments to them safely, avoiding
`shell:true` execution.
## 11.0
- Drop support for node before v20
## 10.4
- Add `includeChildMatches: false` option
- Export the `Ignore` class
## 10.3
- Add `--default -p` flag to provide a default pattern
- exclude symbolic links to directories when `follow` and `nodir`
are both set
## 10.2
- Add glob cli
## 10.1
- Return `'.'` instead of the empty string `''` when the current
working directory is returned as a match.
- Add `posix: true` option to return `/` delimited paths, even on
Windows.
## 10.0.0
- No default exports, only named exports
## 9.3.3
- Upgraded minimatch to v8, adding support for any degree of
nested extglob patterns.
## 9.3
- Add aliases for methods. `glob.sync`, `glob.stream`,
`glob.stream.sync`, etc.
## 9.2
- Support using a custom fs object, which is passed to PathScurry
- add maxDepth option
- add stat option
- add custom Ignore support
## 9.1
- Bring back the `root` option, albeit with slightly different
semantics than in v8 and before.
- Support `{ absolute:false }` option to explicitly always return
relative paths. An unset `absolute` setting will still return
absolute or relative paths based on whether the pattern is
absolute.
- Add `magicalBraces` option to treat brace expansion as "magic"
in the `hasMagic` function.
- Add `dotRelative` option
- Add `escape()` and `unescape()` methods
## 9.0
This is a full rewrite, with significant API and algorithm
changes.
### High-Level Feature and API Surface Changes
- Only support node 16 and higher.
- Promise API instead of callbacks.
- Exported function names have changed, as have the methods on
the Glob class. See API documentation for details.
- Accept pattern as string or array of strings.
- Hybrid module distribution.
- Full TypeScript support.
- Exported `Glob` class is no longer an event emitter.
- Exported `Glob` class has `walk()`, `walkSync()`, `stream()`,
`streamSync()`, `iterate()`, `iterateSync()` methods, and is
both an async and sync Generator.
- First class support for UNC paths and drive letters on Windows.
Note that _glob patterns_ must still use `/` as a path
separator, unless the `windowsPathsNoEscape` option is set, in
which case glob patterns cannot be escaped with `\`.
- Paths are returned in the canonical formatting for the platform
in question.
- The `hasMagic` method will return false for patterns that only
contain brace expansion, but no other "magic" glob characters.
- Patterns ending in `/` will still be restricted to matching
directories, but will not have a `/` appended in the results.
In general, results will be in their default relative or
absolute forms, without any extraneous `/` and `.` characters,
unlike shell matches. (The `mark` option may still be used to
_always_ mark directory matches with a trailing `/` or `\`.)
- An options argument is required for the `Glob` class
constructor. `{}` may be provided to accept all default
options.
### Options Changes
- Removed `root` option and mounting behavior.
- Removed `stat` option. It's slow and pointless. (Could bring
back easily if there's demand, but items are already statted in
cases where it's relevant, such as `nodir:true` or
`mark:true`.)
- Simplified `cwd` behavior so it is far less magical, and relies
less on platform-specific absolute path representations.
- `cwd` can be a File URL or a string path.
- More efficient handling for absolute patterns. (That is,
patterns that start with `/` on any platform, or start with a
drive letter or UNC path on Windows.)
- Removed `silent` and `strict` options. Any readdir errors are
simply treated as "the directory could not be read", and it is
treated as a normal file entry instead, like shells do.
- Removed `fs` option. This module only operates on the real
filesystem. (Could bring back if there's demand for it, but
it'd be an update to PathScurry, not Glob.)
- `nonull:true` is no longer supported.
- `withFileTypes:true` option added, to get `Path` objects.
These are a bit like a Dirent, but can do a lot more. See
<http://npm.im/path-scurry>
- `nounique:true` is no longer supported. Result sets are always
unique.
- `nosort:true` is no longer supported. Result sets are never
sorted.
- When the `nocase` option is used, the assumption is that it
reflects the case sensitivity of the _filesystem itself_.
Using case-insensitive matching on a case-sensitive filesystem,
or vice versa, may thus result in more or fewer matches than
expected. In general, it should only be used when the
filesystem is known to differ from the platform default.
- `realpath:true` no longer implies `absolute:true`. The
relative path to the realpath will be emitted when `absolute`
is not set.
- `realpath:true` will cause invalid symbolic links to be
omitted, rather than matching the link itself.
### Performance and Algorithm Changes
- Massive performance improvements.
- Removed nearly all stat calls, in favor of using
`withFileTypes:true` with `fs.readdir()`.
- Replaced most of the caching with a
[PathScurry](http://npm.im/path-scurry) based implementation.
- More correct handling of `**` vs `./**`, following Bash
semantics, where a `**` is followed one time only if it is not
the first item in the pattern.
## 8.1
- Add `windowsPathsNoEscape` option
## 8.0
- Only support node v12 and higher
- `\` is now **only** used as an escape character, and never as a
path separator in glob patterns, so that Windows users have a
way to match against filenames containing literal glob pattern
characters.
- Glob pattern paths **must** use forward-slashes as path
separators, since `\` is an escape character to match literal
glob pattern characters.
- (8.0.2) `cwd` and `root` will always be automatically coerced
to use `/` as path separators on Windows, as they cannot
contain glob patterns anyway, and are often supplied by
`path.resolve()` and other methods that will use `\` path
separators by default.
## 7.2
- Add fs option to allow passing virtual filesystem
## 7.1
- Ignore stat errors that are not `ENOENT` to work around Windows issues.
- Support using root and absolute options together
- Bring back lumpy space princess
- force 'en' locale in string sorting
## 7.0
- Raise error if `options.cwd` is specified, and not a directory
## 6.0
- Remove comment and negation pattern support
- Ignore patterns are always in `dot:true` mode
## 5.0
- Deprecate comment and negation patterns
- Fix regression in `mark` and `nodir` options from making all cache
keys absolute path.
- Abort if `fs.readdir` returns an error that's unexpected
- Don't emit `match` events for ignored items
- Treat ENOTSUP like ENOTDIR in readdir
## 4.5
- Add `options.follow` to always follow directory symlinks in globstar
- Add `options.realpath` to call `fs.realpath` on all results
- Always cache based on absolute path
## 4.4
- Add `options.ignore`
- Fix handling of broken symlinks
## 4.3
- Bump minimatch to 2.x
- Pass all tests on Windows
## 4.2
- Add `glob.hasMagic` function
- Add `options.nodir` flag
## 4.1
- Refactor sync and async implementations for performance
- Throw if callback provided to sync glob function
- Treat symbolic links in globstar results the same as Bash 4.3
## 4.0
- Use `^` for dependency versions (bumped major because this breaks
older npm versions)
- Ensure callbacks are only ever called once
- switch to ISC license
## 3.x
- Rewrite in JavaScript
- Add support for setting root, cwd, and windows support
- Cache many fs calls
- Add globstar support
- emit match events
## 2.x
- Use `glob.h` and `fnmatch.h` from NetBSD
## 1.x
- `glob.h` static binding.
================================================
FILE: examples/g.js
================================================
var Glob = require('../').Glob
var pattern = 'test/a/**/[cg]/../[cg]'
console.log(pattern)
var mg = new Glob(pattern, { mark: true, sync: true }, function (
er,
matches,
) {
console.log('matches', matches)
})
console.log('after')
================================================
FILE: examples/usr-local.js
================================================
var Glob = require('../').Glob
var pattern = '{./*/*,/*,/usr/local/*}'
console.log(pattern)
var mg = new Glob(pattern, { mark: true }, function (er, matches) {
console.log('matches', matches)
})
console.log('after')
================================================
FILE: make-benchmark-fixture.sh
================================================
#!/bin/bash
wd=$PWD
mkdir -p "$wd/bench-working-dir/fixture"
tmp="$wd/bench-working-dir/fixture"
export CDPATH=
set -e
if ! [ -d "$tmp/0" ]; then
echo Making benchmark fixtures
mkdir -p "$tmp"
cd "$tmp"
dirnames=`echo {0..9}/{0..9}/{0..9}/{0..9}` # 10000 dirs
filenames=`echo {0..9}/{0..9}/{0..9}/{0..9}/{0..9}.txt`
echo $dirnames | xargs mkdir -p
echo $filenames | xargs touch
# add 10k more that are not single chars
for i in {0..9}; do
for j in {0..9}; do
for k in {0..9}; do
for l in {0..9}; do
mkdir -p "$i$i$i$i/$j$j$j$j/$k$k$k$k/$l$l$l$l"
for m in {0..9}; do
touch "$i$i$i$i/$j$j$j$j/$k$k$k$k/$l$l$l$l/$m$m$m$m.txt"
done
done
done
done
done
fi
================================================
FILE: package.json
================================================
{
"author": "Isaac Z. Schlueter <i@izs.me> (https://blog.izs.me/)",
"name": "glob",
"description": "the most correct and second fastest glob implementation in JavaScript",
"version": "13.0.6",
"type": "module",
"tshy": {
"selfLink": false,
"exports": {
"./package.json": "./package.json",
"./raw": "./src/index.ts",
".": {
"import": {
"types": "./dist/esm/index.d.ts",
"default": "./dist/esm/index.min.js"
},
"require": {
"types": "./dist/commonjs/index.d.ts",
"default": "./dist/commonjs/index.min.js"
}
}
}
},
"main": "./dist/commonjs/index.min.js",
"module": "./dist/esm/index.min.js",
"types": "./dist/commonjs/index.d.ts",
"exports": {
"./package.json": "./package.json",
"./raw": {
"import": {
"types": "./dist/esm/index.d.ts",
"default": "./dist/esm/index.js"
},
"require": {
"types": "./dist/commonjs/index.d.ts",
"default": "./dist/commonjs/index.js"
}
},
".": {
"import": {
"types": "./dist/esm/index.d.ts",
"default": "./dist/esm/index.min.js"
},
"require": {
"types": "./dist/commonjs/index.d.ts",
"default": "./dist/commonjs/index.min.js"
}
}
},
"repository": {
"type": "git",
"url": "git@github.com:isaacs/node-glob.git"
},
"files": [
"dist"
],
"scripts": {
"preversion": "npm test",
"postversion": "npm publish",
"prepublishOnly": "npm run benchclean; git push origin --follow-tags",
"prepare": "tshy && bash scripts/build.sh",
"pretest": "npm run prepare",
"presnap": "npm run prepare",
"test": "tap",
"snap": "tap",
"posttest": "npm run lint",
"postsnap": "npm run lint",
"format": "prettier --write .",
"lint": "oxlint --fix src test",
"postlint": "npm run format",
"typedoc": "typedoc",
"profclean": "rm -f v8.log profile.txt",
"test-regen": "npm run profclean && TEST_REGEN=1 node --no-warnings --loader ts-node/esm test/00-setup.ts",
"prebench": "npm run prepare",
"bench": "bash benchmark.sh",
"preprof": "npm run prepare",
"prof": "bash prof.sh",
"benchclean": "node benchclean.cjs"
},
"dependencies": {
"minimatch": "^10.2.4",
"minipass": "^7.1.3",
"path-scurry": "^2.0.2"
},
"devDependencies": {
"@types/node": "^25.5.0",
"esbuild": "^0.27.4",
"memfs": "^4.50.0",
"mkdirp": "^3.0.1",
"oxlint": "^1.56.0",
"oxlint-tsgolint": "^0.17.0",
"prettier": "^3.8.1",
"rimraf": "^6.1.3",
"tap": "^21.6.2",
"tshy": "^3.3.2",
"typedoc": "^0.28.17"
},
"license": "BlueOak-1.0.0",
"funding": {
"url": "https://github.com/sponsors/isaacs"
},
"engines": {
"node": "18 || 20 || >=22"
}
}
================================================
FILE: patterns.sh
================================================
patterns=(
'{0000,0,1111,1}/{0000,0,1111,1}/{0000,0,1111,1}/**'
'**'
'**/..'
# some of these aren't particularly "representative" of real-world
# glob patterns, but they're here to highlight pathological perf
# cases that I found while working on the rewrite of this library.
'./**/0/**/0/**/0/**/0/**/*.txt'
'./**/[01]/**/[12]/**/[23]/**/[45]/**/*.txt'
'./**/0/**/0/**/*.txt'
'**/*.txt'
'{**/*.txt,**/?/**/*.txt,**/?/**/?/**/*.txt,**/?/**/?/**/?/**/*.txt,**/?/**/?/**/?/**/?/**/*.txt}'
'**/5555/0000/*.txt'
'./**/0/**/../[01]/**/0/../**/0/*.txt'
'**/????/????/????/????/*.txt'
'./{**/?{/**/?{/**/?{/**/?,,,,},,,,},,,,},,,}/**/*.txt'
'**/!(0|9).txt'
'./{*/**/../{*/**/../{*/**/../{*/**/../{*/**,,,,},,,,},,,,},,,,},,,,}/*.txt'
'./*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/*.txt'
'./*/**/../*/**/../*/**/../*/**/../*/**/*.txt'
'./0/**/../1/**/../2/**/../3/**/../4/**/../5/**/../6/**/../7/**/*.txt'
'./**/?/**/?/**/?/**/?/**/*.txt'
'**/*/**/*/**/*/**/*/**'
# '5555/0000/**/*.txt'
# '*/*/9/**/**/**/**/*/**/**/*.txt'
'./**/*/**/*/**/*/**/*/**/*.txt'
'**/*.txt'
# './**/*.txt'
'./**/**/**/**/**/**/**/**/*.txt'
'**/*/*.txt'
'**/*/**/*.txt'
'**/[0-9]/**/*.txt'
# '0/@([5-9]/*.txt|8/**)'
# '[0-9]/[0-9]/[0-9]/[0-9]/[0-9].txt'
# /**/**/**/**//////**/**//*.txt'
# '**/[5-9]/*.txt'
# '[678]/**/2.txt'
# '0/!(1|2)@(4|5)/**/**/**/**/*.txt'
# '0/!(1|2|@(4|5))/**/**/**/**/*.txt'
)
================================================
FILE: prof.sh
================================================
#!/bin/bash
export CDPATH=
set -e
set -x
. patterns.sh
bash -x make-benchmark-fixture.sh
wd=$PWD
tmp="$wd/bench-working-dir"
cd "$tmp"
export __GLOB_PROFILE__=1
cat > "profscript.mjs" <<MJS
import { glob } from '$wd/dist/mjs/index.js'
const patterns = process.argv.slice(2)
for (const p of patterns) {
glob.sync("./fixture/" + p)
}
await Promise.all(patterns.map(async p => {
await glob("./fixture/" + p)
}))
MJS
node --prof profscript.mjs "${patterns[@]}" &> profile.out
mkdir -p profiles
d=./profiles/$(date +%s)
mv isolate*.log ${d}.log
node --prof-process ${d}.log > ${d}.txt
cp ${d}.txt ../profile.txt
#cat ${d}.txt
================================================
FILE: scripts/build.sh
================================================
#!/usr/bin/env bash
esbuild \
--minify \
--platform=node \
--sourcemap \
--bundle dist/commonjs/index.js \
--outfile=dist/commonjs/index.min.js \
--format=cjs
esbuild \
--minify \
--platform=node \
--sourcemap \
--bundle dist/esm/index.js \
--outfile=dist/esm/index.min.js \
--format=esm
================================================
FILE: scripts/make-big-tree.js
================================================
#!/usr/bin/env node
const mkdirp = require('mkdirp')
const { readFileSync } = require('fs')
const { writeFile } = require('fs/promises')
const rimraf = require('rimraf')
const filesPerDir = 10
const dirsPerDir = 5
const max = (module === require.main && +process.argv[2]) || 1_000_000
const { now } = performance
let lastReported = now()
const report = s => {
if (!process.stderr.isTTY) return
process.stderr.write('\r' + s.padEnd(40))
}
let made = 0
const makeStep = async dir => {
if (now() - lastReported > 250) report('growing: ' + made)
const promises = []
for (let i = 0; i < filesPerDir && made < max; i++) {
made++
promises.push(writeFile(`${dir}/${i}.txt`, ''))
}
await Promise.all(promises)
const childDirs = []
for (let i = 0; i < dirsPerDir && made < max; i++) {
made++
await mkdirp(`${dir}/${i}`)
childDirs.push(makeStep(`${dir}/${i}`))
}
await Promise.all(childDirs)
}
const make = async root => {
try {
const already = +readFileSync(`${root}/bigtree.txt`)
if (already === max) {
console.log('already done!')
return
}
} catch (_) {}
report('chop down previous bigtree...')
await rimraf(root + '/bigtree')
report('creating bigtree...')
report('\n')
await mkdirp(root + '/bigtree')
await makeStep(root + '/bigtree')
await writeFile(`${root}/bigtree.txt`, `${max}`)
}
make(__dirname + '/fixture').then(() => {
if (process.stderr.isTTY) process.stderr.write('\r'.padEnd(40) + '\r')
console.log('done')
})
================================================
FILE: src/glob.ts
================================================
import type { MinimatchOptions } from 'minimatch'
import { Minimatch } from 'minimatch'
import type { Minipass } from 'minipass'
import { fileURLToPath } from 'node:url'
import type { FSOption, Path } from 'path-scurry'
import {
PathScurry,
PathScurryDarwin,
PathScurryPosix,
PathScurryWin32,
} from 'path-scurry'
import type { IgnoreLike } from './ignore.js'
import { Pattern } from './pattern.js'
import { GlobStream, GlobWalker } from './walker.js'
export type MatchSet = Minimatch['set']
export type GlobParts = Exclude<Minimatch['globParts'], undefined>
// if no process global, just call it linux.
// so we default to case-sensitive, / separators
const defaultPlatform: NodeJS.Platform =
(
typeof process === 'object' &&
process &&
typeof process.platform === 'string'
) ?
process.platform
: 'linux'
/**
* A `GlobOptions` object may be provided to any of the exported methods, and
* must be provided to the `Glob` constructor.
*
* All options are optional, boolean, and false by default, unless otherwise
* noted.
*
* All resolved options are added to the Glob object as properties.
*
* If you are running many `glob` operations, you can pass a Glob object as the
* `options` argument to a subsequent operation to share the previously loaded
* cache.
*/
export interface GlobOptions {
/**
* Set to `true` to always receive absolute paths for
* matched files. Set to `false` to always return relative paths.
*
* When this option is not set, absolute paths are returned for patterns
* that are absolute, and otherwise paths are returned that are relative
* to the `cwd` setting.
*
* This does _not_ make an extra system call to get
* the realpath, it only does string path resolution.
*
* Conflicts with {@link withFileTypes}
*/
absolute?: boolean
/**
* Set to false to enable {@link windowsPathsNoEscape}
*
* @deprecated
*/
allowWindowsEscape?: boolean
/**
* The current working directory in which to search. Defaults to
* `process.cwd()`.
*
* May be eiher a string path or a `file://` URL object or string.
*/
cwd?: string | URL
/**
* Include `.dot` files in normal matches and `globstar`
* matches. Note that an explicit dot in a portion of the pattern
* will always match dot files.
*/
dot?: boolean
/**
* Prepend all relative path strings with `./` (or `.\` on Windows).
*
* Without this option, returned relative paths are "bare", so instead of
* returning `'./foo/bar'`, they are returned as `'foo/bar'`.
*
* Relative patterns starting with `'../'` are not prepended with `./`, even
* if this option is set.
*/
dotRelative?: boolean
/**
* Follow symlinked directories when expanding `**`
* patterns. This can result in a lot of duplicate references in
* the presence of cyclic links, and make performance quite bad.
*
* By default, a `**` in a pattern will follow 1 symbolic link if
* it is not the first item in the pattern, or none if it is the
* first item in the pattern, following the same behavior as Bash.
*/
follow?: boolean
/**
* string or string[], or an object with `ignored` and `childrenIgnored`
* methods.
*
* If a string or string[] is provided, then this is treated as a glob
* pattern or array of glob patterns to exclude from matches. To ignore all
* children within a directory, as well as the entry itself, append `'/**'`
* to the ignore pattern.
*
* **Note** `ignore` patterns are _always_ in `dot:true` mode, regardless of
* any other settings.
*
* If an object is provided that has `ignored(path)` and/or
* `childrenIgnored(path)` methods, then these methods will be called to
* determine whether any Path is a match or if its children should be
* traversed, respectively.
*/
ignore?: string | string[] | IgnoreLike
/**
* Treat brace expansion like `{a,b}` as a "magic" pattern. Has no
* effect if {@link nobrace} is set.
*
* Only has effect on the {@link hasMagic} function.
*/
magicalBraces?: boolean
/**
* Add a `/` character to directory matches. Note that this requires
* additional stat calls in some cases.
*/
mark?: boolean
/**
* Perform a basename-only match if the pattern does not contain any slash
* characters. That is, `*.js` would be treated as equivalent to
* `**\/*.js`, matching all js files in all directories.
*/
matchBase?: boolean
/**
* Limit the directory traversal to a given depth below the cwd.
* Note that this does NOT prevent traversal to sibling folders,
* root patterns, and so on. It only limits the maximum folder depth
* that the walk will descend, relative to the cwd.
*/
maxDepth?: number
/**
* Do not expand `{a,b}` and `{1..3}` brace sets.
*/
nobrace?: boolean
/**
* Perform a case-insensitive match. This defaults to `true` on macOS and
* Windows systems, and `false` on all others.
*
* **Note** `nocase` should only be explicitly set when it is
* known that the filesystem's case sensitivity differs from the
* platform default. If set `true` on case-sensitive file
* systems, or `false` on case-insensitive file systems, then the
* walk may return more or less results than expected.
*/
nocase?: boolean
/**
* Do not match directories, only files. (Note: to match
* _only_ directories, put a `/` at the end of the pattern.)
*/
nodir?: boolean
/**
* Do not match "extglob" patterns such as `+(a|b)`.
*/
noext?: boolean
/**
* Do not match `**` against multiple filenames. (Ie, treat it as a normal
* `*` instead.)
*
* Conflicts with {@link matchBase}
*/
noglobstar?: boolean
/**
* Defaults to value of `process.platform` if available, or `'linux'` if
* not. Setting `platform:'win32'` on non-Windows systems may cause strange
* behavior.
*/
platform?: NodeJS.Platform
/**
* Set to true to call `fs.realpath` on all of the
* results. In the case of an entry that cannot be resolved, the
* entry is omitted. This incurs a slight performance penalty, of
* course, because of the added system calls.
*/
realpath?: boolean
/**
*
* A string path resolved against the `cwd` option, which
* is used as the starting point for absolute patterns that start
* with `/`, (but not drive letters or UNC paths on Windows).
*
* Note that this _doesn't_ necessarily limit the walk to the
* `root` directory, and doesn't affect the cwd starting point for
* non-absolute patterns. A pattern containing `..` will still be
* able to traverse out of the root directory, if it is not an
* actual root directory on the filesystem, and any non-absolute
* patterns will be matched in the `cwd`. For example, the
* pattern `/../*` with `{root:'/some/path'}` will return all
* files in `/some`, not all files in `/some/path`. The pattern
* `*` with `{root:'/some/path'}` will return all the entries in
* the cwd, not the entries in `/some/path`.
*
* To start absolute and non-absolute patterns in the same
* path, you can use `{root:''}`. However, be aware that on
* Windows systems, a pattern like `x:/*` or `//host/share/*` will
* _always_ start in the `x:/` or `//host/share` directory,
* regardless of the `root` setting.
*/
root?: string
/**
* A [PathScurry](http://npm.im/path-scurry) object used
* to traverse the file system. If the `nocase` option is set
* explicitly, then any provided `scurry` object must match this
* setting.
*/
scurry?: PathScurry
/**
* Call `lstat()` on all entries, whether required or not to determine
* if it's a valid match. When used with {@link withFileTypes}, this means
* that matches will include data such as modified time, permissions, and
* so on. Note that this will incur a performance cost due to the added
* system calls.
*/
stat?: boolean
/**
* An AbortSignal which will cancel the Glob walk when
* triggered.
*/
signal?: AbortSignal
/**
* Use `\\` as a path separator _only_, and
* _never_ as an escape character. If set, all `\\` characters are
* replaced with `/` in the pattern.
*
* Note that this makes it **impossible** to match against paths
* containing literal glob pattern characters, but allows matching
* with patterns constructed using `path.join()` and
* `path.resolve()` on Windows platforms, mimicking the (buggy!)
* behavior of Glob v7 and before on Windows. Please use with
* caution, and be mindful of [the caveat below about Windows
* paths](#windows). (For legacy reasons, this is also set if
* `allowWindowsEscape` is set to the exact value `false`.)
*/
windowsPathsNoEscape?: boolean
/**
* Return [PathScurry](http://npm.im/path-scurry)
* `Path` objects instead of strings. These are similar to a
* NodeJS `Dirent` object, but with additional methods and
* properties.
*
* Conflicts with {@link absolute}
*/
withFileTypes?: boolean
/**
* An fs implementation to override some or all of the defaults. See
* http://npm.im/path-scurry for details about what can be overridden.
*/
fs?: FSOption
/**
* Just passed along to Minimatch. Note that this makes all pattern
* matching operations slower and *extremely* noisy.
*/
debug?: boolean
/**
* Return `/` delimited paths, even on Windows.
*
* On posix systems, this has no effect. But, on Windows, it means that
* paths will be `/` delimited, and absolute paths will be their full
* resolved UNC forms, eg instead of `'C:\\foo\\bar'`, it would return
* `'//?/C:/foo/bar'`
*/
posix?: boolean
/**
* Do not match any children of any matches. For example, the pattern
* `**\/foo` would match `a/foo`, but not `a/foo/b/foo` in this mode.
*
* This is especially useful for cases like "find all `node_modules`
* folders, but not the ones in `node_modules`".
*
* In order to support this, the `Ignore` implementation must support an
* `add(pattern: string)` method. If using the default `Ignore` class, then
* this is fine, but if this is set to `false`, and a custom `Ignore` is
* provided that does not have an `add()` method, then it will throw an
* error.
*
* **Caveat** It *only* ignores matches that would be a descendant of a
* previous match, and only if that descendant is matched *after* the
* ancestor is encountered. Since the file system walk happens in
* indeterminate order, it's possible that a match will already be added
* before its ancestor, if multiple or braced patterns are used.
*
* For example:
*
* ```ts
* const results = await glob([
* // likely to match first, since it's just a stat
* 'a/b/c/d/e/f',
*
* // this pattern is more complicated! It must to various readdir()
* // calls and test the results against a regular expression, and that
* // is certainly going to take a little bit longer.
* //
* // So, later on, it encounters a match at 'a/b/c/d/e', but it's too
* // late to ignore a/b/c/d/e/f, because it's already been emitted.
* 'a/[bdf]/?/[a-z]/*',
* ], { includeChildMatches: false })
* ```
*
* It's best to only set this to `false` if you can be reasonably sure that
* no components of the pattern will potentially match one another's file
* system descendants, or if the occasional included child entry will not
* cause problems.
*
* @default true
*/
includeChildMatches?: boolean
/**
* max number of `{...}` patterns to expand. Default `1_000`.
*
* Note: this is much less than minimatch's default of `100_000`,
* because Glob has higher memory requirements due to walking
* the file system tree.
*/
braceExpandMax?: number
}
export type GlobOptionsWithFileTypesTrue = GlobOptions & {
withFileTypes: true
// string options not relevant if returning Path objects.
absolute?: undefined
mark?: undefined
posix?: undefined
}
export type GlobOptionsWithFileTypesFalse = GlobOptions & {
withFileTypes?: false
}
export type GlobOptionsWithFileTypesUnset = GlobOptions & {
withFileTypes?: undefined
}
export type Result<Opts> =
Opts extends GlobOptionsWithFileTypesTrue ? Path
: Opts extends GlobOptionsWithFileTypesFalse ? string
: Opts extends GlobOptionsWithFileTypesUnset ? string
: string | Path
export type Results<Opts> = Result<Opts>[]
export type FileTypes<Opts> =
Opts extends GlobOptionsWithFileTypesTrue ? true
: Opts extends GlobOptionsWithFileTypesFalse ? false
: Opts extends GlobOptionsWithFileTypesUnset ? false
: boolean
/**
* An object that can perform glob pattern traversals.
*/
export class Glob<Opts extends GlobOptions> implements GlobOptions {
absolute?: boolean
cwd: string
root?: string
dot: boolean
dotRelative: boolean
follow: boolean
ignore?: string | string[] | IgnoreLike
magicalBraces: boolean
mark?: boolean
matchBase: boolean
maxDepth: number
nobrace: boolean
nocase: boolean
nodir: boolean
noext: boolean
noglobstar: boolean
pattern: string[]
platform: NodeJS.Platform
realpath: boolean
scurry: PathScurry
stat: boolean
signal?: AbortSignal
windowsPathsNoEscape: boolean
withFileTypes: FileTypes<Opts>
includeChildMatches: boolean
/**
* The options provided to the constructor.
*/
opts: Opts
/**
* An array of parsed immutable {@link Pattern} objects.
*/
patterns: Pattern[]
/**
* All options are stored as properties on the `Glob` object.
*
* See {@link GlobOptions} for full options descriptions.
*
* Note that a previous `Glob` object can be passed as the
* `GlobOptions` to another `Glob` instantiation to re-use settings
* and caches with a new pattern.
*
* Traversal functions can be called multiple times to run the walk
* again.
*/
constructor(pattern: string | string[], opts: Opts) {
/* c8 ignore start */
if (!opts) throw new TypeError('glob options required')
/* c8 ignore stop */
this.withFileTypes = !!opts.withFileTypes as FileTypes<Opts>
this.signal = opts.signal
this.follow = !!opts.follow
this.dot = !!opts.dot
this.dotRelative = !!opts.dotRelative
this.nodir = !!opts.nodir
this.mark = !!opts.mark
if (!opts.cwd) {
this.cwd = ''
} else if (opts.cwd instanceof URL || opts.cwd.startsWith('file://')) {
opts.cwd = fileURLToPath(opts.cwd)
}
this.cwd = opts.cwd || ''
this.root = opts.root
this.magicalBraces = !!opts.magicalBraces
this.nobrace = !!opts.nobrace
this.noext = !!opts.noext
this.realpath = !!opts.realpath
this.absolute = opts.absolute
this.includeChildMatches = opts.includeChildMatches !== false
this.noglobstar = !!opts.noglobstar
this.matchBase = !!opts.matchBase
this.maxDepth =
typeof opts.maxDepth === 'number' ? opts.maxDepth : Infinity
this.stat = !!opts.stat
this.ignore = opts.ignore
if (this.withFileTypes && this.absolute !== undefined) {
throw new Error('cannot set absolute and withFileTypes:true')
}
let p: string[] = typeof pattern === 'string' ? [pattern] : pattern
this.windowsPathsNoEscape =
!!opts.windowsPathsNoEscape ||
(opts as { allowWindowsEscape?: boolean }).allowWindowsEscape ===
false
if (this.windowsPathsNoEscape) {
p = p.map(p => p.replace(/\\/g, '/'))
}
if (this.matchBase) {
if (opts.noglobstar) {
throw new TypeError('base matching requires globstar')
}
p = p.map(p => (p.includes('/') ? p : `./**/${p}`))
}
this.pattern = p
this.platform = opts.platform || defaultPlatform
this.opts = { ...opts, platform: this.platform }
if (opts.scurry) {
this.scurry = opts.scurry
if (
opts.nocase !== undefined &&
opts.nocase !== opts.scurry.nocase
) {
throw new Error('nocase option contradicts provided scurry option')
}
} else {
const Scurry =
opts.platform === 'win32' ? PathScurryWin32
: opts.platform === 'darwin' ? PathScurryDarwin
: opts.platform ? PathScurryPosix
: PathScurry
this.scurry = new Scurry(this.cwd, {
nocase: opts.nocase,
fs: opts.fs,
})
}
this.nocase = this.scurry.nocase
// If you do nocase:true on a case-sensitive file system, then
// we need to use regexps instead of strings for non-magic
// path portions, because statting `aBc` won't return results
// for the file `AbC` for example.
const nocaseMagicOnly =
this.platform === 'darwin' || this.platform === 'win32'
const mmo: MinimatchOptions = {
braceExpandMax: 10_000,
...opts,
dot: this.dot,
matchBase: this.matchBase,
nobrace: this.nobrace,
// default nocase based on platform
nocase: this.nocase,
nocaseMagicOnly,
nocomment: true,
noext: this.noext,
nonegate: true,
optimizationLevel: 2,
platform: this.platform,
windowsPathsNoEscape: this.windowsPathsNoEscape,
debug: !!this.opts.debug,
}
const mms = this.pattern.map(p => new Minimatch(p, mmo))
const [matchSet, globParts] = mms.reduce(
(set: [MatchSet, GlobParts], m) => {
set[0].push(...m.set)
set[1].push(...m.globParts)
return set
},
[[], []],
)
this.patterns = matchSet.map((set, i) => {
const g = globParts[i]
/* c8 ignore start */
if (!g) throw new Error('invalid pattern object')
/* c8 ignore stop */
return new Pattern(set, g, 0, this.platform)
})
}
/**
* Returns a Promise that resolves to the results array.
*/
async walk(): Promise<Results<Opts>>
async walk(): Promise<(string | Path)[]> {
// Walkers always return array of Path objects, so we just have to
// coerce them into the right shape. It will have already called
// realpath() if the option was set to do so, so we know that's cached.
// start out knowing the cwd, at least
return [
...(await new GlobWalker(this.patterns, this.scurry.cwd, {
...this.opts,
maxDepth:
this.maxDepth !== Infinity ?
this.maxDepth + this.scurry.cwd.depth()
: Infinity,
platform: this.platform,
nocase: this.nocase,
includeChildMatches: this.includeChildMatches,
}).walk()),
]
}
/**
* synchronous {@link Glob.walk}
*/
walkSync(): Results<Opts>
walkSync(): (string | Path)[] {
return [
...new GlobWalker(this.patterns, this.scurry.cwd, {
...this.opts,
maxDepth:
this.maxDepth !== Infinity ?
this.maxDepth + this.scurry.cwd.depth()
: Infinity,
platform: this.platform,
nocase: this.nocase,
includeChildMatches: this.includeChildMatches,
}).walkSync(),
]
}
/**
* Stream results asynchronously.
*/
stream(): Minipass<Result<Opts>, Result<Opts>>
stream(): Minipass<string | Path, string | Path> {
return new GlobStream(this.patterns, this.scurry.cwd, {
...this.opts,
maxDepth:
this.maxDepth !== Infinity ?
this.maxDepth + this.scurry.cwd.depth()
: Infinity,
platform: this.platform,
nocase: this.nocase,
includeChildMatches: this.includeChildMatches,
}).stream()
}
/**
* Stream results synchronously.
*/
streamSync(): Minipass<Result<Opts>, Result<Opts>>
streamSync(): Minipass<string | Path, string | Path> {
return new GlobStream(this.patterns, this.scurry.cwd, {
...this.opts,
maxDepth:
this.maxDepth !== Infinity ?
this.maxDepth + this.scurry.cwd.depth()
: Infinity,
platform: this.platform,
nocase: this.nocase,
includeChildMatches: this.includeChildMatches,
}).streamSync()
}
/**
* Default sync iteration function. Returns a Generator that
* iterates over the results.
*/
iterateSync(): Generator<Result<Opts>, void, void> {
return this.streamSync()[Symbol.iterator]()
}
[Symbol.iterator]() {
return this.iterateSync()
}
/**
* Default async iteration function. Returns an AsyncGenerator that
* iterates over the results.
*/
iterate(): AsyncGenerator<Result<Opts>, void, void> {
return this.stream()[Symbol.asyncIterator]()
}
[Symbol.asyncIterator]() {
return this.iterate()
}
}
================================================
FILE: src/has-magic.ts
================================================
import { Minimatch } from 'minimatch'
import type { GlobOptions } from './glob.js'
/**
* Return true if the patterns provided contain any magic glob characters,
* given the options provided.
*
* Brace expansion is not considered "magic" unless the `magicalBraces` option
* is set, as brace expansion just turns one string into an array of strings.
* So a pattern like `'x{a,b}y'` would return `false`, because `'xay'` and
* `'xby'` both do not contain any magic glob characters, and it's treated the
* same as if you had called it on `['xay', 'xby']`. When `magicalBraces:true`
* is in the options, brace expansion _is_ treated as a pattern having magic.
*/
export const hasMagic = (
pattern: string | string[],
options: GlobOptions = {},
): boolean => {
for (const p of Array.isArray(pattern) ? pattern : [pattern]) {
if (new Minimatch(p, options).hasMagic()) return true
}
return false
}
================================================
FILE: src/ignore.ts
================================================
// give it a pattern, and it'll be able to tell you if
// a given path should be ignored.
// Ignoring a path ignores its children if the pattern ends in /**
// Ignores are always parsed in dot:true mode
import type { MinimatchOptions } from 'minimatch'
import { Minimatch } from 'minimatch'
import type { Path } from 'path-scurry'
import { Pattern } from './pattern.js'
import type { GlobWalkerOpts } from './walker.js'
export interface IgnoreLike {
ignored?: (p: Path) => boolean
childrenIgnored?: (p: Path) => boolean
add?: (ignore: string) => void
}
const defaultPlatform: NodeJS.Platform =
(
typeof process === 'object' &&
process &&
typeof process.platform === 'string'
) ?
process.platform
: 'linux'
/**
* Class used to process ignored patterns
*/
export class Ignore implements IgnoreLike {
relative: Minimatch[]
relativeChildren: Minimatch[]
absolute: Minimatch[]
absoluteChildren: Minimatch[]
platform: NodeJS.Platform
mmopts: MinimatchOptions
constructor(
ignored: string[],
{
nobrace,
nocase,
noext,
noglobstar,
platform = defaultPlatform,
}: GlobWalkerOpts,
) {
this.relative = []
this.absolute = []
this.relativeChildren = []
this.absoluteChildren = []
this.platform = platform
this.mmopts = {
dot: true,
nobrace,
nocase,
noext,
noglobstar,
optimizationLevel: 2,
platform,
nocomment: true,
nonegate: true,
}
for (const ign of ignored) this.add(ign)
}
add(ign: string) {
// this is a little weird, but it gives us a clean set of optimized
// minimatch matchers, without getting tripped up if one of them
// ends in /** inside a brace section, and it's only inefficient at
// the start of the walk, not along it.
// It'd be nice if the Pattern class just had a .test() method, but
// handling globstars is a bit of a pita, and that code already lives
// in minimatch anyway.
// Another way would be if maybe Minimatch could take its set/globParts
// as an option, and then we could at least just use Pattern to test
// for absolute-ness.
// Yet another way, Minimatch could take an array of glob strings, and
// a cwd option, and do the right thing.
const mm = new Minimatch(ign, this.mmopts)
for (let i = 0; i < mm.set.length; i++) {
const parsed = mm.set[i]
const globParts = mm.globParts[i]
/* c8 ignore start */
if (!parsed || !globParts) {
throw new Error('invalid pattern object')
}
// strip off leading ./ portions
// https://github.com/isaacs/node-glob/issues/570
while (parsed[0] === '.' && globParts[0] === '.') {
parsed.shift()
globParts.shift()
}
/* c8 ignore stop */
const p = new Pattern(parsed, globParts, 0, this.platform)
const m = new Minimatch(p.globString(), this.mmopts)
const children = globParts[globParts.length - 1] === '**'
const absolute = p.isAbsolute()
if (absolute) this.absolute.push(m)
else this.relative.push(m)
if (children) {
if (absolute) this.absoluteChildren.push(m)
else this.relativeChildren.push(m)
}
}
}
ignored(p: Path): boolean {
const fullpath = p.fullpath()
const fullpaths = `${fullpath}/`
const relative = p.relative() || '.'
const relatives = `${relative}/`
for (const m of this.relative) {
if (m.match(relative) || m.match(relatives)) return true
}
for (const m of this.absolute) {
if (m.match(fullpath) || m.match(fullpaths)) return true
}
return false
}
childrenIgnored(p: Path): boolean {
const fullpath = `${p.fullpath()}/`
const relative = `${p.relative() || '.'}/`
for (const m of this.relativeChildren) {
if (m.match(relative)) return true
}
for (const m of this.absoluteChildren) {
if (m.match(fullpath)) return true
}
return false
}
}
================================================
FILE: src/index.ts
================================================
import { escape, unescape } from 'minimatch'
import type { Minipass } from 'minipass'
import type { Path } from 'path-scurry'
import type {
GlobOptions,
GlobOptionsWithFileTypesFalse,
GlobOptionsWithFileTypesTrue,
GlobOptionsWithFileTypesUnset,
} from './glob.js'
import { Glob } from './glob.js'
import { hasMagic } from './has-magic.js'
export { escape, unescape } from 'minimatch'
export type {
FSOption,
Path,
WalkOptions,
WalkOptionsWithFileTypesTrue,
WalkOptionsWithFileTypesUnset,
} from 'path-scurry'
export { Glob } from './glob.js'
export type {
GlobOptions,
GlobOptionsWithFileTypesFalse,
GlobOptionsWithFileTypesTrue,
GlobOptionsWithFileTypesUnset,
} from './glob.js'
export { hasMagic } from './has-magic.js'
export { Ignore } from './ignore.js'
export type { IgnoreLike } from './ignore.js'
export type { MatchStream } from './walker.js'
/**
* Syncronous form of {@link globStream}. Will read all the matches as fast as
* you consume them, even all in a single tick if you consume them immediately,
* but will still respond to backpressure if they're not consumed immediately.
*/
export function globStreamSync(
pattern: string | string[],
options: GlobOptionsWithFileTypesTrue,
): Minipass<Path, Path>
export function globStreamSync(
pattern: string | string[],
options: GlobOptionsWithFileTypesFalse,
): Minipass<string, string>
export function globStreamSync(
pattern: string | string[],
options: GlobOptionsWithFileTypesUnset,
): Minipass<string, string>
export function globStreamSync(
pattern: string | string[],
options: GlobOptions,
): Minipass<Path, Path> | Minipass<string, string>
export function globStreamSync(
pattern: string | string[],
options: GlobOptions = {},
) {
return new Glob(pattern, options).streamSync()
}
/**
* Return a stream that emits all the strings or `Path` objects and
* then emits `end` when completed.
*/
export function globStream(
pattern: string | string[],
options: GlobOptionsWithFileTypesFalse,
): Minipass<string, string>
export function globStream(
pattern: string | string[],
options: GlobOptionsWithFileTypesTrue,
): Minipass<Path, Path>
export function globStream(
pattern: string | string[],
options?: GlobOptionsWithFileTypesUnset | undefined,
): Minipass<string, string>
export function globStream(
pattern: string | string[],
options: GlobOptions,
): Minipass<Path, Path> | Minipass<string, string>
export function globStream(
pattern: string | string[],
options: GlobOptions = {},
) {
return new Glob(pattern, options).stream()
}
/**
* Synchronous form of {@link glob}
*/
export function globSync(
pattern: string | string[],
options: GlobOptionsWithFileTypesFalse,
): string[]
export function globSync(
pattern: string | string[],
options: GlobOptionsWithFileTypesTrue,
): Path[]
export function globSync(
pattern: string | string[],
options?: GlobOptionsWithFileTypesUnset | undefined,
): string[]
export function globSync(
pattern: string | string[],
options: GlobOptions,
): Path[] | string[]
export function globSync(
pattern: string | string[],
options: GlobOptions = {},
) {
return new Glob(pattern, options).walkSync()
}
/**
* Perform an asynchronous glob search for the pattern(s) specified. Returns
* [Path](https://isaacs.github.io/path-scurry/classes/PathBase) objects if the
* {@link withFileTypes} option is set to `true`. See {@link GlobOptions} for
* full option descriptions.
*/
async function glob_(
pattern: string | string[],
options?: GlobOptionsWithFileTypesUnset | undefined,
): Promise<string[]>
async function glob_(
pattern: string | string[],
options: GlobOptionsWithFileTypesTrue,
): Promise<Path[]>
async function glob_(
pattern: string | string[],
options: GlobOptionsWithFileTypesFalse,
): Promise<string[]>
async function glob_(
pattern: string | string[],
options: GlobOptions,
): Promise<Path[] | string[]>
async function glob_(
pattern: string | string[],
options: GlobOptions = {},
) {
return new Glob(pattern, options).walk()
}
/**
* Return a sync iterator for walking glob pattern matches.
*/
export function globIterateSync(
pattern: string | string[],
options?: GlobOptionsWithFileTypesUnset | undefined,
): Generator<string, void, void>
export function globIterateSync(
pattern: string | string[],
options: GlobOptionsWithFileTypesTrue,
): Generator<Path, void, void>
export function globIterateSync(
pattern: string | string[],
options: GlobOptionsWithFileTypesFalse,
): Generator<string, void, void>
export function globIterateSync(
pattern: string | string[],
options: GlobOptions,
): Generator<Path, void, void> | Generator<string, void, void>
export function globIterateSync(
pattern: string | string[],
options: GlobOptions = {},
) {
return new Glob(pattern, options).iterateSync()
}
/**
* Return an async iterator for walking glob pattern matches.
*/
export function globIterate(
pattern: string | string[],
options?: GlobOptionsWithFileTypesUnset | undefined,
): AsyncGenerator<string, void, void>
export function globIterate(
pattern: string | string[],
options: GlobOptionsWithFileTypesTrue,
): AsyncGenerator<Path, void, void>
export function globIterate(
pattern: string | string[],
options: GlobOptionsWithFileTypesFalse,
): AsyncGenerator<string, void, void>
export function globIterate(
pattern: string | string[],
options: GlobOptions,
): AsyncGenerator<Path, void, void> | AsyncGenerator<string, void, void>
export function globIterate(
pattern: string | string[],
options: GlobOptions = {},
) {
return new Glob(pattern, options).iterate()
}
// aliases: glob.sync.stream() glob.stream.sync() glob.sync() etc
export const streamSync = globStreamSync
export const stream = Object.assign(globStream, { sync: globStreamSync })
export const iterateSync = globIterateSync
export const iterate = Object.assign(globIterate, {
sync: globIterateSync,
})
export const sync = Object.assign(globSync, {
stream: globStreamSync,
iterate: globIterateSync,
})
export const glob = Object.assign(glob_, {
glob: glob_,
globSync,
sync,
globStream,
stream,
globStreamSync,
streamSync,
globIterate,
iterate,
globIterateSync,
iterateSync,
Glob,
hasMagic,
escape,
unescape,
})
glob.glob = glob
================================================
FILE: src/pattern.ts
================================================
// this is just a very light wrapper around 2 arrays with an offset index
import { GLOBSTAR } from 'minimatch'
export type MMPattern = string | RegExp | typeof GLOBSTAR
// an array of length >= 1
export type PatternList = [p: MMPattern, ...rest: MMPattern[]]
export type UNCPatternList = [
p0: '',
p1: '',
p2: string,
p3: string,
...rest: MMPattern[],
]
export type DrivePatternList = [p0: string, ...rest: MMPattern[]]
export type AbsolutePatternList = [p0: '', ...rest: MMPattern[]]
export type GlobList = [p: string, ...rest: string[]]
const isPatternList = (pl: MMPattern[]): pl is PatternList =>
pl.length >= 1
const isGlobList = (gl: string[]): gl is GlobList => gl.length >= 1
const customInspect = Symbol.for('nodejs.util.inspect.custom')
/**
* An immutable-ish view on an array of glob parts and their parsed
* results
*/
export class Pattern {
readonly #patternList: PatternList
readonly #globList: GlobList
readonly #index: number
readonly length: number
readonly #platform: NodeJS.Platform
#rest?: Pattern | null
#globString?: string
#isDrive?: boolean
#isUNC?: boolean
#isAbsolute?: boolean
#followGlobstar: boolean = true
constructor(
patternList: MMPattern[],
globList: string[],
index: number,
platform: NodeJS.Platform,
) {
if (!isPatternList(patternList)) {
throw new TypeError('empty pattern list')
}
if (!isGlobList(globList)) {
throw new TypeError('empty glob list')
}
if (globList.length !== patternList.length) {
throw new TypeError('mismatched pattern list and glob list lengths')
}
this.length = patternList.length
if (index < 0 || index >= this.length) {
throw new TypeError('index out of range')
}
this.#patternList = patternList
this.#globList = globList
this.#index = index
this.#platform = platform
// normalize root entries of absolute patterns on initial creation.
if (this.#index === 0) {
// c: => ['c:/']
// C:/ => ['C:/']
// C:/x => ['C:/', 'x']
// //host/share => ['//host/share/']
// //host/share/ => ['//host/share/']
// //host/share/x => ['//host/share/', 'x']
// /etc => ['/', 'etc']
// / => ['/']
if (this.isUNC()) {
// '' / '' / 'host' / 'share'
const [p0, p1, p2, p3, ...prest] = this.#patternList
const [g0, g1, g2, g3, ...grest] = this.#globList
if (prest[0] === '') {
// ends in /
prest.shift()
grest.shift()
}
const p = [p0, p1, p2, p3, ''].join('/')
const g = [g0, g1, g2, g3, ''].join('/')
this.#patternList = [p, ...prest]
this.#globList = [g, ...grest]
this.length = this.#patternList.length
} else if (this.isDrive() || this.isAbsolute()) {
const [p1, ...prest] = this.#patternList
const [g1, ...grest] = this.#globList
if (prest[0] === '') {
// ends in /
prest.shift()
grest.shift()
}
const p = `${p1 as string}/`
const g = `${g1}/`
this.#patternList = [p, ...prest]
this.#globList = [g, ...grest]
this.length = this.#patternList.length
}
}
}
[customInspect]() {
return `Pattern <${this.#globList.slice(this.#index).join('/')}>`
}
/**
* The first entry in the parsed list of patterns
*/
pattern(): MMPattern {
return this.#patternList[this.#index] as MMPattern
}
/**
* true of if pattern() returns a string
*/
isString(): boolean {
return typeof this.#patternList[this.#index] === 'string'
}
/**
* true of if pattern() returns GLOBSTAR
*/
isGlobstar(): boolean {
return this.#patternList[this.#index] === GLOBSTAR
}
/**
* true if pattern() returns a regexp
*/
isRegExp(): boolean {
return this.#patternList[this.#index] instanceof RegExp
}
/**
* The /-joined set of glob parts that make up this pattern
*/
globString(): string {
return (this.#globString =
this.#globString ||
(this.#index === 0 ?
this.isAbsolute() ?
this.#globList[0] + this.#globList.slice(1).join('/')
: this.#globList.join('/')
: this.#globList.slice(this.#index).join('/')))
}
/**
* true if there are more pattern parts after this one
*/
hasMore(): boolean {
return this.length > this.#index + 1
}
/**
* The rest of the pattern after this part, or null if this is the end
*/
rest(): Pattern | null {
if (this.#rest !== undefined) return this.#rest
if (!this.hasMore()) return (this.#rest = null)
this.#rest = new Pattern(
this.#patternList,
this.#globList,
this.#index + 1,
this.#platform,
)
this.#rest.#isAbsolute = this.#isAbsolute
this.#rest.#isUNC = this.#isUNC
this.#rest.#isDrive = this.#isDrive
return this.#rest
}
/**
* true if the pattern represents a //unc/path/ on windows
*/
isUNC(): boolean {
const pl = this.#patternList
return this.#isUNC !== undefined ?
this.#isUNC
: (this.#isUNC =
this.#platform === 'win32' &&
this.#index === 0 &&
pl[0] === '' &&
pl[1] === '' &&
typeof pl[2] === 'string' &&
!!pl[2] &&
typeof pl[3] === 'string' &&
!!pl[3])
}
// pattern like C:/...
// split = ['C:', ...]
// XXX: would be nice to handle patterns like `c:*` to test the cwd
// in c: for *, but I don't know of a way to even figure out what that
// cwd is without actually chdir'ing into it?
/**
* True if the pattern starts with a drive letter on Windows
*/
isDrive(): boolean {
const pl = this.#patternList
return this.#isDrive !== undefined ?
this.#isDrive
: (this.#isDrive =
this.#platform === 'win32' &&
this.#index === 0 &&
this.length > 1 &&
typeof pl[0] === 'string' &&
/^[a-z]:$/i.test(pl[0]))
}
// pattern = '/' or '/...' or '/x/...'
// split = ['', ''] or ['', ...] or ['', 'x', ...]
// Drive and UNC both considered absolute on windows
/**
* True if the pattern is rooted on an absolute path
*/
isAbsolute(): boolean {
const pl = this.#patternList
return this.#isAbsolute !== undefined ?
this.#isAbsolute
: (this.#isAbsolute =
(pl[0] === '' && pl.length > 1) ||
this.isDrive() ||
this.isUNC())
}
/**
* consume the root of the pattern, and return it
*/
root(): string {
const p = this.#patternList[0]
return (
typeof p === 'string' && this.isAbsolute() && this.#index === 0
) ?
p
: ''
}
/**
* Check to see if the current globstar pattern is allowed to follow
* a symbolic link.
*/
checkFollowGlobstar(): boolean {
return !(
this.#index === 0 ||
!this.isGlobstar() ||
!this.#followGlobstar
)
}
/**
* Mark that the current globstar pattern is following a symbolic link
*/
markFollowGlobstar(): boolean {
if (this.#index === 0 || !this.isGlobstar() || !this.#followGlobstar)
return false
this.#followGlobstar = false
return true
}
}
================================================
FILE: src/processor.ts
================================================
// synchronous utility for filtering entries and calculating subwalks
import type { MMRegExp } from 'minimatch'
import { GLOBSTAR } from 'minimatch'
import type { Path } from 'path-scurry'
import type { MMPattern, Pattern } from './pattern.js'
import type { GlobWalkerOpts } from './walker.js'
/**
* A cache of which patterns have been processed for a given Path
*/
export class HasWalkedCache {
store: Map<string, Set<string>>
constructor(store: Map<string, Set<string>> = new Map()) {
this.store = store
}
copy() {
return new HasWalkedCache(new Map(this.store))
}
hasWalked(target: Path, pattern: Pattern) {
return this.store.get(target.fullpath())?.has(pattern.globString())
}
storeWalked(target: Path, pattern: Pattern) {
const fullpath = target.fullpath()
const cached = this.store.get(fullpath)
if (cached) cached.add(pattern.globString())
else this.store.set(fullpath, new Set([pattern.globString()]))
}
}
/**
* A record of which paths have been matched in a given walk step,
* and whether they only are considered a match if they are a directory,
* and whether their absolute or relative path should be returned.
*/
export class MatchRecord {
store: Map<Path, number> = new Map()
add(target: Path, absolute: boolean, ifDir: boolean) {
const n = (absolute ? 2 : 0) | (ifDir ? 1 : 0)
const current = this.store.get(target)
this.store.set(target, current === undefined ? n : n & current)
}
// match, absolute, ifdir
entries(): [Path, boolean, boolean][] {
return [...this.store.entries()].map(([path, n]) => [
path,
!!(n & 2),
!!(n & 1),
])
}
}
/**
* A collection of patterns that must be processed in a subsequent step
* for a given path.
*/
export class SubWalks {
store: Map<Path, Pattern[]> = new Map()
add(target: Path, pattern: Pattern) {
if (!target.canReaddir()) {
return
}
const subs = this.store.get(target)
if (subs) {
if (!subs.find(p => p.globString() === pattern.globString())) {
subs.push(pattern)
}
} else this.store.set(target, [pattern])
}
get(target: Path): Pattern[] {
const subs = this.store.get(target)
/* c8 ignore start */
if (!subs) {
throw new Error('attempting to walk unknown path')
}
/* c8 ignore stop */
return subs
}
entries(): [Path, Pattern[]][] {
return this.keys().map(k => [k, this.store.get(k) as Pattern[]])
}
keys(): Path[] {
return [...this.store.keys()].filter(t => t.canReaddir())
}
}
/**
* The class that processes patterns for a given path.
*
* Handles child entry filtering, and determining whether a path's
* directory contents must be read.
*/
export class Processor {
hasWalkedCache: HasWalkedCache
matches = new MatchRecord()
subwalks = new SubWalks()
patterns?: Pattern[]
follow: boolean
dot: boolean
opts: GlobWalkerOpts
constructor(opts: GlobWalkerOpts, hasWalkedCache?: HasWalkedCache) {
this.opts = opts
this.follow = !!opts.follow
this.dot = !!opts.dot
this.hasWalkedCache =
hasWalkedCache ? hasWalkedCache.copy() : new HasWalkedCache()
}
processPatterns(target: Path, patterns: Pattern[]) {
this.patterns = patterns
const processingSet: [Path, Pattern][] = patterns.map(p => [target, p])
// map of paths to the magic-starting subwalks they need to walk
// first item in patterns is the filter
for (let [t, pattern] of processingSet) {
this.hasWalkedCache.storeWalked(t, pattern)
const root = pattern.root()
const absolute = pattern.isAbsolute() && this.opts.absolute !== false
// start absolute patterns at root
if (root) {
t = t.resolve(
root === '/' && this.opts.root !== undefined ?
this.opts.root
: root,
)
const rest = pattern.rest()
if (!rest) {
this.matches.add(t, true, false)
continue
} else {
pattern = rest
}
}
if (t.isENOENT()) continue
let p: MMPattern
let rest: Pattern | null
let changed = false
while (
typeof (p = pattern.pattern()) === 'string' &&
(rest = pattern.rest())
) {
const c = t.resolve(p)
t = c
pattern = rest
changed = true
}
p = pattern.pattern()
rest = pattern.rest()
if (changed) {
if (this.hasWalkedCache.hasWalked(t, pattern)) continue
this.hasWalkedCache.storeWalked(t, pattern)
}
// now we have either a final string for a known entry,
// more strings for an unknown entry,
// or a pattern starting with magic, mounted on t.
if (typeof p === 'string') {
// must not be final entry, otherwise we would have
// concatenated it earlier.
const ifDir = p === '..' || p === '' || p === '.'
this.matches.add(t.resolve(p), absolute, ifDir)
continue
} else if (p === GLOBSTAR) {
// if no rest, match and subwalk pattern
// if rest, process rest and subwalk pattern
// if it's a symlink, but we didn't get here by way of a
// globstar match (meaning it's the first time THIS globstar
// has traversed a symlink), then we follow it. Otherwise, stop.
if (
!t.isSymbolicLink() ||
this.follow ||
pattern.checkFollowGlobstar()
) {
this.subwalks.add(t, pattern)
}
const rp = rest?.pattern()
const rrest = rest?.rest()
if (!rest || ((rp === '' || rp === '.') && !rrest)) {
// only HAS to be a dir if it ends in **/ or **/.
// but ending in ** will match files as well.
this.matches.add(t, absolute, rp === '' || rp === '.')
} else {
if (rp === '..') {
// this would mean you're matching **/.. at the fs root,
// and no thanks, I'm not gonna test that specific case.
/* c8 ignore start */
const tp = t.parent || t
/* c8 ignore stop */
if (!rrest) this.matches.add(tp, absolute, true)
else if (!this.hasWalkedCache.hasWalked(tp, rrest)) {
this.subwalks.add(tp, rrest)
}
}
}
} else if (p instanceof RegExp) {
this.subwalks.add(t, pattern)
}
}
return this
}
subwalkTargets(): Path[] {
return this.subwalks.keys()
}
child() {
return new Processor(this.opts, this.hasWalkedCache)
}
// return a new Processor containing the subwalks for each
// child entry, and a set of matches, and
// a hasWalkedCache that's a copy of this one
// then we're going to call
filterEntries(parent: Path, entries: Path[]): Processor {
const patterns = this.subwalks.get(parent)
// put matches and entry walks into the results processor
const results = this.child()
for (const e of entries) {
for (const pattern of patterns) {
const absolute = pattern.isAbsolute()
const p = pattern.pattern()
const rest = pattern.rest()
if (p === GLOBSTAR) {
results.testGlobstar(e, pattern, rest, absolute)
} else if (p instanceof RegExp) {
results.testRegExp(e, p, rest, absolute)
} else {
results.testString(e, p, rest, absolute)
}
}
}
return results
}
testGlobstar(
e: Path,
pattern: Pattern,
rest: Pattern | null,
absolute: boolean,
) {
if (this.dot || !e.name.startsWith('.')) {
if (!pattern.hasMore()) {
this.matches.add(e, absolute, false)
}
if (e.canReaddir()) {
// if we're in follow mode or it's not a symlink, just keep
// testing the same pattern. If there's more after the globstar,
// then this symlink consumes the globstar. If not, then we can
// follow at most ONE symlink along the way, so we mark it, which
// also checks to ensure that it wasn't already marked.
if (this.follow || !e.isSymbolicLink()) {
this.subwalks.add(e, pattern)
} else if (e.isSymbolicLink()) {
if (rest && pattern.checkFollowGlobstar()) {
this.subwalks.add(e, rest)
} else if (pattern.markFollowGlobstar()) {
this.subwalks.add(e, pattern)
}
}
}
}
// if the NEXT thing matches this entry, then also add
// the rest.
if (rest) {
const rp = rest.pattern()
if (
typeof rp === 'string' &&
// dots and empty were handled already
rp !== '..' &&
rp !== '' &&
rp !== '.'
) {
this.testString(e, rp, rest.rest(), absolute)
} else if (rp === '..') {
/* c8 ignore start */
const ep = e.parent || e
/* c8 ignore stop */
this.subwalks.add(ep, rest)
} else if (rp instanceof RegExp) {
this.testRegExp(e, rp, rest.rest(), absolute)
}
}
}
testRegExp(
e: Path,
p: MMRegExp,
rest: Pattern | null,
absolute: boolean,
) {
if (!p.test(e.name)) return
if (!rest) {
this.matches.add(e, absolute, false)
} else {
this.subwalks.add(e, rest)
}
}
testString(e: Path, p: string, rest: Pattern | null, absolute: boolean) {
// should never happen?
if (!e.isNamed(p)) return
if (!rest) {
this.matches.add(e, absolute, false)
} else {
this.subwalks.add(e, rest)
}
}
}
================================================
FILE: src/walker.ts
================================================
/**
* Single-use utility classes to provide functionality to the {@link Glob}
* methods.
*
* @module
*/
import { Minipass } from 'minipass'
import type { Path } from 'path-scurry'
import type { IgnoreLike } from './ignore.js'
import { Ignore } from './ignore.js'
// XXX can we somehow make it so that it NEVER processes a given path more than
// once, enough that the match set tracking is no longer needed? that'd speed
// things up a lot. Or maybe bring back nounique, and skip it in that case?
// a single minimatch set entry with 1 or more parts
import type { Pattern } from './pattern.js'
import { Processor } from './processor.js'
export interface GlobWalkerOpts {
absolute?: boolean
allowWindowsEscape?: boolean
cwd?: string | URL
dot?: boolean
dotRelative?: boolean
follow?: boolean
ignore?: string | string[] | IgnoreLike
mark?: boolean
matchBase?: boolean
// Note: maxDepth here means "maximum actual Path.depth()",
// not "maximum depth beyond cwd"
maxDepth?: number
nobrace?: boolean
nocase?: boolean
nodir?: boolean
noext?: boolean
noglobstar?: boolean
platform?: NodeJS.Platform
posix?: boolean
realpath?: boolean
root?: string
stat?: boolean
signal?: AbortSignal
windowsPathsNoEscape?: boolean
withFileTypes?: boolean
includeChildMatches?: boolean
}
export type GWOFileTypesTrue = GlobWalkerOpts & {
withFileTypes: true
}
export type GWOFileTypesFalse = GlobWalkerOpts & {
withFileTypes: false
}
export type GWOFileTypesUnset = GlobWalkerOpts & {
withFileTypes?: undefined
}
export type Result<O extends GlobWalkerOpts> =
O extends GWOFileTypesTrue ? Path
: O extends GWOFileTypesFalse ? string
: O extends GWOFileTypesUnset ? string
: Path | string
export type Matches<O extends GlobWalkerOpts> =
O extends GWOFileTypesTrue ? Set<Path>
: O extends GWOFileTypesFalse ? Set<string>
: O extends GWOFileTypesUnset ? Set<string>
: Set<Path | string>
export type MatchStream<O extends GlobWalkerOpts> = Minipass<
Result<O>,
Result<O>
>
const makeIgnore = (
ignore: string | string[] | IgnoreLike,
opts: GlobWalkerOpts,
): IgnoreLike =>
typeof ignore === 'string' ? new Ignore([ignore], opts)
: Array.isArray(ignore) ? new Ignore(ignore, opts)
: ignore
/**
* basic walking utilities that all the glob walker types use
*/
export abstract class GlobUtil<O extends GlobWalkerOpts = GlobWalkerOpts> {
path: Path
patterns: Pattern[]
opts: O
seen: Set<Path> = new Set<Path>()
paused: boolean = false
aborted: boolean = false
#onResume: (() => unknown)[] = []
#ignore?: IgnoreLike
#sep: '\\' | '/'
signal?: AbortSignal
maxDepth: number
includeChildMatches: boolean
constructor(patterns: Pattern[], path: Path, opts: O)
constructor(patterns: Pattern[], path: Path, opts: O) {
this.patterns = patterns
this.path = path
this.opts = opts
this.#sep = !opts.posix && opts.platform === 'win32' ? '\\' : '/'
this.includeChildMatches = opts.includeChildMatches !== false
if (opts.ignore || !this.includeChildMatches) {
this.#ignore = makeIgnore(opts.ignore ?? [], opts)
if (
!this.includeChildMatches &&
typeof this.#ignore.add !== 'function'
) {
const m = 'cannot ignore child matches, ignore lacks add() method.'
throw new Error(m)
}
}
// ignore, always set with maxDepth, but it's optional on the
// GlobOptions type
/* c8 ignore start */
this.maxDepth = opts.maxDepth || Infinity
/* c8 ignore stop */
if (opts.signal) {
this.signal = opts.signal
this.signal.addEventListener('abort', () => {
this.#onResume.length = 0
})
}
}
#ignored(path: Path): boolean {
return this.seen.has(path) || !!this.#ignore?.ignored?.(path)
}
#childrenIgnored(path: Path): boolean {
return !!this.#ignore?.childrenIgnored?.(path)
}
// backpressure mechanism
pause() {
this.paused = true
}
resume() {
/* c8 ignore start */
if (this.signal?.aborted) return
/* c8 ignore stop */
this.paused = false
let fn: (() => unknown) | undefined = undefined
while (!this.paused && (fn = this.#onResume.shift())) {
fn()
}
}
onResume(fn: () => unknown) {
if (this.signal?.aborted) return
/* c8 ignore start */
if (!this.paused) {
fn()
} else {
/* c8 ignore stop */
this.#onResume.push(fn)
}
}
// do the requisite realpath/stat checking, and return the path
// to add or undefined to filter it out.
async matchCheck(
inPath: Path,
ifDir: boolean,
): Promise<Path | undefined> {
if (ifDir && this.opts.nodir) return undefined
let rpc: Path | undefined
let e: Path
if (this.opts.realpath) {
rpc = inPath.realpathCached() || (await inPath.realpath())
if (!rpc) return undefined
e = rpc
} else {
e = inPath
}
const needStat = e.isUnknown() || this.opts.stat
const s = needStat ? await e.lstat() : e
if (this.opts.follow && this.opts.nodir && s?.isSymbolicLink()) {
const target = await s.realpath()
/* c8 ignore start */
if (target && (target.isUnknown() || this.opts.stat)) {
await target.lstat()
}
/* c8 ignore stop */
}
return this.matchCheckTest(s, ifDir)
}
matchCheckTest(e: Path | undefined, ifDir: boolean): Path | undefined {
return (
e &&
(this.maxDepth === Infinity || e.depth() <= this.maxDepth) &&
(!ifDir || e.canReaddir()) &&
(!this.opts.nodir || !e.isDirectory()) &&
(!this.opts.nodir ||
!this.opts.follow ||
!e.isSymbolicLink() ||
!e.realpathCached()?.isDirectory()) &&
!this.#ignored(e)
) ?
e
: undefined
}
matchCheckSync(inPath: Path, ifDir: boolean): Path | undefined {
if (ifDir && this.opts.nodir) return undefined
let rpc: Path | undefined
let e: Path
if (this.opts.realpath) {
rpc = inPath.realpathCached() || inPath.realpathSync()
if (!rpc) return undefined
e = rpc
} else {
e = inPath
}
const needStat = e.isUnknown() || this.opts.stat
const s = needStat ? e.lstatSync() : e
if (this.opts.follow && this.opts.nodir && s?.isSymbolicLink()) {
const target = s.realpathSync()
if (target && (target?.isUnknown() || this.opts.stat)) {
target.lstatSync()
}
}
return this.matchCheckTest(s, ifDir)
}
abstract matchEmit(p: Result<O>): void
abstract matchEmit(p: string | Path): void
matchFinish(e: Path, absolute: boolean) {
if (this.#ignored(e)) return
// we know we have an ignore if this is false, but TS doesn't
if (!this.includeChildMatches && this.#ignore?.add) {
const ign = `${e.relativePosix()}/**`
this.#ignore.add(ign)
}
const abs =
this.opts.absolute === undefined ? absolute : this.opts.absolute
this.seen.add(e)
const mark = this.opts.mark && e.isDirectory() ? this.#sep : ''
// ok, we have what we need!
if (this.opts.withFileTypes) {
this.matchEmit(e)
} else if (abs) {
const abs = this.opts.posix ? e.fullpathPosix() : e.fullpath()
this.matchEmit(abs + mark)
} else {
const rel = this.opts.posix ? e.relativePosix() : e.relative()
const pre =
this.opts.dotRelative && !rel.startsWith(`..${this.#sep}`) ?
`.${this.#sep}`
: ''
this.matchEmit(!rel ? `.${mark}` : pre + rel + mark)
}
}
async match(e: Path, absolute: boolean, ifDir: boolean): Promise<void> {
const p = await this.matchCheck(e, ifDir)
if (p) this.matchFinish(p, absolute)
}
matchSync(e: Path, absolute: boolean, ifDir: boolean): void {
const p = this.matchCheckSync(e, ifDir)
if (p) this.matchFinish(p, absolute)
}
walkCB(target: Path, patterns: Pattern[], cb: () => unknown) {
/* c8 ignore start */
if (this.signal?.aborted) cb()
/* c8 ignore stop */
this.walkCB2(target, patterns, new Processor(this.opts), cb)
}
walkCB2(
target: Path,
patterns: Pattern[],
processor: Processor,
cb: () => unknown,
) {
if (this.#childrenIgnored(target)) return cb()
if (this.signal?.aborted) cb()
if (this.paused) {
this.onResume(() => this.walkCB2(target, patterns, processor, cb))
return
}
processor.processPatterns(target, patterns)
// done processing. all of the above is sync, can be abstracted out.
// subwalks is a map of paths to the entry filters they need
// matches is a map of paths to [absolute, ifDir] tuples.
let tasks = 1
const next = () => {
if (--tasks === 0) cb()
}
for (const [m, absolute, ifDir] of processor.matches.entries()) {
if (this.#ignored(m)) continue
tasks++
void this.match(m, absolute, ifDir).then(() => next())
}
for (const t of processor.subwalkTargets()) {
if (this.maxDepth !== Infinity && t.depth() >= this.maxDepth) {
continue
}
tasks++
const childrenCached = t.readdirCached()
if (t.calledReaddir())
this.walkCB3(t, childrenCached, processor, next)
else {
t.readdirCB(
(_, entries) => this.walkCB3(t, entries, processor, next),
true,
)
}
}
next()
}
walkCB3(
target: Path,
entries: Path[],
processorx: Processor,
cb: () => unknown,
) {
const proc = processorx.filterEntries(target, entries)
let tasks = 1
const next = () => {
if (--tasks === 0) cb()
}
for (const [m, absolute, ifDir] of proc.matches.entries()) {
if (this.#ignored(m)) continue
tasks++
void this.match(m, absolute, ifDir).then(() => next())
}
for (const [target, patterns] of proc.subwalks.entries()) {
tasks++
this.walkCB2(target, patterns, proc.child(), next)
}
next()
}
walkCBSync(target: Path, patterns: Pattern[], cb: () => unknown) {
/* c8 ignore start */
if (this.signal?.aborted) cb()
/* c8 ignore stop */
this.walkCB2Sync(target, patterns, new Processor(this.opts), cb)
}
walkCB2Sync(
target: Path,
patterns: Pattern[],
processor: Processor,
cb: () => unknown,
) {
if (this.#childrenIgnored(target)) return cb()
if (this.signal?.aborted) cb()
if (this.paused) {
this.onResume(() =>
this.walkCB2Sync(target, patterns, processor, cb),
)
return
}
processor.processPatterns(target, patterns)
// done processing. all of the above is sync, can be abstracted out.
// subwalks is a map of paths to the entry filters they need
// matches is a map of paths to [absolute, ifDir] tuples.
let tasks = 1
const next = () => {
if (--tasks === 0) cb()
}
for (const [m, absolute, ifDir] of processor.matches.entries()) {
if (this.#ignored(m)) continue
this.matchSync(m, absolute, ifDir)
}
for (const t of processor.subwalkTargets()) {
if (this.maxDepth !== Infinity && t.depth() >= this.maxDepth) {
continue
}
tasks++
const children = t.readdirSync()
this.walkCB3Sync(t, children, processor, next)
}
next()
}
walkCB3Sync(
target: Path,
entries: Path[],
processor: Processor,
cb: () => unknown,
) {
const proc = processor.filterEntries(target, entries)
let tasks = 1
const next = () => {
if (--tasks === 0) cb()
}
for (const [m, absolute, ifDir] of proc.matches.entries()) {
if (this.#ignored(m)) continue
this.matchSync(m, absolute, ifDir)
}
for (const [target, patterns] of proc.subwalks.entries()) {
tasks++
this.walkCB2Sync(target, patterns, proc.child(), next)
}
next()
}
}
export class GlobWalker<
O extends GlobWalkerOpts = GlobWalkerOpts,
> extends GlobUtil<O> {
matches = new Set<Result<O>>()
constructor(patterns: Pattern[], path: Path, opts: O) {
super(patterns, path, opts)
}
matchEmit(e: Result<O>): void {
this.matches.add(e)
}
async walk(): Promise<Set<Result<O>>> {
if (this.signal?.aborted) throw this.signal.reason
if (this.path.isUnknown()) {
await this.path.lstat()
}
await new Promise((res, rej) => {
this.walkCB(this.path, this.patterns, () => {
if (this.signal?.aborted) {
rej(this.signal.reason)
} else {
res(this.matches)
}
})
})
return this.matches
}
walkSync(): Set<Result<O>> {
if (this.signal?.aborted) throw this.signal.reason
if (this.path.isUnknown()) {
this.path.lstatSync()
}
// nothing for the callback to do, because this never pauses
this.walkCBSync(this.path, this.patterns, () => {
if (this.signal?.aborted) throw this.signal.reason
})
return this.matches
}
}
export class GlobStream<
O extends GlobWalkerOpts = GlobWalkerOpts,
> extends GlobUtil<O> {
results: Minipass<Result<O>, Result<O>>
constructor(patterns: Pattern[], path: Path, opts: O) {
super(patterns, path, opts)
this.results = new Minipass<Result<O>, Result<O>>({
signal: this.signal,
objectMode: true,
})
this.results.on('drain', () => this.resume())
this.results.on('resume', () => this.resume())
}
matchEmit(e: Result<O>): void {
this.results.write(e)
if (!this.results.flowing) this.pause()
}
stream(): MatchStream<O> {
const target = this.path
if (target.isUnknown()) {
void target.lstat().then(() => {
this.walkCB(target, this.patterns, () => this.results.end())
})
} else {
this.walkCB(target, this.patterns, () => this.results.end())
}
return this.results
}
streamSync(): MatchStream<O> {
if (this.path.isUnknown()) {
this.path.lstatSync()
}
this.walkCBSync(this.path, this.patterns, () => this.results.end())
return this.results
}
}
================================================
FILE: tap-snapshots/test/bin.ts.test.cjs
================================================
/* IMPORTANT
* This snapshot file is auto-generated, but designed for humans.
* It should be checked into source control and tracked carefully.
* Re-generate by setting TAP_SNAPSHOT=1 and running tests.
* Make sure to inspect the output below. Do not ignore changes!
*/
'use strict'
exports[`test/bin.ts > TAP > usage > -h shows usage 1`] = `
Object {
"args": Array [
"-h",
],
"code": 0,
"options": Object {},
"signal": null,
"stderr": "",
"stdout": String(
Usage:
glob [options] [<pattern> [<pattern> ...]]
Glob v{VERSION}
Expand the positional glob expression arguments into any matching file system
paths found.
-c<command> --cmd=<command>
Run the command provided, passing the glob expression
matches as arguments.
-p<pattern> --default=<pattern>
If no positional arguments are provided, glob will use
this pattern
--shell Interpret the command as a shell command by passing it
to the shell, with all matched filesystem paths
appended,
**even if this cannot be done safely**.
This is **not** unsafe (and usually unnecessary) when
using the known Unix shells sh, bash, zsh, and fish, as
these can all be executed in such a way as to pass
positional arguments safely.
**Note**: THIS IS UNSAFE IF THE FILE PATHS ARE
UNTRUSTED, because a path like \`'some/path/\\\\$\\\\(cmd)'\`
will be executed by the shell.
If you do have positional arguments that you wish to
pass to the command ahead of the glob pattern matches,
use the \`--cmd-arg\`/\`-g\` option instead.
The next major release of glob will fully remove the
ability to use this option unsafely.
-g<arg> --cmd-arg=<arg>
Pass the provided values to the supplied command, ahead
of the glob matches.
For example, the command:
glob -c echo -g"hello" -g"world" *.txt
might output:
hello world a.txt b.txt
This is a safer (and future-proof) alternative than
putting positional arguments in the \`-c\`/\`--cmd\`
option.
Can be set multiple times
-A --all By default, the glob cli command will not expand any
arguments that are an exact match to a file on disk.
This prevents double-expanding, in case the shell
expands an argument whose filename is a glob
expression.
For example, if 'app/*.ts' would match 'app/[id].ts',
then on Windows powershell or cmd.exe, 'glob app/*.ts'
will expand to 'app/[id].ts', as expected. However, in
posix shells such as bash or zsh, the shell will first
expand 'app/*.ts' to a list of filenames. Then glob
will look for a file matching 'app/[id].ts' (ie,
'app/i.ts' or 'app/d.ts'), which is unexpected.
Setting '--all' prevents this behavior, causing glob to
treat ALL patterns as glob expressions to be expanded,
even if they are an exact match to a file on disk.
When setting this option, be sure to enquote arguments
so that the shell will not expand them prior to passing
them to the glob command process.
-a --absolute Expand to absolute paths
-d --dot-relative Prepend './' on relative matches
-m --mark Append a / on any directories matched
-x --posix Always resolve to posix style paths, using '/' as the
directory separator, even on Windows. Drive letter
absolute matches on Windows will be expanded to their
full resolved UNC paths, eg instead of 'C:\\\\foo\\\\bar', it
will expand to '//?/C:/foo/bar'.
-f --follow Follow symlinked directories when expanding '**'
-R --realpath Call 'fs.realpath' on all of the results. In the case
of an entry that cannot be resolved, the entry is
omitted. This incurs a slight performance penalty, of
course, because of the added system calls.
-s --stat Call 'fs.lstat' on all entries, whether required or not
to determine if it's a valid match.
-b --match-base Perform a basename-only match if the pattern does not
contain any slash characters. That is, '*.js' would be
treated as equivalent to '**/*.js', matching js files
in all directories.
--dot Allow patterns to match files/directories that start
with '.', even if the pattern does not start with '.'
--nobrace Do not expand {...} patterns
--nocase Perform a case-insensitive match. This defaults to
'true' on macOS and Windows platforms, and false on all
others.
Note: 'nocase' should only be explicitly set when it is
known that the filesystem's case sensitivity differs
from the platform default. If set 'true' on
case-insensitive file systems, then the walk may return
more or less results than expected.
--nodir Do not match directories, only files.
Note: to *only* match directories, append a '/' at the
end of the pattern.
--noext Do not expand extglob patterns, such as '+(a|b)'
--noglobstar Do not expand '**' against multiple path portions. Ie,
treat it as a normal '*' instead.
--windows-path-no-escape
Use '\\\\' as a path separator *only*, and *never* as an
escape character. If set, all '\\\\' characters are
replaced with '/' in the pattern.
-D<n> --max-depth=<n> Maximum depth to traverse from the current working
directory
-C<cwd> --cwd=<cwd> Current working directory to execute/match in
-r<root> --root=<root> A string path resolved against the 'cwd', which is used
as the starting point for absolute patterns that start
with '/' (but not drive letters or UNC paths on
Windows).
Note that this *doesn't* necessarily limit the walk to
the 'root' directory, and doesn't affect the cwd
starting point for non-absolute patterns. A pattern
containing '..' will still be able to traverse out of
the root directory, if it is not an actual root
directory on the filesystem, and any non-absolute
patterns will still be matched in the 'cwd'.
To start absolute and non-absolute patterns in the same
path, you can use '--root=' to set it to the empty
string. However, be aware that on Windows systems, a
pattern like 'x:/*' or '//host/share/*' will *always*
start in the 'x:/' or '//host/share/' directory,
regardless of the --root setting.
--platform=<platform> Defaults to the value of 'process.platform' if
available, or 'linux' if not. Setting --platform=win32
on non-Windows systems may cause strange behavior!
Valid options: "aix", "android", "darwin", "freebsd",
"haiku", "linux", "openbsd", "sunos", "win32",
"cygwin", "netbsd"
-i<ignore> --ignore=<ignore>
Glob patterns to ignore
Can be set multiple times
-v --debug Output a huge amount of noisy debug information about
patterns as they are parsed and used to match files.
-V --version Output the version ({VERSION})
-h --help Show this usage information
),
}
`
exports[`test/bin.ts > TAP > version > --version shows version 1`] = `
Object {
"args": Array [
"--version",
],
"code": 0,
"options": Object {},
"signal": null,
"stderr": "",
"stdout": "{VERSION}\\n",
}
`
exports[`test/bin.ts > TAP > version > -V shows version 1`] = `
Object {
"args": Array [
"-V",
],
"code": 0,
"options": Object {},
"signal": null,
"stderr": "",
"stdout": "{VERSION}\\n",
}
`
================================================
FILE: tap-snapshots/test/pattern.ts.test.cjs
================================================
/* IMPORTANT
* This snapshot file is auto-generated, but designed for humans.
* It should be checked into source control and tracked carefully.
* Re-generate by setting TAP_SNAPSHOT=1 and running tests.
* Make sure to inspect the output below. Do not ignore changes!
*/
'use strict'
exports[`test/pattern.ts > TAP > g 1`] = `
Pattern <**>
`
exports[`test/pattern.ts > TAP > r 1`] = `
Pattern <?>
`
exports[`test/pattern.ts > TAP > s 1`] = `
Pattern <x>
`
================================================
FILE: tap-snapshots/test/root.ts.test.cjs
================================================
/* IMPORTANT
* This snapshot file is auto-generated, but designed for humans.
* It should be checked into source control and tracked carefully.
* Re-generate by setting TAP_SNAPSHOT=1 and running tests.
* Make sure to inspect the output below. Do not ignore changes!
*/
'use strict'
exports[`test/root.ts > TAP > set root option > absolute=false > async 1`] = `
Array [
"x/x/a",
"x/x/x/a",
"x/x/x/y",
"x/x/x/y/r",
"x/x/y",
"x/x/y/r",
"x/y",
"x/y/r",
"y/r",
]
`
exports[`test/root.ts > TAP > set root option > absolute=false > sync 1`] = `
Array [
"x/x/a",
"x/x/x/a",
"x/x/x/y",
"x/x/x/y/r",
"x/x/y",
"x/x/y/r",
"x/y",
"x/y/r",
"y/r",
]
`
exports[`test/root.ts > TAP > set root option > absolute=true > async 1`] = `
Array [
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/y/r",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/y/r",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/y/r",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/y/r",
]
`
exports[`test/root.ts > TAP > set root option > absolute=true > sync 1`] = `
Array [
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/y/r",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/y/r",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/y/r",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/y/r",
]
`
exports[`test/root.ts > TAP > set root option > absolute=undefined > async 1`] = `
Array [
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/y",
"x/x/x/y/r",
"x/x/y/r",
"x/y/r",
"y/r",
]
`
exports[`test/root.ts > TAP > set root option > absolute=undefined > sync 1`] = `
Array [
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/a",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/x/y",
"{CWD}/.tap/fixtures/test-root.ts-set-root-option/x/y",
"x/x/x/y/r",
"x/x/y/r",
"x/y/r",
"y/r",
]
`
================================================
FILE: test/00-setup.ts
================================================
// just a little pre-run script to set up the fixtures.
// zz-finish cleans it up
import { spawn } from 'child_process'
import { createWriteStream, promises } from 'fs'
import { mkdirp } from 'mkdirp'
import { join, dirname, resolve } from 'path'
import t from 'tap'
import { fileURLToPath } from 'url'
const { writeFile, symlink } = promises
t.pipe(createWriteStream('00-setup.tap'))
process.env.TAP_BAIL = '1'
const __dirname = fileURLToPath(new URL('.', import.meta.url))
const fixtureDir = resolve(__dirname, 'fixtures')
const filesUnresolved = [
'a/.abcdef/x/y/z/a',
'a/abcdef/g/h',
'a/abcfed/g/h',
'a/b/c/d',
'a/bc/e/f',
'a/c/d/c/b',
'a/cb/e/f',
'a/x/.y/b',
'a/z/.y/b',
]
const symlinkTo = resolve(fixtureDir, 'a/symlink/a/b/c')
const symlinkFrom = '../..'
const files = filesUnresolved.map(f => resolve(fixtureDir, f))
for (const file of files) {
t.test(file, { bail: true }, async () => {
const f = resolve(fixtureDir, file)
const d = dirname(f)
await mkdirp(d)
await writeFile(f, 'i like tests')
})
}
if (process.platform !== 'win32') {
t.test('symlinky', async () => {
const d = dirname(symlinkTo)
await mkdirp(d)
await symlink(symlinkFrom, symlinkTo, 'dir')
})
}
;['foo', 'bar', 'baz', 'asdf', 'quux', 'qwer', 'rewq'].forEach(
function (s) {
const w = `/tmp/glob-test/${s}`
t.test(`create ${w}`, async t => {
await mkdirp(w)
t.pass(w)
})
},
)
// generate the bash pattern test-fixtures if possible
if (process.platform === 'win32' || !process.env.TEST_REGEN) {
console.error('Windows, or TEST_REGEN unset. Using cached fixtures.')
} else {
const globs =
// put more patterns here.
// anything that would be directly in / should be in /tmp/glob-test
[
'a/c/d/*/b',
'a//c//d//*//b',
'a/*/d/*/b',
'a/*/+(c|g)/./d',
'a/**/[cg]/../[cg]',
'a/{b,c,d,e,f}/**/g',
'a/b/**',
'./**/g',
'a/abc{fed,def}/g/h',
'a/abc{fed/g,def}/**/',
'a/abc{fed/g,def}/**///**/',
// When a ** is the FIRST item in a pattern, it has
// more restrictive symbolic link handling behavior.
'**/a',
'**/a/**',
'./**/a',
'./**/a/**/',
'./**/a/**',
'./**/a/**/a/**/',
'+(a|b|c)/a{/,bc*}/**',
'*/*/*/f',
'./**/f',
'a/symlink/a/b/c/a/b/c/a/b/c//a/b/c////a/b/c/**/b/c/**',
'{./*/*,/tmp/glob-test/*}',
'{/tmp/glob-test/*,*}', // evil owl face! how you taunt me!
'a/!(symlink)/**',
'a/symlink/a/**/*',
// this one we don't quite match bash, because when bash
// applies the .. to the symlink walked by **, it effectively
// resets the symlink walk limit, and that is just a step too
// far for an edge case no one knows or cares about, even for
// an obsessive perfectionist like me.
// './a/**/../*/**',
'a/!(symlink)/**/..',
'a/!(symlink)/**/../',
'a/!(symlink)/**/../*',
'a/!(symlink)/**/../*/*',
]
const bashOutput: { [k: string]: string[] } = {}
for (const pattern of globs) {
t.test(`generate fixture ${pattern}`, t => {
const opts = [
'-O',
'globstar',
'-O',
'extglob',
'-O',
'nullglob',
'-c',
`for i in ${pattern}; do echo $i; done`,
]
const cp = spawn('bash', opts, { cwd: fixtureDir })
const out: Buffer[] = []
cp.stdout.on('data', c => out.push(c))
cp.stderr.pipe(process.stderr)
cp.on('close', function (code) {
const o = flatten(out)
bashOutput[pattern] = !o ? [] : cleanResults(o.split(/\r*\n/))
t.notOk(code, 'bash test should finish nicely')
t.end()
})
})
}
t.test('save fixtures', async () => {
const fname = resolve(__dirname, 'bash-results.ts')
const data = `// generated via 'npm run test-regen'
import { fileURLToPath } from 'url'
if (process.argv[1] === fileURLToPath(import.meta.url)) {
console.log('TAP version 14\\n1..1\\nok\\n')
}
export const bashResults:{ [path: string]: string[] } = ${JSON.stringify(
bashOutput,
null,
2,
)}
`
await writeFile(fname, data)
})
t.test('formatting', t => {
const c = spawn(
'prettier',
['--write', resolve(__dirname, 'bash-results.ts')],
{ stdio: ['ignore', 2, 2] },
)
c.on('close', (code, signal) => {
t.equal(code, 0, 'code')
t.equal(signal, null, 'signal')
t.end()
})
})
function cleanResults(m: string[]) {
// normalize discrepancies in ordering, duplication,
// and ending slashes.
return m
.map(m => join(m.replace(/\/$/, '').replace(/\/+/g, '/')))
.sort(alphasort)
.reduce(function (set: string[], f) {
if (f !== set[set.length - 1]) set.push(f)
return set
}, [])
.sort(alphasort)
.map(function (f) {
// de-windows
return process.platform !== 'win32' ?
f
: f.replace(/^[a-zA-Z]:\\\\/, '/').replace(/\\/g, '/')
})
}
const flatten = (chunks: Buffer[]) =>
Buffer.concat(chunks).toString().trim()
const alphasort = (a: string, b: string) =>
a.toLowerCase().localeCompare(b.toLowerCase(), 'en')
}
================================================
FILE: test/absolute-must-be-strings.ts
================================================
import { Glob } from '../dist/esm/index.js'
import t from 'tap'
t.throws(() => {
new Glob('.', {
withFileTypes: true,
absolute: true,
})
})
================================================
FILE: test/absolute.ts
================================================
import { isAbsolute } from 'path'
import type { Test } from 'tap'
import t from 'tap'
import { fileURLToPath } from 'url'
import { Glob } from '../dist/esm/index.js'
import { bashResults } from './bash-results.js'
const pattern = 'a/b/**'
const __dirname = fileURLToPath(new URL('.', import.meta.url))
process.chdir(`${__dirname}/fixtures`)
const ok = (t: Test, file: string) =>
t.ok(isAbsolute(file), 'must be absolute', { found: file })
var marks = [true, false]
for (const mark of marks) {
t.test(`mark=${mark}`, t => {
t.plan(2)
t.test('Emits absolute matches if option set', async t => {
var g = new Glob(pattern, { absolute: true, posix: true })
const results = await g.walk()
t.equal(
results.length,
bashResults[pattern]?.length,
'must match all files',
)
for (const m of results) {
t.ok(m.startsWith('/'), `starts with / ${m}`)
}
})
t.test('returns absolute results synchronously', async t => {
var g = new Glob(pattern, { absolute: true })
const results = g.walkSync()
t.equal(
results.length,
bashResults[pattern]?.length,
'must match all files',
)
for (const m of results) {
ok(t, m)
}
})
})
}
================================================
FILE: test/bash-comparison.ts
================================================
// basic test
// show that it does the same thing by default as the shell.
import { resolve } from 'path'
import t from 'tap'
import { fileURLToPath } from 'url'
import { glob } from '../dist/esm/index.js'
import { bashResults } from './bash-results.js'
const globs = Object.keys(bashResults)
// run from the root of the project
// this is usually where you're at anyway, but be sure.
const __dirname = fileURLToPath(new URL('.', import.meta.url))
const fixtures = resolve(__dirname, 'fixtures')
process.chdir(fixtures)
const alphasort = (a: string, b: string) =>
a.toLowerCase().localeCompare(b.toLowerCase(), 'en')
const cleanResults = (m: string[]) => {
// normalize discrepancies in ordering, duplication,
// and ending slashes.
return m
.map(m => m.replace(/\/$/, ''))
.sort(alphasort)
.reduce((set: string[], f) => {
if (f !== set[set.length - 1]) set.push(f)
return set
}, [])
.map(f => {
// de-windows
return process.platform !== 'win32' ?
f
: f.replace(/^[a-zA-Z]:[/\\]+/, '/').replace(/[\\/]+/g, '/')
})
.sort(alphasort)
}
globs.forEach(function (pattern) {
var expect = bashResults[pattern]
// anything regarding the symlink thing will fail on windows, so just skip it
if (
process.platform === 'win32' &&
expect?.some((m: string) => /\bsymlink\b/.test(m))
) {
return
}
t.test(pattern, async t => {
// sort and unmark, just to match the shell results
const matches = cleanResults(await glob(pattern))
t.same(matches, expect, pattern)
})
t.test(`${pattern} sync`, async t => {
const matches = cleanResults(glob.globSync(pattern))
t.same(matches, expect, 'should match shell (sync)')
})
})
================================================
FILE: test/bash-results.ts
================================================
// generated via 'npm run test-regen'
import { fileURLToPath } from 'url'
if (process.argv[1] === fileURLToPath(import.meta.url)) {
console.log('TAP version 14\n1..1\nok\n')
}
export const bashResults: { [path: string]: string[] } = {
'a/c/d/*/b': ['a/c/d/c/b'],
'a//c//d//*//b': ['a/c/d/c/b'],
'a/*/d/*/b': ['a/c/d/c/b'],
'a/*/+(c|g)/./d': ['a/b/c/d'],
'a/**/[cg]/../[cg]': [
'a/abcdef/g',
'a/abcfed/g',
'a/b/c',
'a/c',
'a/c/d/c',
'a/symlink/a/b/c',
],
'a/{b,c,d,e,f}/**/g': [],
'a/b/**': ['a/b', 'a/b/c', 'a/b/c/d'],
'./**/g': ['a/abcdef/g', 'a/abcfed/g'],
'a/abc{fed,def}/g/h': ['a/abcdef/g/h', 'a/abcfed/g/h'],
'a/abc{fed/g,def}/**/': ['a/abcdef', 'a/abcdef/g', 'a/abcfed/g'],
'a/abc{fed/g,def}/**///**/': ['a/abcdef', 'a/abcdef/g', 'a/abcfed/g'],
'**/a': ['a', 'a/symlink/a'],
'**/a/**': [
'a',
'a/abcdef',
'a/abcdef/g',
'a/abcdef/g/h',
'a/abcfed',
'a/abcfed/g',
'a/abcfed/g/h',
'a/b',
'a/b/c',
'a/b/c/d',
'a/bc',
'a/bc/e',
'a/bc/e/f',
'a/c',
'a/c/d',
'a/c/d/c',
'a/c/d/c/b',
'a/cb',
'a/cb/e',
'a/cb/e/f',
'a/symlink',
'a/symlink/a',
'a/symlink/a/b',
'a/symlink/a/b/c',
'a/x',
'a/z',
],
'./**/a': ['a', 'a/symlink/a', 'a/symlink/a/b/c/a'],
'./**/a/**/': [
'a',
'a/abcdef',
'a/abcdef/g',
'a/abcfed',
'a/abcfed/g',
'a/b',
'a/b/c',
'a/bc',
'a/bc/e',
'a/c',
'a/c/d',
'a/c/d/c',
'a/cb',
'a/cb/e',
'a/symlink',
'a/symlink/a',
'a/symlink/a/b',
'a/symlink/a/b/c',
'a/symlink/a/b/c/a',
'a/symlink/a/b/c/a/b',
'a/symlink/a/b/c/a/b/c',
'a/x',
'a/z',
],
'./**/a/**': [
'a',
'a/abcdef',
'a/abcdef/g',
'a/abcdef/g/h',
'a/abcfed',
'a/abcfed/g',
'a/abcfed/g/h',
'a/b',
'a/b/c',
'a/b/c/d',
'a/bc',
'a/bc/e',
'a/bc/e/f',
'a/c',
'a/c/d',
'a/c/d/c',
'a/c/d/c/b',
'a/cb',
'a/cb/e',
'a/cb/e/f',
'a/symlink',
'a/symlink/a',
'a/symlink/a/b',
'a/symlink/a/b/c',
'a/symlink/a/b/c/a',
'a/symlink/a/b/c/a/b',
'a/symlink/a/b/c/a/b/c',
'a/x',
'a/z',
],
'./**/a/**/a/**/': [
'a/symlink/a',
'a/symlink/a/b',
'a/symlink/a/b/c',
'a/symlink/a/b/c/a',
'a/symlink/a/b/c/a/b',
'a/symlink/a/b/c/a/b/c',
'a/symlink/a/b/c/a/b/c/a',
'a/symlink/a/b/c/a/b/c/a/b',
'a/symlink/a/b/c/a/b/c/a/b/c',
],
'+(a|b|c)/a{/,bc*}/**': [
'a/abcdef',
'a/abcdef/g',
'a/abcdef/g/h',
'a/abcfed',
'a/abcfed/g',
'a/abcfed/g/h',
],
'*/*/*/f': ['a/bc/e/f', 'a/cb/e/f'],
'./**/f': ['a/bc/e/f', 'a/cb/e/f'],
'a/symlink/a/b/c/a/b/c/a/b/c//a/b/c////a/b/c/**/b/c/**': [
'a/symlink/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c',
'a/symlink/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a',
'a/symlink/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b',
'a/symlink/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c',
],
'{./*/*,/tmp/glob-test/*}': [
'/tmp/glob-test/asdf',
'/tmp/glob-test/bar',
'/tmp/glob-test/baz',
'/tmp/glob-test/foo',
'/tmp/glob-test/quux',
'/tmp/glob-test/qwer',
'/tmp/glob-test/rewq',
'a/abcdef',
'a/abcfed',
'a/b',
'a/bc',
'a/c',
'a/cb',
'a/symlink',
'a/x',
'a/z',
],
'{/tmp/glob-test/*,*}': [
'/tmp/glob-test/asdf',
'/tmp/glob-test/bar',
'/tmp/glob-test/baz',
'/tmp/glob-test/foo',
'/tmp/glob-test/quux',
'/tmp/glob-test/qwer',
'/tmp/glob-test/rewq',
'a',
],
'a/!(symlink)/**': [
'a/abcdef',
'a/abcdef/g',
'a/abcdef/g/h',
'a/abcfed',
'a/abcfed/g',
'a/abcfed/g/h',
'a/b',
'a/b/c',
'a/b/c/d',
'a/bc',
'a/bc/e',
'a/bc/e/f',
'a/c',
'a/c/d',
'a/c/d/c',
'a/c/d/c/b',
'a/cb',
'a/cb/e',
'a/cb/e/f',
'a/x',
'a/z',
],
'a/symlink/a/**/*': [
'a/symlink/a/b',
'a/symlink/a/b/c',
'a/symlink/a/b/c/a',
],
'a/!(symlink)/**/..': [
'a',
'a/abcdef',
'a/abcfed',
'a/b',
'a/bc',
'a/c',
'a/c/d',
'a/cb',
],
'a/!(symlink)/**/../': [
'a',
'a/abcdef',
'a/abcfed',
'a/b',
'a/bc',
'a/c',
'a/c/d',
'a/cb',
],
'a/!(symlink)/**/../*': [
'a/abcdef',
'a/abcdef/g',
'a/abcfed',
'a/abcfed/g',
'a/b',
'a/b/c',
'a/bc',
'a/bc/e',
'a/c',
'a/c/d',
'a/c/d/c',
'a/cb',
'a/cb/e',
'a/symlink',
'a/x',
'a/z',
],
'a/!(symlink)/**/../*/*': [
'a/abcdef/g',
'a/abcdef/g/h',
'a/abcfed/g',
'a/abcfed/g/h',
'a/b/c',
'a/b/c/d',
'a/bc/e',
'a/bc/e/f',
'a/c/d',
'a/c/d/c',
'a/c/d/c/b',
'a/cb/e',
'a/cb/e/f',
'a/symlink/a',
],
}
================================================
FILE: test/broken-symlink.ts
================================================
import { relative } from 'path'
import t from 'tap'
import { glob } from '../dist/esm/index.js'
import type { GlobOptionsWithFileTypesUnset } from '../dist/esm/glob.js'
if (process.platform === 'win32') {
t.plan(0, 'skip on windows')
process.exit(0)
}
const dir = relative(
process.cwd(),
t.testdir({
a: {
'broken-link': {
link: t.fixture('symlink', 'this-does-not-exist'),
},
},
}),
)
const link = `${dir}/a/broken-link/link`
const patterns = [
`${dir}/a/broken-link/*`,
`${dir}/a/broken-link/**`,
`${dir}/a/broken-link/**/link`,
`${dir}/a/broken-link/**/*`,
`${dir}/a/broken-link/link`,
`${dir}/a/broken-link/{link,asdf}`,
`${dir}/a/broken-link/+(link|asdf)`,
`${dir}/a/broken-link/!(asdf)`,
]
const opts: (GlobOptionsWithFileTypesUnset | undefined)[] = [
undefined,
{ mark: true },
{ follow: true },
]
t.test('async test', t => {
t.plan(patterns.length)
for (const pattern of patterns) {
t.test(pattern, async t => {
t.plan(opts.length)
for (const opt of opts) {
const res = await glob(pattern, opt)
const msg = `${pattern} ${JSON.stringify(opt)}`
t.not(res.indexOf(link), -1, msg)
}
})
}
})
t.test('sync test', t => {
t.plan(patterns.length)
for (const pattern of patterns) {
t.test(pattern, t => {
t.plan(opts.length)
for (const opt of opts) {
const res = glob.globSync(pattern, opt)
t.not(res.indexOf(link), -1, `opt=${JSON.stringify(opt)}`)
}
})
}
})
================================================
FILE: test/custom-fs.ts
================================================
import t from 'tap'
import { globSync } from '../dist/esm/index.js'
// just a rudimentary test, since PathScurry tests it more anyway
import { readdirSync } from 'fs'
let readdirCalled = 0
const myReaddirSync = (path: string, options: { withFileTypes: true }) => {
readdirCalled++
return readdirSync(path, options)
}
const cwd = t.testdir({
a: '',
b: '',
c: {},
})
t.same(
new Set(['a', 'b', 'c', '.']),
new Set(
globSync('**', {
fs: {
readdirSync: myReaddirSync,
},
cwd,
}),
),
)
t.equal(readdirCalled, 2)
================================================
FILE: test/custom-ignore.ts
================================================
import { basename } from 'path'
import type { Path } from 'path-scurry'
import t from 'tap'
import { fileURLToPath } from 'url'
import type { IgnoreLike } from '../dist/esm/index.js'
import { glob, globSync } from '../dist/esm/index.js'
const cwd = fileURLToPath(new URL('./fixtures', import.meta.url))
const j = (a: string[]) =>
a
.map(s => s.replace(/\\/g, '/'))
.sort((a, b) => a.localeCompare(b, 'en'))
t.test('ignore files with long names', async t => {
const ignore: IgnoreLike = {
ignored: (p: Path) => p.name.length > 1,
}
const syncRes = globSync('**', { cwd, ignore })
const asyncRes = await glob('**', { cwd, ignore })
const expect = j(
globSync('**', { cwd }).filter(p => {
return basename(p).length === 1 && basename(p) !== '.'
}),
)
t.same(j(syncRes), expect)
t.same(j(asyncRes), expect)
for (const r of syncRes) {
if (basename(r).length > 1) t.fail(r)
}
})
t.test('ignore symlink and abcdef directories', async t => {
const ignore: IgnoreLike = {
childrenIgnored: (p: Path) => {
return p.isNamed('symlink') || p.isNamed('abcdef')
},
}
const syncRes = globSync('**', { cwd, ignore, nodir: true })
const asyncRes = await glob('**', { cwd, ignore, nodir: true })
const expect = j(
globSync('**', { nodir: true, cwd }).filter(p => {
return !/\bsymlink\b|\babcdef\b/.test(p)
}),
)
t.same(j(syncRes), expect)
t.same(j(asyncRes), expect)
for (const r of syncRes) {
if (r === 'symlink' || r === 'basename') t.fail(r)
}
})
================================================
FILE: test/cwd-noent.ts
================================================
import t from 'tap'
import { fileURLToPath } from 'url'
import { Glob } from '../dist/esm/index.js'
const cwd = fileURLToPath(
new URL('./fixtures/does-not-exist', import.meta.url),
)
t.test('walk', async t => {
const g = new Glob('**', { cwd })
t.same(await g.walk(), [])
})
t.test('walkSync', t => {
const g = new Glob('**', { cwd })
t.same(g.walkSync(), [])
t.end()
})
t.test('stream', async t => {
const g = new Glob('**', { cwd })
const s = g.stream()
s.on('data', () => t.fail('should not get entries'))
t.same(await s.collect(), [])
})
t.test('streamSync', t => {
const g = new Glob('**', { cwd })
const s = g.streamSync()
const c: string[] = []
s.on('data', p => {
t.fail('should not get entries')
c.push(p)
})
s.on('end', () => {
t.same(c, [])
t.end()
})
})
t.test('iterate', async t => {
const g = new Glob('**', { cwd })
const s = g.iterate()
const c: string[] = []
for await (const p of s) {
c.push(p)
t.fail('should not get entries')
}
t.same(c, [])
})
t.test('iterateSync', async t => {
const g = new Glob('**', { cwd })
const s = g.iterateSync()
const c: string[] = []
for (const p of s) {
c.push(p)
t.fail('should not get entries')
}
t.same(c, [])
t.end()
})
t.test('for await', async t => {
const g = new Glob('**', { cwd })
const c: string[] = []
for await (const p of g) {
c.push(p)
t.fail('should not get entries')
}
t.same(c, [])
})
t.test('iterateSync', async t => {
const g = new Glob('**', { cwd })
const c: string[] = []
for (const p of g) {
c.push(p)
t.fail('should not get entries')
}
t.same(c, [])
t.end()
})
================================================
FILE: test/cwd-test.ts
================================================
import { resolve, sep } from 'path'
import t from 'tap'
import { fileURLToPath } from 'url'
import { glob } from '../dist/esm/index.js'
const j = (a: string[]) => a.map(s => s.split('/').join(sep))
const origCwd = process.cwd()
process.chdir(fileURLToPath(new URL('./fixtures', import.meta.url)))
t.teardown(() => process.chdir(origCwd))
t.test('changing cwd and searching for **/d', t => {
const expect = Object.entries({
a: new Set(j(['c/d', 'b/c/d'])),
'a/b': new Set(j(['c/d'])),
'': new Set(j(['a/b/c/d', 'a/c/d'])),
})
t.plan(expect.length)
for (const [cwd, matches] of expect) {
t.test(cwd || '(empty string)', async t => {
t.same(new Set(await glob('**/d', { cwd })), matches)
if (cwd) {
t.same(new Set(await glob('**/d', { cwd: `${cwd}/` })), matches)
t.same(new Set(await glob('**/d', { cwd: `${cwd}/.` })), matches)
t.same(new Set(await glob('**/d', { cwd: `${cwd}/./` })), matches)
} else {
t.same(new Set(await glob('**/d', { cwd: '.' })), matches)
t.same(new Set(await glob('**/d', { cwd: './' })), matches)
}
t.same(new Set(await glob('**/d', { cwd: resolve(cwd) })), matches)
t.same(
new Set(await glob('**/d', { cwd: `${resolve(cwd)}/` })),
matches,
)
t.same(
new Set(await glob('**/d', { cwd: `${resolve(cwd)}/.` })),
matches,
)
t.same(
new Set(await glob('**/d', { cwd: `${resolve(cwd)}/./` })),
matches,
)
})
}
})
================================================
FILE: test/dot-relative.ts
================================================
import { resolve, sep } from 'path'
import t from 'tap'
import { fileURLToPath } from 'url'
import { Glob } from '../dist/esm/index.js'
import { bashResults } from './bash-results.js'
const __dirname = fileURLToPath(new URL('.', import.meta.url))
const pattern = 'a/b/**'
process.chdir(fileURLToPath(new URL('./fixtures', import.meta.url)))
const marks = [true, false]
for (const mark of marks) {
t.test(`'mark=${mark}`, t => {
t.plan(3)
t.test('Emits relative matches prefixed with ./', async t => {
const g = new Glob(pattern, { dotRelative: true })
const results = await g.walk()
t.equal(
results.length,
bashResults[pattern]?.length,
'must match all files',
)
for (const m of results) {
t.ok(m.startsWith(`.${sep}`))
}
})
t.test('returns ./ prefixed matches synchronously', async t => {
const g = new Glob(pattern, { dotRelative: true })
const results = g.walkSync()
t.equal(
results.length,
bashResults[pattern]?.length,
'must match all files',
)
for (const m of results) {
t.ok(m.startsWith(`.${sep}`))
}
})
t.test(
'does not prefix with ./ unless dotRelative is true',
async t => {
const g = new Glob(pattern, {})
const results = await g.walk()
t.equal(
results.length,
bashResults[pattern]?.length,
'must match all files',
)
for (const m of results) {
t.ok((mark && m === `.${sep}`) || !m.startsWith(`.${sep}`))
}
},
)
})
}
t.test('does not add ./ for patterns starting in ../', async t => {
t.plan(2)
const pattern = '../a/b/**'
const cwd = resolve(__dirname, 'fixtures/a')
t.test('async', async t => {
const g = new Glob(pattern, { dotRelative: true, cwd })
for await (const m of g) {
t.ok(!m.startsWith(`.${sep}..${sep}`))
}
})
t.test('sync', async t => {
const g = new Glob(pattern, { dotRelative: true, cwd })
for (const m of g) {
t.ok(!m.startsWith(`.${sep}..${sep}`))
}
})
})
================================================
FILE: test/empty-set.ts
================================================
import t from 'tap'
import { glob } from '../dist/esm/index.js'
// Patterns that cannot match anything
const patterns = [
'# comment',
' ',
'\n',
'just doesnt happen to match anything so this is a control',
]
t.plan(patterns.length)
for (const p of patterns) {
t.test(JSON.stringify(p), async t => {
const f = await glob(p)
t.same(f, [], 'no returned values')
})
}
================================================
FILE: test/escape.ts
================================================
import t from 'tap'
import { unescape, escape, hasMagic } from '../dist/esm/index.js'
import { bashResults } from './bash-results.js'
for (const pattern of Object.keys(bashResults)) {
t.notOk(hasMagic(escape(pattern)), `escape(${pattern})`)
const pp = escape(pattern)
const pw = escape(pattern, {
windowsPathsNoEscape: true,
})
t.notOk(
hasMagic(pp, { platform: 'linux' }),
'no magic after posix escape',
)
t.notOk(
hasMagic(pw, { platform: 'win32', windowsPathsNoEscape: true }),
'no magic after windows escape',
)
const up = unescape(pp)
const uw = unescape(pw, { windowsPathsNoEscape: true })
t.equal(up, pattern, 'unescaped posix pattern returned')
t.equal(uw, pattern, 'unescaped windows pattern returned')
}
================================================
FILE: test/follow.ts
================================================
import t from 'tap'
import { fileURLToPath } from 'url'
import { glob } from '../dist/esm/index.js'
if (process.platform === 'win32') {
t.plan(0, 'skip on windows')
process.exit(0)
}
process.chdir(fileURLToPath(new URL('./fixtures', import.meta.url)))
t.test('follow symlinks', async t => {
const pattern = 'a/symlink/**'
const syncNoFollow = glob.globSync(pattern)
const syncFollow = glob.globSync(pattern, { follow: true })
const [noFollow, follow] = await Promise.all([
glob(pattern),
glob(pattern, { follow: true }),
])
t.same(
new Set(follow),
new Set(syncFollow),
'sync and async follow should match',
)
t.same(
new Set(noFollow),
new Set(syncNoFollow),
'sync and async noFollow should match',
)
var long = 'a/symlink/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c/a/b/c'
t.ok(follow.includes(long), 'follow should have long entry')
t.ok(syncFollow.includes(long), 'syncFollow should have long entry')
t.end()
})
t.test('follow + nodir means no symlinks to dirs in results', async t => {
const pattern = 'dir_baz/**'
const cwd = t.testdir({
dir_baz: {
bar: t.fixture('symlink', '../dir_bar'),
},
dir_bar: {
foo: t.fixture('symlink', '../dir_foo'),
},
dir_foo: {
'foo.txt': 'hello',
},
})
const follow = true
const nodir = true
const posix = true
const syncResult = glob
.globSync(pattern, { follow, nodir, cwd, posix })
.sort((a, b) => a.localeCompare(b))
const asyncResult = (
await glob(pattern, { follow, nodir, cwd, posix })
).sort((a, b) => a.localeCompare(b))
t.strictSame(syncResult, asyncResult)
t.strictSame(syncResult, ['dir_baz/bar/foo/foo.txt'])
})
================================================
FILE: test/has-magic.ts
================================================
import t from 'tap'
import { fileURLToPath } from 'url'
import { glob } from '../dist/esm/index.js'
process.chdir(fileURLToPath(new URL('.', import.meta.url)))
t.test('non-string pattern is evil magic', async t => {
const patterns = [0, null, 12, { x: 1 }, undefined, /x/, NaN]
patterns.forEach(function (p) {
t.throws(function () {
// @ts-expect-error
glob.hasMagic(p)
})
})
})
t.test('detect magic in glob patterns', async t => {
t.notOk(glob.hasMagic(['']), "no magic in ''")
t.notOk(glob.hasMagic('a/b/c/'), 'no magic a/b/c/')
t.ok(glob.hasMagic('a/b/**/'), 'magic in a/b/**/')
t.ok(glob.hasMagic('a/b/?/'), 'magic in a/b/?/')
t.ok(glob.hasMagic('a/b/+(x|y)'), 'magic in a/b/+(x|y)')
t.notOk(
glob.hasMagic('a/b/+(x|y)', { noext: true }),
'no magic in a/b/+(x|y) noext',
)
t.notOk(glob.hasMagic('{a,b}'), 'no magic in {a,b}')
t.ok(
glob.hasMagic('{a,b}', { magicalBraces: true }),
'magical braces are magic in {a,b}',
)
t.notOk(
glob.hasMagic('{a,b}', { nobrace: true }),
'no magic in {a,b} nobrace:true',
)
t.notOk(
glob.hasMagic('{a,b}', { nobrace: true, magicalBraces: true }),
'magical braces not magic in {a,b} nobrace:true',
)
})
================================================
FILE: test/ignore.ts
================================================
// Ignore option test
// Show that glob ignores results matching pattern on ignore option
import { sep } from 'path'
import t from 'tap'
import { fileURLToPath } from 'url'
import type { GlobOptions } from '../dist/esm/index.js'
import { glob } from '../dist/esm/index.js'
const __dirname = fileURLToPath(new URL('.', import.meta.url))
const alphasort = (a: string, b: string) => a.localeCompare(b, 'en')
const j = (a: string[]) =>
a.map(s => s.split('/').join(sep)).sort(alphasort)
process.chdir(fileURLToPath(new URL('./fixtures', import.meta.url)))
// [pattern, ignore, expect, opt (object) or cwd (string)]
type Case = [
pattern: string,
ignore: null | string | string[],
expect: string[],
optOrCwd?: GlobOptions | string | undefined,
]
const cases: Case[] = [
[
'*',
null,
j(['abcdef', 'abcfed', 'b', 'bc', 'c', 'cb', 'symlink', 'x', 'z']),
'a',
],
[
'*',
['b'],
j(['abcdef', 'abcfed', 'bc', 'c', 'cb', 'symlink', 'x', 'z']),
'a',
],
[
'*',
'b*',
j(['abcdef', 'abcfed', 'c', 'cb', 'symlink', 'x', 'z']),
'a',
],
['b/**', 'b/c/d', j(['b', 'b/c']), 'a'],
['b/**', 'd', j(['b', 'b/c', 'b/c/d']), 'a'],
['b/**', 'b/c/**', ['b'], 'a'],
['b/**', `${process.cwd()}/a/b/c/**`.split(sep).join('/'), ['b'], 'a'],
['**/d', 'b/c/d', j(['c/d']), 'a'],
[
'a/**/[gh]',
['a/abcfed/g/h'],
j(['a/abcdef/g', 'a/abcdef/g/h', 'a/abcfed/g']),
],
[
'*',
['c', 'bc', 'symlink', 'abcdef'],
['abcfed', 'b', 'cb', 'x', 'z'],
'a',
],
[
'**',
['c/**', 'bc/**', 'symlink/**', 'abcdef/**'],
j([
'.',
'abcfed',
'abcfed/g',
'abcfed/g/h',
'b',
'b/c',
'b/c/d',
'cb',
'cb/e',
'cb/e/f',
'x',
'z',
]),
'a',
],
['a/**', ['a/**'], []],
['a/**', ['a/**/**'], []],
['a/b/**', ['a/b'], j(['a/b/c', 'a/b/c/d'])],
[
'**',
['b'],
j([
'.',
'abcdef',
'abcdef/g',
'abcdef/g/h',
'abcfed',
'abcfed/g',
'abcfed/g/h',
'b/c',
'b/c/d',
'bc',
'bc/e',
'bc/e/f',
'c',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
[
'**',
['b', 'c'],
j([
'.',
'abcdef',
'abcdef/g',
'abcdef/g/h',
'abcfed',
'abcfed/g',
'abcfed/g/h',
'b/c',
'b/c/d',
'bc',
'bc/e',
'bc/e/f',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
[
'**',
['b**'],
j([
'.',
'abcdef',
'abcdef/g',
'abcdef/g/h',
'abcfed',
'abcfed/g',
'abcfed/g/h',
'b/c',
'b/c/d',
'bc/e',
'bc/e/f',
'c',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
[
'**',
['b/**'],
j([
'.',
'abcdef',
'abcdef/g',
'abcdef/g/h',
'abcfed',
'abcfed/g',
'abcfed/g/h',
'bc',
'bc/e',
'bc/e/f',
'c',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
[
'**',
['b**/**'],
j([
'.',
'abcdef',
'abcdef/g',
'abcdef/g/h',
'abcfed',
'abcfed/g',
'abcfed/g/h',
'c',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
[
'**',
['ab**ef/**'],
j([
'.',
'abcfed',
'abcfed/g',
'abcfed/g/h',
'b',
'b/c',
'b/c/d',
'bc',
'bc/e',
'bc/e/f',
'c',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
[
'**',
['abc{def,fed}/**'],
j([
'.',
'b',
'b/c',
'b/c/d',
'bc',
'bc/e',
'bc/e/f',
'c',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
[
'**',
['abc{def,fed}/*'],
j([
'.',
'abcdef',
'abcdef/g/h',
'abcfed',
'abcfed/g/h',
'b',
'b/c',
'b/c/d',
'bc',
'bc/e',
'bc/e/f',
'c',
'c/d',
'c/d/c',
'c/d/c/b',
'cb',
'cb/e',
'cb/e/f',
'symlink',
'symlink/a',
'symlink/a/b',
'symlink/a/b/c',
'x',
'z',
]),
'a',
],
['c/**', ['c/*'], j(['c', 'c/d/c', 'c/d/c/b']), 'a'],
['a/c/**', ['a/c/*'], j(['a/c', 'a/c/d/c', 'a/c/d/c/b'])],
['a/c/**', ['a/c/**', 'a/c/*', 'a/c/*/c'], []],
['a/**/.y', ['a/x/**'], j(['a/z/.y'])],
['a/**/.y', ['a/x/**'], j(['a/z/.y']), { dot: true }],
['a/**/b', ['a/x/**'], j(['a/b', 'a/c/d/c/b', 'a/symlink/a/b'])],
[
'a/**/b',
['a/x/**'],
j(['a/b', 'a/c/d/c/b', 'a/symlink/a/b', 'a/z/.y/b']),
{ dot: true },
],
['*/.abcdef', 'a/**', []],
['a/*/.y/b', 'a/x/**', j(['a/z/.y/b'])],
[
'a/*/.y/b',
`${process.cwd()}/a/x/**`.split(sep).join('/'),
j(['a/z/.y/b']),
],
[
'./*',
'{./,c}b',
j(['abcdef', 'abcfed', 'bc', 'c', 'symlink', 'x', 'z']),
'a',
],
[
'./*',
'./c/../b',
j(['abcdef', 'abcfed', 'bc', 'c', 'cb', 'symlink', 'x', 'z']),
'a',
],
]
for (const c of cases) {
const [pattern, ignore, ex, optCwd] = c
const expect = (
process.platform === 'win32' ?
ex.filter(e => !/\bsymlink\b/.test(e))
: ex).sort()
expect.sort()
const opt: GlobOptions =
(typeof optCwd === 'string' ? { cwd: optCwd } : optCwd) || {}
const name = `p=${pattern} i=${JSON.stringify(ignore)} ${JSON.stringify(
opt,
)}`
if (ignore) {
opt.ignore = ignore
}
t.test(name, async t => {
const res = await glob(pattern, opt)
t.same(res.sort(), expect, 'async')
const resSync = glob.globSync(pattern, opt)
t.same(resSync.sort(), expect, 'sync')
})
}
t.test('race condition', async t => {
process.chdir(__dirname)
var pattern = 'fixtures/*'
t.jobs = 64
for (const dot of [true, false]) {
for (const ignore of ['fixtures/**', undefined]) {
for (const cwd of [undefined, process.cwd(), '.']) {
const opt: GlobOptions = {
dot,
ignore,
}
if (cwd) opt.cwd = cwd
const expect = ignore ? [] : j(['fixtures/a'])
t.test(JSON.stringify(opt), async t => {
t.plan(2)
t.same(glob.globSync(pattern, opt).sort(), expect)
t.same((await glob(pattern, opt)).sort(), expect)
})
}
}
}
})
================================================
FILE: test/include-child-matches.ts
================================================
import t from 'tap'
import type { GlobOptionsWithFileTypesUnset } from '../src/index.js'
import { glob, globSync } from '../src/index.js'
t.test('no include child matches', async t => {
const cwd = t.testdir({ a: { b: { c: { d: { e: { f: '' } } } } } })
const pattern = 'a/**/[cde]/**'
const o: GlobOptionsWithFileTypesUnset = {
cwd,
posix: true,
includeChildMatches: false,
}
const a = await glob(pattern, o)
const s = globSync(pattern, o)
t.strictSame(a, ['a/b/c'])
t.strictSame(s, ['a/b/c'])
})
t.test('test the caveat', async t => {
const cwd = t.testdir({ a: { b: { c: { d: { e: { f: '' } } } } } })
const pattern = ['a/b/c/d/e/f', 'a/[bdf]/?/[a-z]/*']
const o: GlobOptionsWithFileTypesUnset = {
cwd,
posix: true,
includeChildMatches: false,
}
const a = await glob(pattern, o)
const s = globSync(pattern, o)
t.strictSame(a, ['a/b/c/d/e/f', 'a/b/c/d/e'])
t.strictSame(s, ['a/b/c/d/e/f', 'a/b/c/d/e'])
})
t.test('ignore impl must have an add() method', t => {
t.throws(() =>
globSync('', {
ignore: {
ignored: () => true,
childrenIgnored: () => true,
},
includeChildMatches: false,
}),
)
t.end()
})
================================================
FILE: test/mark.ts
================================================
import { sep } from 'path'
import t from 'tap'
import { fileURLToPath } from 'url'
import { glob } from '../dist/esm/index.js'
process.chdir(fileURLToPath(new URL('./fixtures', import.meta.url)))
const alphasort = (a: string, b: string) => a.localeCompare(b, 'en')
const j = (a: string[]) =>
a.map(s => s.split('/').join(sep)).sort(alphasort)
t.test('mark with cwd', async t => {
const pattern = '*/*'
const opt = { mark: true, cwd: 'a' }
const expect = [
'abcdef/g/',
'abcfed/g/',
'b/c/',
'bc/e/',
'c/d/',
'cb/e/',
]
const res = await glob(pattern, opt)
if (process.platform !== 'win32') {
expect.push('symlink/a/')
}
t.same(res.sort(alphasort), j(expect))
t.same(glob.globSync(pattern, opt).sort(alphasort), j(expect))
})
t.test('mark, with **', async t => {
const pattern = 'a/*b*/**'
const opt = { mark: true }
const expect = [
'a/abcdef/',
'a/abcdef/g/',
'a/abcdef/g/h',
'a/abcfed/',
'a/abcfed/g/',
'a/abcfed/g/h',
'a/b/',
'a/b/c/',
'a/b/c/d',
'a/bc/',
'a/bc/e/',
'a/bc/e/f',
'a/cb/',
'a/cb/e/',
'a/cb/e/f',
].sort(alphasort)
t.same((await glob(pattern, opt)).sort(alphasort), j(expect), 'async')
t.same(glob.globSync(pattern, opt).sort(alphasort), j(expect), 'sync')
})
t.test('mark, no / on pattern', async t => {
const pattern = 'a/*'
const opt = { mark: true }
const expect = [
'a/abcdef/',
'a/abcfed/',
'a/b/',
'a/bc/',
'a/c/',
'a/cb/',
'a/x/',
'a/z/',
]
if (process.platform !== 'win32') {
expect.push('a/symlink/')
}
const results = (await glob(pattern, opt)).sort(alphasort)
t.same(results, j(expect))
t.same(glob.globSync(pattern, opt).sort(alphasort), j(expect))
})
t.test('mark=false, no / on pattern', async t => {
const pattern = 'a/*'
const expect = [
'a/abcdef',
'a/abcfed',
'a/b',
'a/bc',
'a/c',
'a/cb',
'a/x',
'a/z',
]
if (process.platform !== 'win32') {
expect.push('a/symlink')
}
const results = (await glob(pattern)).sort(alphasort)
t.same(results, j(expect))
t.same(glob.globSync(pattern).sort(alphasort), j(expect))
})
t.test('mark=true, / on pattern', async t => {
const pattern = 'a/*/'
const opt = { mark: true }
const expect = [
'a/abcdef/',
'a/abcfed/',
'a/b/',
'a/bc/',
'a/c/',
'a/cb/',
'a/x/',
'a/z/',
]
if (process.platform !== 'win32') {
expect.push('a/symlink/')
}
const results = (await glob(pattern, opt)).sort(alphasort)
t.same(results, j(expect))
t.same(glob.globSync(pattern, opt).sort(alphasort), j(expect))
})
t.test('mark=false, / on pattern', async t => {
const pattern = 'a/*/'
const expect = [
'a/abcdef',
'a/abcfed',
'a/b',
'a/bc',
'a/c',
'a/cb',
'a/x',
'a/z',
]
if (process.platform !== 'win32') {
expect.push('a/symlink')
}
const results = (await glob(pattern)).sort(alphasort)
t.same(results, j(expect))
t.same(glob.globSync(pattern).sort(alphasort), j(expect))
})
const cwd = process
.cwd()
.replace(/[/\\]+$/, '')
.replace(/\\/g, '/')
for (const mark of [true, false]) {
for (const slash of [true, false]) {
t.test(`cwd mark:${mark} slash:${slash}`, async t => {
const pattern = cwd + (slash ? '/' : '')
const results = await glob(pattern, { mark })
t.equal(results.length, 1)
const res = results[0]?.replace(/\\/g, '/')
const syncResults = glob.globSync(pattern, { mark: mark })
const syncRes = syncResults[0]?.replace(/\\/g, '/')
if (mark) {
t.equal(res, `${cwd}/`)
} else {
t.equal(res?.indexOf(cwd), 0)
}
t.equal(syncRes, res, 'sync should match async')
})
}
}
for (const mark of [true, false]) {
for (const slash of [true, false]) {
t.test(`. mark:${mark} slash:${slash}`, async t => {
const pattern = `.${slash ? '/' : ''}`
const results = await glob(pattern, { mark })
t.equal(results.length, 1)
const res = results[0]?.replace(/\\/g, '/')
const syncResults = glob.globSync(pattern, { mark: mark })
const syncRes = syncResults[0]?.replace(/\\/g, '/')
if (mark) {
t.equal(res, './')
} else {
t.equal(res, '.')
}
t.equal(syncRes, res, 'sync should match async')
})
}
}
================================================
FILE: test/match-base.ts
================================================
import t from 'tap'
import { glob } from '../dist/esm/index.js'
import { sep } from 'path'
import { fileURLToPath } from 'url'
const alphasort = (a: string, b: string) => a.localeCompare(b, 'en')
const j = (a: string[]) =>
a.map(s => s.split('/').join(sep)).sort(alphasort)
const fixtureDir = fileURLToPath(new URL('./fixtu
gitextract_aolffhr8/ ├── .github/ │ └── workflows/ │ ├── ci.yml │ └── typedoc.yml ├── .gitignore ├── .oxlint.json ├── .prettierignore ├── .prettierrc.json ├── .taprc ├── .tshy/ │ ├── build.json │ ├── commonjs.json │ └── esm.json ├── CONTRIBUTING.md ├── LICENSE.md ├── README.md ├── benchclean.cjs ├── benchmark.sh ├── changelog.md ├── examples/ │ ├── g.js │ └── usr-local.js ├── make-benchmark-fixture.sh ├── package.json ├── patterns.sh ├── prof.sh ├── scripts/ │ ├── build.sh │ └── make-big-tree.js ├── src/ │ ├── glob.ts │ ├── has-magic.ts │ ├── ignore.ts │ ├── index.ts │ ├── pattern.ts │ ├── processor.ts │ └── walker.ts ├── tap-snapshots/ │ └── test/ │ ├── bin.ts.test.cjs │ ├── pattern.ts.test.cjs │ └── root.ts.test.cjs ├── test/ │ ├── 00-setup.ts │ ├── absolute-must-be-strings.ts │ ├── absolute.ts │ ├── bash-comparison.ts │ ├── bash-results.ts │ ├── broken-symlink.ts │ ├── custom-fs.ts │ ├── custom-ignore.ts │ ├── cwd-noent.ts │ ├── cwd-test.ts │ ├── dot-relative.ts │ ├── empty-set.ts │ ├── escape.ts │ ├── follow.ts │ ├── has-magic.ts │ ├── ignore.ts │ ├── include-child-matches.ts │ ├── mark.ts │ ├── match-base.ts │ ├── match-parent.ts │ ├── match-root.ts │ ├── max-depth.ts │ ├── memfs.ts │ ├── nocase-magic-only.ts │ ├── nodir.ts │ ├── oom.ts │ ├── pattern.ts │ ├── platform.ts │ ├── progra-tilde.ts │ ├── readme-issue.ts │ ├── realpath.ts │ ├── root.ts │ ├── signal.ts │ ├── slash-cwd.ts │ ├── stat.ts │ ├── stream.ts │ ├── url-cwd.ts │ ├── windows-paths-fs.ts │ └── windows-paths-no-escape.ts ├── tsconfig.json └── typedoc.json
SYMBOL INDEX (113 symbols across 9 files)
FILE: src/glob.ts
type MatchSet (line 16) | type MatchSet = Minimatch['set']
type GlobParts (line 17) | type GlobParts = Exclude<Minimatch['globParts'], undefined>
type GlobOptions (line 43) | interface GlobOptions {
type GlobOptionsWithFileTypesTrue (line 353) | type GlobOptionsWithFileTypesTrue = GlobOptions & {
type GlobOptionsWithFileTypesFalse (line 361) | type GlobOptionsWithFileTypesFalse = GlobOptions & {
type GlobOptionsWithFileTypesUnset (line 365) | type GlobOptionsWithFileTypesUnset = GlobOptions & {
type Result (line 369) | type Result<Opts> =
type Results (line 374) | type Results<Opts> = Result<Opts>[]
type FileTypes (line 376) | type FileTypes<Opts> =
class Glob (line 385) | class Glob<Opts extends GlobOptions> implements GlobOptions {
method constructor (line 434) | constructor(pattern: string | string[], opts: Opts) {
method walk (line 560) | async walk(): Promise<(string | Path)[]> {
method walkSync (line 583) | walkSync(): (string | Path)[] {
method stream (line 602) | stream(): Minipass<string | Path, string | Path> {
method streamSync (line 619) | streamSync(): Minipass<string | Path, string | Path> {
method iterateSync (line 636) | iterateSync(): Generator<Result<Opts>, void, void> {
method iterate (line 647) | iterate(): AsyncGenerator<Result<Opts>, void, void> {
method [Symbol.iterator] (line 639) | [Symbol.iterator]() {
method [Symbol.asyncIterator] (line 650) | [Symbol.asyncIterator]() {
FILE: src/ignore.ts
type IgnoreLike (line 12) | interface IgnoreLike {
class Ignore (line 30) | class Ignore implements IgnoreLike {
method constructor (line 38) | constructor(
method add (line 67) | add(ign: string) {
method ignored (line 108) | ignored(p: Path): boolean {
method childrenIgnored (line 122) | childrenIgnored(p: Path): boolean {
FILE: src/index.ts
function globStreamSync (line 54) | function globStreamSync(
function globStream (line 81) | function globStream(
function globSync (line 107) | function globSync(
function glob_ (line 136) | async function glob_(
function globIterateSync (line 162) | function globIterateSync(
function globIterate (line 188) | function globIterate(
FILE: src/pattern.ts
type MMPattern (line 4) | type MMPattern = string | RegExp | typeof GLOBSTAR
type PatternList (line 7) | type PatternList = [p: MMPattern, ...rest: MMPattern[]]
type UNCPatternList (line 8) | type UNCPatternList = [
type DrivePatternList (line 15) | type DrivePatternList = [p0: string, ...rest: MMPattern[]]
type AbsolutePatternList (line 16) | type AbsolutePatternList = [p0: '', ...rest: MMPattern[]]
type GlobList (line 17) | type GlobList = [p: string, ...rest: string[]]
class Pattern (line 29) | class Pattern {
method constructor (line 42) | constructor(
method [customInspect] (line 107) | [customInspect]() {
method pattern (line 114) | pattern(): MMPattern {
method isString (line 121) | isString(): boolean {
method isGlobstar (line 127) | isGlobstar(): boolean {
method isRegExp (line 133) | isRegExp(): boolean {
method globString (line 140) | globString(): string {
method hasMore (line 153) | hasMore(): boolean {
method rest (line 160) | rest(): Pattern | null {
method isUNC (line 178) | isUNC(): boolean {
method isDrive (line 201) | isDrive(): boolean {
method isAbsolute (line 219) | isAbsolute(): boolean {
method root (line 232) | root(): string {
method checkFollowGlobstar (line 245) | checkFollowGlobstar(): boolean {
method markFollowGlobstar (line 256) | markFollowGlobstar(): boolean {
FILE: src/processor.ts
class HasWalkedCache (line 12) | class HasWalkedCache {
method constructor (line 14) | constructor(store: Map<string, Set<string>> = new Map()) {
method copy (line 17) | copy() {
method hasWalked (line 20) | hasWalked(target: Path, pattern: Pattern) {
method storeWalked (line 23) | storeWalked(target: Path, pattern: Pattern) {
class MatchRecord (line 36) | class MatchRecord {
method add (line 38) | add(target: Path, absolute: boolean, ifDir: boolean) {
method entries (line 44) | entries(): [Path, boolean, boolean][] {
class SubWalks (line 57) | class SubWalks {
method add (line 59) | add(target: Path, pattern: Pattern) {
method get (line 70) | get(target: Path): Pattern[] {
method entries (line 79) | entries(): [Path, Pattern[]][] {
method keys (line 82) | keys(): Path[] {
class Processor (line 93) | class Processor {
method constructor (line 102) | constructor(opts: GlobWalkerOpts, hasWalkedCache?: HasWalkedCache) {
method processPatterns (line 110) | processPatterns(target: Path, patterns: Pattern[]) {
method subwalkTargets (line 209) | subwalkTargets(): Path[] {
method child (line 213) | child() {
method filterEntries (line 221) | filterEntries(parent: Path, entries: Path[]): Processor {
method testGlobstar (line 242) | testGlobstar(
method testRegExp (line 292) | testRegExp(
method testString (line 306) | testString(e: Path, p: string, rest: Pattern | null, absolute: boolean) {
FILE: src/walker.ts
type GlobWalkerOpts (line 20) | interface GlobWalkerOpts {
type GWOFileTypesTrue (line 49) | type GWOFileTypesTrue = GlobWalkerOpts & {
type GWOFileTypesFalse (line 52) | type GWOFileTypesFalse = GlobWalkerOpts & {
type GWOFileTypesUnset (line 55) | type GWOFileTypesUnset = GlobWalkerOpts & {
type Result (line 59) | type Result<O extends GlobWalkerOpts> =
type Matches (line 65) | type Matches<O extends GlobWalkerOpts> =
type MatchStream (line 71) | type MatchStream<O extends GlobWalkerOpts> = Minipass<
method constructor (line 102) | constructor(patterns: Pattern[], path: Path, opts: O) {
method #ignored (line 131) | #ignored(path: Path): boolean {
method #childrenIgnored (line 134) | #childrenIgnored(path: Path): boolean {
method pause (line 139) | pause() {
method resume (line 142) | resume() {
method onResume (line 152) | onResume(fn: () => unknown) {
method matchCheck (line 165) | async matchCheck(
method matchCheckTest (line 192) | matchCheckTest(e: Path | undefined, ifDir: boolean): Path | undefined {
method matchCheckSync (line 208) | matchCheckSync(inPath: Path, ifDir: boolean): Path | undefined {
method matchFinish (line 233) | matchFinish(e: Path, absolute: boolean) {
method match (line 260) | async match(e: Path, absolute: boolean, ifDir: boolean): Promise<void> {
method matchSync (line 265) | matchSync(e: Path, absolute: boolean, ifDir: boolean): void {
method walkCB (line 270) | walkCB(target: Path, patterns: Pattern[], cb: () => unknown) {
method walkCB2 (line 277) | walkCB2(
method walkCB3 (line 324) | walkCB3(
method walkCBSync (line 350) | walkCBSync(target: Path, patterns: Pattern[], cb: () => unknown) {
method walkCB2Sync (line 357) | walkCB2Sync(
method walkCB3Sync (line 398) | walkCB3Sync(
class GlobWalker (line 424) | class GlobWalker<
method constructor (line 429) | constructor(patterns: Pattern[], path: Path, opts: O) {
method matchEmit (line 433) | matchEmit(e: Result<O>): void {
method walk (line 437) | async walk(): Promise<Set<Result<O>>> {
method walkSync (line 454) | walkSync(): Set<Result<O>> {
class GlobStream (line 467) | class GlobStream<
method constructor (line 472) | constructor(patterns: Pattern[], path: Path, opts: O) {
method matchEmit (line 482) | matchEmit(e: Result<O>): void {
method stream (line 487) | stream(): MatchStream<O> {
method streamSync (line 499) | streamSync(): MatchStream<O> {
FILE: test/00-setup.ts
function cleanResults (line 167) | function cleanResults(m: string[]) {
FILE: test/ignore.ts
type Case (line 18) | type Case = [
FILE: test/realpath.ts
type Case (line 24) | type Case = [
Condensed preview — 75 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (238K chars).
[
{
"path": ".github/workflows/ci.yml",
"chars": 1357,
"preview": "name: CI\n\non:\n push:\n branches: [\"main\"]\n pull_request_target:\n paths:\n - 'src/**'\n - 'test/**'\n "
},
{
"path": ".github/workflows/typedoc.yml",
"chars": 934,
"preview": "name: typedoc\n\non:\n push:\n branches: [\"main\"]\n workflow_dispatch:\n\npermissions:\n contents: read\n pages: write\n i"
},
{
"path": ".gitignore",
"chars": 156,
"preview": ".*.swp\n/deleteme\n/old\n/*.tap\n/dist\n/node_modules\n/v8.log\n/profile.txt\n/nyc_output\n/.nyc_output\n/coverage\n/test/fixtures\n"
},
{
"path": ".oxlint.json",
"chars": 5408,
"preview": "{\n \"$schema\": \"./node_modules/oxlint/configuration_schema.json\",\n \"categories\": {},\n \"options\": {\n \"typeAware\": tr"
},
{
"path": ".prettierignore",
"chars": 201,
"preview": "/node_modules\n/tsconfig.json\n/package-lock.json\n/package.json\n/LICENSE.md\n/example\n/.github\n/dist\n/.env\n/tap-snapshots\n/"
},
{
"path": ".prettierrc.json",
"chars": 234,
"preview": "{\n \"experimentalTernaries\": true,\n \"semi\": false,\n \"printWidth\": 75,\n \"tabWidth\": 2,\n \"useTabs\": false,\n \"singleQu"
},
{
"path": ".taprc",
"chars": 27,
"preview": "before: \"test/00-setup.ts\"\n"
},
{
"path": ".tshy/build.json",
"chars": 150,
"preview": "{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"rootDir\": \"../src\",\n \"module\": \"nodenext\",\n \"module"
},
{
"path": ".tshy/commonjs.json",
"chars": 280,
"preview": "{\n \"extends\": \"./build.json\",\n \"include\": [\n \"../src/**/*.ts\",\n \"../src/**/*.cts\",\n \"../src/**/*.tsx\",\n \"."
},
{
"path": ".tshy/esm.json",
"chars": 252,
"preview": "{\n \"extends\": \"./build.json\",\n \"include\": [\n \"../src/**/*.ts\",\n \"../src/**/*.mts\",\n \"../src/**/*.tsx\",\n \"."
},
{
"path": "CONTRIBUTING.md",
"chars": 303,
"preview": "Any change to behavior (including bugfixes) must come with a test.\n\nPatches that fail tests or reduce performance will b"
},
{
"path": "LICENSE.md",
"chars": 1764,
"preview": "All packages under `src/` are licensed according to the terms in\ntheir respective `LICENSE` or `LICENSE.md` files.\n\nThe "
},
{
"path": "README.md",
"chars": 44236,
"preview": "# Glob\n\nMatch files using the patterns the shell uses.\n\nThe most correct and second fastest glob implementation in\nJavaS"
},
{
"path": "benchclean.cjs",
"chars": 86,
"preview": "var rimraf = require('rimraf')\nvar bf = './bench-working-dir/fixture'\nrimraf.sync(bf)\n"
},
{
"path": "benchmark.sh",
"chars": 6086,
"preview": "#!/bin/bash\nexport CDPATH=\nset -e\n\n. patterns.sh\n\nbash make-benchmark-fixture.sh\nwd=$PWD\n\nmkdir -p \"$wd/bench-working-di"
},
{
"path": "changelog.md",
"chars": 8489,
"preview": "# changeglob\n\n## 13\n\n- Move the CLI program out to a separate package, `glob-bin`.\n Install that if you'd like to conti"
},
{
"path": "examples/g.js",
"chars": 238,
"preview": "var Glob = require('../').Glob\n\nvar pattern = 'test/a/**/[cg]/../[cg]'\nconsole.log(pattern)\n\nvar mg = new Glob(pattern, "
},
{
"path": "examples/usr-local.js",
"chars": 220,
"preview": "var Glob = require('../').Glob\n\nvar pattern = '{./*/*,/*,/usr/local/*}'\nconsole.log(pattern)\n\nvar mg = new Glob(pattern,"
},
{
"path": "make-benchmark-fixture.sh",
"chars": 750,
"preview": "#!/bin/bash\n\nwd=$PWD\nmkdir -p \"$wd/bench-working-dir/fixture\"\ntmp=\"$wd/bench-working-dir/fixture\"\nexport CDPATH=\nset -e\n"
},
{
"path": "package.json",
"chars": 2849,
"preview": "{\n \"author\": \"Isaac Z. Schlueter <i@izs.me> (https://blog.izs.me/)\",\n \"name\": \"glob\",\n \"description\": \"the most corre"
},
{
"path": "patterns.sh",
"chars": 1473,
"preview": "patterns=(\n '{0000,0,1111,1}/{0000,0,1111,1}/{0000,0,1111,1}/**'\n\n '**'\n '**/..'\n\n # some of these aren't particular"
},
{
"path": "prof.sh",
"chars": 630,
"preview": "#!/bin/bash\nexport CDPATH=\nset -e\nset -x\n\n. patterns.sh\n\nbash -x make-benchmark-fixture.sh\nwd=$PWD\ntmp=\"$wd/bench-workin"
},
{
"path": "scripts/build.sh",
"chars": 314,
"preview": "#!/usr/bin/env bash\n\nesbuild \\\n --minify \\\n --platform=node \\\n --sourcemap \\\n --bundle dist/commonjs/index.js \\\n --"
},
{
"path": "scripts/make-big-tree.js",
"chars": 1508,
"preview": "#!/usr/bin/env node\nconst mkdirp = require('mkdirp')\nconst { readFileSync } = require('fs')\nconst { writeFile } = requir"
},
{
"path": "src/glob.ts",
"chars": 20602,
"preview": "import type { MinimatchOptions } from 'minimatch'\nimport { Minimatch } from 'minimatch'\nimport type { Minipass } from 'm"
},
{
"path": "src/has-magic.ts",
"chars": 915,
"preview": "import { Minimatch } from 'minimatch'\nimport type { GlobOptions } from './glob.js'\n\n/**\n * Return true if the patterns p"
},
{
"path": "src/ignore.ts",
"chars": 3997,
"preview": "// give it a pattern, and it'll be able to tell you if\n// a given path should be ignored.\n// Ignoring a path ignores its"
},
{
"path": "src/index.ts",
"chars": 6314,
"preview": "import { escape, unescape } from 'minimatch'\nimport type { Minipass } from 'minipass'\nimport type { Path } from 'path-sc"
},
{
"path": "src/pattern.ts",
"chars": 7223,
"preview": "// this is just a very light wrapper around 2 arrays with an offset index\n\nimport { GLOBSTAR } from 'minimatch'\nexport t"
},
{
"path": "src/processor.ts",
"chars": 9506,
"preview": "// synchronous utility for filtering entries and calculating subwalks\n\nimport type { MMRegExp } from 'minimatch'\nimport "
},
{
"path": "src/walker.ts",
"chars": 13988,
"preview": "/**\n * Single-use utility classes to provide functionality to the {@link Glob}\n * methods.\n *\n * @module\n */\nimport { Mi"
},
{
"path": "tap-snapshots/test/bin.ts.test.cjs",
"chars": 10185,
"preview": "/* IMPORTANT\n * This snapshot file is auto-generated, but designed for humans.\n * It should be checked into source contr"
},
{
"path": "tap-snapshots/test/pattern.ts.test.cjs",
"chars": 463,
"preview": "/* IMPORTANT\n * This snapshot file is auto-generated, but designed for humans.\n * It should be checked into source contr"
},
{
"path": "tap-snapshots/test/root.ts.test.cjs",
"chars": 2845,
"preview": "/* IMPORTANT\n * This snapshot file is auto-generated, but designed for humans.\n * It should be checked into source contr"
},
{
"path": "test/00-setup.ts",
"chars": 5250,
"preview": "// just a little pre-run script to set up the fixtures.\n// zz-finish cleans it up\n\nimport { spawn } from 'child_process'"
},
{
"path": "test/absolute-must-be-strings.ts",
"chars": 152,
"preview": "import { Glob } from '../dist/esm/index.js'\nimport t from 'tap'\nt.throws(() => {\n new Glob('.', {\n withFileTypes: tr"
},
{
"path": "test/absolute.ts",
"chars": 1275,
"preview": "import { isAbsolute } from 'path'\nimport type { Test } from 'tap'\nimport t from 'tap'\nimport { fileURLToPath } from 'url"
},
{
"path": "test/bash-comparison.ts",
"chars": 1733,
"preview": "// basic test\n// show that it does the same thing by default as the shell.\nimport { resolve } from 'path'\nimport t from "
},
{
"path": "test/bash-results.ts",
"chars": 4773,
"preview": "// generated via 'npm run test-regen'\nimport { fileURLToPath } from 'url'\n\nif (process.argv[1] === fileURLToPath(import."
},
{
"path": "test/broken-symlink.ts",
"chars": 1529,
"preview": "import { relative } from 'path'\nimport t from 'tap'\nimport { glob } from '../dist/esm/index.js'\nimport type { GlobOption"
},
{
"path": "test/custom-fs.ts",
"chars": 561,
"preview": "import t from 'tap'\nimport { globSync } from '../dist/esm/index.js'\n\n// just a rudimentary test, since PathScurry tests "
},
{
"path": "test/custom-ignore.ts",
"chars": 1537,
"preview": "import { basename } from 'path'\nimport type { Path } from 'path-scurry'\nimport t from 'tap'\nimport { fileURLToPath } fro"
},
{
"path": "test/cwd-noent.ts",
"chars": 1675,
"preview": "import t from 'tap'\nimport { fileURLToPath } from 'url'\nimport { Glob } from '../dist/esm/index.js'\nconst cwd = fileURLT"
},
{
"path": "test/cwd-test.ts",
"chars": 1520,
"preview": "import { resolve, sep } from 'path'\nimport t from 'tap'\nimport { fileURLToPath } from 'url'\nimport { glob } from '../dis"
},
{
"path": "test/dot-relative.ts",
"chars": 2124,
"preview": "import { resolve, sep } from 'path'\nimport t from 'tap'\nimport { fileURLToPath } from 'url'\nimport { Glob } from '../dis"
},
{
"path": "test/empty-set.ts",
"chars": 387,
"preview": "import t from 'tap'\nimport { glob } from '../dist/esm/index.js'\n\n// Patterns that cannot match anything\nconst patterns ="
},
{
"path": "test/escape.ts",
"chars": 759,
"preview": "import t from 'tap'\nimport { unescape, escape, hasMagic } from '../dist/esm/index.js'\nimport { bashResults } from './bas"
},
{
"path": "test/follow.ts",
"chars": 1698,
"preview": "import t from 'tap'\nimport { fileURLToPath } from 'url'\nimport { glob } from '../dist/esm/index.js'\n\nif (process.platfor"
},
{
"path": "test/has-magic.ts",
"chars": 1229,
"preview": "import t from 'tap'\nimport { fileURLToPath } from 'url'\nimport { glob } from '../dist/esm/index.js'\n\nprocess.chdir(fileU"
},
{
"path": "test/ignore.ts",
"chars": 7334,
"preview": "// Ignore option test\n// Show that glob ignores results matching pattern on ignore option\n\nimport { sep } from 'path'\nim"
},
{
"path": "test/include-child-matches.ts",
"chars": 1208,
"preview": "import t from 'tap'\nimport type { GlobOptionsWithFileTypesUnset } from '../src/index.js'\nimport { glob, globSync } from "
},
{
"path": "test/mark.ts",
"chars": 4358,
"preview": "import { sep } from 'path'\nimport t from 'tap'\nimport { fileURLToPath } from 'url'\nimport { glob } from '../dist/esm/ind"
},
{
"path": "test/match-base.ts",
"chars": 2429,
"preview": "import t from 'tap'\nimport { glob } from '../dist/esm/index.js'\nimport { sep } from 'path'\nimport { fileURLToPath } from"
},
{
"path": "test/match-parent.ts",
"chars": 712,
"preview": "import t from 'tap'\nimport { PathScurry } from 'path-scurry'\nimport { Glob } from '../dist/esm/index.js'\n\nconst scurry ="
},
{
"path": "test/match-root.ts",
"chars": 278,
"preview": "import t from 'tap'\nimport { PathScurry } from 'path-scurry'\nimport { Glob } from '../dist/esm/index.js'\n\nconst scurry ="
},
{
"path": "test/max-depth.ts",
"chars": 2757,
"preview": "import { resolve } from 'path'\nimport { PathScurry } from 'path-scurry'\nimport t from 'tap'\nimport { fileURLToPath } fro"
},
{
"path": "test/memfs.ts",
"chars": 1062,
"preview": "import t from 'tap'\n\nif (process.platform === 'win32') {\n t.plan(0, 'this test does not work on windows')\n process.exi"
},
{
"path": "test/nocase-magic-only.ts",
"chars": 291,
"preview": "import t from 'tap'\nimport { Glob } from '../dist/esm/index.js'\n\nconst darwin = new Glob('x', { nocase: true, platform: "
},
{
"path": "test/nodir.ts",
"chars": 1372,
"preview": "import { resolve, sep } from 'path'\nimport t from 'tap'\nimport { fileURLToPath } from 'url'\nimport type { GlobOptions } "
},
{
"path": "test/oom.ts",
"chars": 543,
"preview": "import t from 'tap'\nimport { Glob } from '../src/index.js'\n\nconst pattern =\n '{*z,x*y/z*,a*b*}' +\n '{*z,x*y/z*,a*b*}' "
},
{
"path": "test/pattern.ts",
"chars": 1848,
"preview": "import { GLOBSTAR } from 'minimatch'\nimport t from 'tap'\nimport type { MMPattern } from '../dist/esm/pattern.js'\nimport "
},
{
"path": "test/platform.ts",
"chars": 2094,
"preview": "import { resolve } from 'path'\nimport t from 'tap'\n\nimport {\n PathScurry,\n PathScurryDarwin,\n PathScurryPosix,\n Path"
},
{
"path": "test/progra-tilde.ts",
"chars": 987,
"preview": "// https://github.com/isaacs/node-glob/issues/547\nimport t from 'tap'\n\nimport { globSync } from '../dist/esm/index.js'\ni"
},
{
"path": "test/readme-issue.ts",
"chars": 283,
"preview": "import t from 'tap'\nimport { glob } from '../dist/esm/index.js'\n\nconst dir = t.testdir({\n 'package.json': '{}',\n READM"
},
{
"path": "test/realpath.ts",
"chars": 2925,
"preview": "import * as fs from 'fs'\nimport * as fsp from 'fs/promises'\nimport { resolve } from 'path'\nimport t from 'tap'\nimport { "
},
{
"path": "test/root.ts",
"chars": 984,
"preview": "import { resolve, sep } from 'path'\nimport t from 'tap'\nimport { Glob } from '../dist/esm/index.js'\n\nconst alphasort = ("
},
{
"path": "test/signal.ts",
"chars": 2183,
"preview": "import * as fs from 'fs'\nimport { resolve } from 'path'\nimport t from 'tap'\nimport { fileURLToPath } from 'url'\nimport {"
},
{
"path": "test/slash-cwd.ts",
"chars": 644,
"preview": "// regression test to make sure that slash-ended patterns\n// don't match files when using a different cwd.\nimport t from"
},
{
"path": "test/stat.ts",
"chars": 680,
"preview": "import { resolve } from 'path'\nimport t from 'tap'\nimport { fileURLToPath } from 'url'\nimport { glob, globSync } from '."
},
{
"path": "test/stream.ts",
"chars": 6025,
"preview": "import { resolve, sep } from 'path'\nimport t from 'tap'\nimport { fileURLToPath } from 'url'\nimport {\n Glob,\n globItera"
},
{
"path": "test/url-cwd.ts",
"chars": 497,
"preview": "import t from 'tap'\nimport { pathToFileURL } from 'url'\nimport { Glob } from '../dist/esm/index.js'\n\nt.test('can use fil"
},
{
"path": "test/windows-paths-fs.ts",
"chars": 1743,
"preview": "// test that escape chars are handled properly according to configs\n// when found in patterns and paths containing glob "
},
{
"path": "test/windows-paths-no-escape.ts",
"chars": 1267,
"preview": "import t from 'tap'\nimport { Glob } from '../dist/esm/index.js'\n\nconst platforms = ['win32', 'posix']\nconst originalPlat"
},
{
"path": "tsconfig.json",
"chars": 429,
"preview": "{\n \"compilerOptions\": {\n \"declaration\": true,\n \"declarationMap\": true,\n \"esModuleInterop\": true,\n \"forceCon"
},
{
"path": "typedoc.json",
"chars": 220,
"preview": "{\n \"tsconfig\": \"./.tshy/esm.json\",\n \"entryPoints\": [\"./src/**/*.+(ts|tsx|mts|cts)\"],\n \"navigationLinks\": {\n \"GitHu"
}
]
About this extraction
This page contains the full source code of the isaacs/node-glob GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 75 files (220.1 KB), approximately 65.5k tokens, and a symbol index with 113 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.