{"id":29200134,"url":"https://github.com/micromatch/glob-fs","last_synced_at":"2025-12-16T13:59:30.005Z","repository":{"id":25252639,"uuid":"28677608","full_name":"micromatch/glob-fs","owner":"micromatch","description":"file globbing for node.js. speedy and powerful alternative to node-glob. This library is experimental and does not work on windows! ","archived":false,"fork":false,"pushed_at":"2022-01-08T05:25:22.000Z","size":107,"stargazers_count":56,"open_issues_count":29,"forks_count":17,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-11-23T07:29:51.111Z","etag":null,"topics":["files","fs","glob","glob-pattern","match","micromatch","minimatch","multimatch","node","node-glob","patterns"],"latest_commit_sha":null,"homepage":"http://jonschlinkert.github.io/glob-fs","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/micromatch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-01T00:05:19.000Z","updated_at":"2025-03-25T12:54:40.000Z","dependencies_parsed_at":"2022-09-16T22:13:11.779Z","dependency_job_id":null,"html_url":"https://github.com/micromatch/glob-fs","commit_stats":null,"previous_names":["jonschlinkert/glob-fs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/micromatch/glob-fs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromatch%2Fglob-fs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromatch%2Fglob-fs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromatch%2Fglob-fs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromatch%2Fglob-fs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micromatch","download_url":"https://codeload.github.com/micromatch/glob-fs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micromatch%2Fglob-fs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27765950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["files","fs","glob","glob-pattern","match","micromatch","minimatch","multimatch","node","node-glob","patterns"],"created_at":"2025-07-02T10:06:30.241Z","updated_at":"2025-12-16T13:59:29.957Z","avatar_url":"https://github.com/micromatch.png","language":"JavaScript","readme":"# glob-fs [![NPM version](https://badge.fury.io/js/glob-fs.svg)](http://badge.fury.io/js/glob-fs)\n\n\u003e file globbing for node.js. speedy and powerful alternative to node-glob.\n\n## Usage\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\nvar files = glob.readdirSync('**/*.js');\n```\n\n[Run actual examples](./examples/):\n\nJump to docs sections:\n\n* [glob.readdir](#async)\n* [glob.readPromise](#promise)\n* [glob.readStream](#stream)\n* [glob.readdirSync](#sync)\n\n## Table of contents\n\n\u003c!-- toc --\u003e\n\n* [Install](#install)\n* [Usage](#usage)\n* [API](#api)\n* [Middleware](#middleware)\n  - [Middleware examples](#middleware-examples)\n  - [Middleware conventions](#middleware-conventions)\n  - [Advice for middleware authors](#advice-for-middleware-authors)\n* [Globbing examples](#globbing-examples)\n  - [async](#async)\n  - [promise](#promise)\n  - [stream](#stream)\n  - [sync](#sync)\n* [Events](#events)\n  - [Event examples](#event-examples)\n* [FAQ](#faq)\n* [TODO](#todo)\n* [Community middleware](#community-middleware)\n* [Related projects](#related-projects)\n* [Running tests](#running-tests)\n* [Contributing](#contributing)\n* [Author](#author)\n* [License](#license)\n\n_(Table of contents generated by [verb](https://github.com/assemble/verb))_\n\n\u003c!-- tocstop --\u003e\n\n## Install\n\nInstall with [npm](https://www.npmjs.com/)\n\n```sh\n$ npm i glob-fs --save\n```\n\n## Usage\n\n**Params**\n\nAll \"read\" methods take a glob pattern and an `options` object.\n\n* `pattern` **{String}**: Glob pattern to use for matching. (multiple pattern support is planned)\n* `options` **{Object}**: Options for `glob-fs` or middleware.\n\n**Examples:**\n\n```js\n// sync\nvar files = glob.readdirSync('*.js', {});\n\n// async\nglob.readdir('*.js', function(err, files) {\n  console.log(files);\n});\n\n// stream\nglob.readdirStream('*.js', {})\n  .on('data', function(file) {\n    console.log(file);\n  });\n\n// promise\nglob.readdirPromise('*.js')\n  .then(function(files) {\n    console.log(file);\n  });\n```\n\n## API\n\n### [.readdir](lib/readers.js#L25)\n\nAsynchronously glob files or directories that match the given `pattern`.\n\n**Params**\n\n* `pattern` **{String}**: Glob pattern\n* `options` **{Object}**\n* `cb` **{Function}**: Callback\n\n**Example**\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nglob.readdir('*.js', function (err, files) {\n  //=\u003e do stuff with `files`\n});\n```\n\n### [.readdirSync](lib/readers.js#L59)\n\nSynchronously glob files or directories that match the given `pattern`.\n\n**Params**\n\n* `pattern` **{String}**: Glob pattern\n* `options` **{Object}**\n* `returns` **{Array}**: Returns an array of files.\n\n**Example**\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nvar files = glob.readdirSync('*.js');\n//=\u003e do stuff with `files`\n```\n\n### [.readdirStream](lib/readers.js#L90)\n\nStream files or directories that match the given glob `pattern`.\n\n**Params**\n\n* `pattern` **{String}**: Glob pattern\n* `options` **{Object}**\n* `returns` **{Stream}**\n\n**Example**\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nglob.readdirStream('*.js')\n  .on('data', function (file) {\n    console.log(file.path);\n  })\n  .on('error', console.error)\n  .on('end', function () {\n    console.log('end');\n  });\n```\n\n### [Glob](index.js#L42)\n\nOptionally create an instance of `Glob` with the given `options`.\n\n**Params**\n\n* `options` **{Object}**\n\n**Example**\n\n```js\nvar Glob = require('glob-fs').Glob;\nvar glob = new Glob();\n```\n\n### [.use](index.js#L178)\n\nAdd a middleware to be called in the order defined.\n\n**Params**\n\n* `fn` **{Function}**\n* `returns` **{Object}**: Returns the `Glob` instance, for chaining.\n\n**Example**\n\n```js\nvar gitignore = require('glob-fs-gitignore');\nvar dotfiles = require('glob-fs-dotfiles');\nvar glob = require('glob-fs')({ foo: true })\n  .use(gitignore())\n  .use(dotfiles());\n\nvar files = glob.readdirSync('**');\n```\n\n### [.exclude](index.js#L219)\n\nThin wrapper around `.use()` for easily excluding files or directories that match the given `pattern`.\n\n**Params**\n\n* `pattern` **{String}**\n* `options` **{Object}**\n\n**Example**\n\n```js\nvar gitignore = require('glob-fs-gitignore');\nvar dotfiles = require('glob-fs-dotfiles');\nvar glob = require('glob-fs')()\n  .exclude(/\\.foo$/)\n  .exclude('*.bar')\n  .exclude('*.baz');\n\nvar files = glob.readdirSync('**');\n//=\u003e ['index.js', 'README.md', ...]\n```\n\n## Middleware\n\nglob-fs uses middleware to add file matching and exclusion capabilities, or other features that may or may not eventually become core functionality.\n\n**What is a middleware?**\n\nA middleware is a function that \"processes\" files as they're read from the file system by glob-fs.\n\nAdditionally, middleware can:\n\n* be chained\n* `include` or `exclude` a file based on some condition, like whether or not one of its properties matches a regex or glob pattern.\n* determine whether or not to continue recursing in a specific directory\n* modifying an existing property to the `file` object\n* add a new property to the `file` object\n\n### Middleware examples\n\n**Ignoring files**\n\nIn the following example, `notemp` is a complete and functional middleware for excluding any filepath that has the substring `temp`:\n\n```js\nvar glob = require('glob-fs')();\n\nfunction notemp(file) {\n  if (/temp/.test(file.path)) {\n    file.exclude = true;\n  }\n  return file;\n}\n\nglob.use(notemp)\n  .readdirStream('**/*.js')\n  .on('data', function(file) {\n    console.log(file.relative);\n  });\n```\n\n**Matching**\n\nPattern matching is done by default in glob-fs, but you get disable the built-in matchers or get more specific by adding a middleware that uses [micromatch][] or [minimatch](https://github.com/isaacs/minimatch#readme) for matching files.\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\nvar mm = require('micromatch');\n\nglob.use(function(file) {\n    if (mm.isMatch(file.relative, 'vendor/**')) file.exclude = true;\n    return file;\n  })\n  .readdirStream('**/*.js')\n  .on('data', function(file) {\n    console.log(file.relative);\n  });\n```\n\n**recursion**\n\nHere is how a middleware might determine whether or not to recurse based on a certain pattern:\n\n```js\nvar glob = require('glob-fs')();\n\n// this specific check is already done by glob-fs, it's just used here as an example \nfunction recurse(file) {\n  // `file.pattern` is an object with a `glob` (string) property\n  file.recurse = file.pattern.glob.indexOf('**') !== -1;\n  return file;\n}\n\n// use the middleware\nglob.use(recurse)\n  .readdir('**/*.js', function(err, files) {\n    console.log(files);\n  });\n```\n\n**Built-in middleware**\n\nCurrently glob-fs includes and runs the following middleware automatically:\n\n\u003c!-- list automatically generated from deps. see .verb.md --\u003e\n\n* [glob-fs-dotfiles](https://github.com/jonschlinkert/glob-fs-dotfiles): glob-fs middleware for automatically ignoring dotfiles.\n* [glob-fs-gitignore](https://github.com/jonschlinkert/glob-fs-gitignore): glob-fs middleware for automatically ignoring files specified in `.gitignore`\n\n**Disabling built-ins**\n\nTo disable built-in middleware and prevent them from running, pass `builtins: false` on the global options. This will disable **all built-in middleware**.\n\nExample:\n\n```js\nvar glob = require('glob-fs')({builtins: false});\n```\n\nTo disable a specific middleware from running, you can usually pass the name of the middleware on the options, like `dotfiles: false`, but it's best to check the readme of that middleware for specifics.\n\n### Middleware conventions\n\n* **Naming**: any middleware published to npm should be prefixed with `glob-fs-`, as in: `glob-fs-dotfiles`.\n* **Keywords**: please add `glob-fs` to the keywords array in package.json\n* **Options**: all middleware should return a function that takes an `options` object, as in the [Middleware Example](#middleware-example)\n* **Return `file`**: all middleware should return the `file` object after processing.\n\n### Advice for middleware authors\n\n* A middleware should only do one specific thing.\n* Multiple middleware libs can be bundled together to create a single middleware.\n* Pattern matching should be extremely specific. Don't force downstream middleware to reverse your mistakes.\n* As mentioned in the [middleware conventions](#middleware-conventions) section, **always return the `file` object**.\n* A single conditional should only set `file.exclude` to `true`, or `file.include` to `true`, never both.\n* It's completely okay to check `this.options`\n* Middleware modules should be fully documented.\n\n## Globbing examples\n\nNote that the `gitignore` option is already `true` by default, it's just shown here as a placeholder for how options may be defined.\n\n### async\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nglob.readdir('**/*.js', function(err, files) {\n  console.log(files);\n});\n```\n\n### promise\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nglob.readdirPromise('**/*')\n  .then(function (files) {\n    console.log(files);\n  });\n```\n\n### stream\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nglob.readdirStream('**/*')\n  .on('data', function (file) {\n    console.log(file.path);\n  })\n```\n\n### sync\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nvar files = glob.readdirSync('**/*.js');\nconsole.log(files);\n```\n\n## Events\n\n_(WIP)_\n\nThe following events are emitted with all \"read\" methods:\n\n* `read`: emitted immediately before an iterator calls the first middleware.\n* `include`: emits a `file` object when it's matched\n* `exclude`: emits a `file` object when it's ignored/excluded\n* `file`: emits a `file` object when the iterator pushes it into the results array. Only applies to `sync`, `async` and `promise`.\n* `dir`: emits a `file` object when the iterator finds a directory\n* `end` when the iterator is finished reading\n* `error` on errors\n\n### Event examples\n\n**async**\n\n```js\nvar glob = require('..')({ gitignore: true });\n\nglob.on('dir', function (file) {\n  console.log(file);\n});\n\nglob.readdir('**/*.js', function (err, files) {\n  if (err) return console.error(err);\n  console.log(files.length);\n});\n```\n\n**promise**\n\n```js\nvar glob = require('glob-fs')({ gitignore: true });\n\nglob.on('include', function (file) {\n  console.log('including:', file.path);\n});\n\nglob.on('exclude', function (file) {\n  console.log('excluding:', file.path);\n});\n\nglob.readdirPromise('**/*');\n```\n\n**sync**\n\nAlso has an example of a custom event, emitted from a middleware:\n\n```js\nvar glob = require('glob-fs')({ gitignore: true })\n  .use(function (file) {\n    if (/\\.js$/.test(file.path)) {\n      // custom event\n      this.emit('js', file);\n    }\n    return file;\n  });\n\nglob.on('js', function (file) {\n  console.log('js file:', file.path);\n});\n\nglob.on('exclude', function (file) {\n  console.log('excluded:', i.excludes++);\n});\n\nglob.on('include', function (file) {\n  console.log('included:', i.includes++)\n});\n\nglob.on('end', function () {\n  console.log('total files:', this.files.length);\n});\n\nglob.readdirSync('**/*.js');\n```\n\n**stream**\n\n```js\nvar glob = require('glob-fs')({ gitignore: true })\n\nglob.readdirStream('**/*')\n  .on('data', function (file) {\n    console.log(file.path)\n  })\n  .on('error', console.error)\n  .on('end', function () {\n    console.log('end');\n  });\n```\n\n## FAQ\n\n* when files are read from the file system, an object is created to keep a record of the file's `path`, `dirname`, and fs `stat` object and other pertinent information that makes it easier to make decisions about inclusion and exclusion later on.\n* `file` objects are decorated with a `parse` method that is used to calculate the `file.relative` and `file.absolute` properties.\n* the `file.parse()` method is called in the iterator, right after the call to `  fs.stats` and just before the call to the middleware handler (`.handle()`). This ensures that all middleware have access to necessary path information.\n* `file.relative` is the file path that's actually pushed into the `files` array that is ultimately returned.\n* `file.relative` is calculated using `path.relative(file.path, cwd)`, where `cwd` is passed on the options (globally, or on a middleware), and `file.path` is typically the absolute, actual file path to the file being globbed.\n\n## TODO\n\n**middleware**\n\n* [x] middleware\n* [x] middleware handler\n* [ ] externalize middleware to modules (started, [prs welcome!](#contributing))\n\n**events**\n\n* [x] events\n\n**tests**\n\n* [x] unit tests (need to be moved)\n\n**iterators**\n\n* [x] sync iterator\n* [x] async iterator\n* [x] stream iterator\n* [x] promise iterator\n\n**read methods**\n\n* [x] glob.readdir (async)\n* [x] glob.readdirSync\n* [x] glob.readdirStream\n* [x] glob.readdirPromise\n\n**patterns**\n\n* [ ] Multiple pattern support. will need to change pattern handling, middleware handling. this is POC currently\n* [ ] Negation patterns (might not do this, since it can be handled in middleware)\n* [ ] matching method, memoized/cached/bound to a glob pattern or patterns, so it can be reused without having to recompile the regex.\n\n**other**\n\n* [ ] clean up `./lib`\n* [ ] comparsion to [node-glob][]\n\n## Community middleware\n\n_(Add your project to the [.verb.md](./.verb.md) template do a PR!)_\n\n\u003c!-- remove these after we get some community middleware libs listed --\u003e\n\n* [glob-fs-dotfiles](https://github.com/jonschlinkert/glob-fs-dotfiles): glob-fs middleware for automatically ignoring dotfiles.\n* [glob-fs-gitignore](https://github.com/jonschlinkert/glob-fs-gitignore): glob-fs middleware for automatically ignoring files specified in `.gitignore`\n\n## Related projects\n\n* [braces](https://github.com/jonschlinkert/braces): Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces… [more](https://github.com/jonschlinkert/braces)\n* [fill-range](https://github.com/jonschlinkert/fill-range): Fill in a range of numbers or letters, optionally passing an increment or multiplier to… [more](https://github.com/jonschlinkert/fill-range)\n* [is-glob](https://github.com/jonschlinkert/is-glob): Returns `true` if the given string looks like a glob pattern.\n* [micromatch](https://github.com/jonschlinkert/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. Just… [more](https://github.com/jonschlinkert/micromatch)\n\n## Running tests\n\nInstall dev dependencies:\n\n```sh\n$ npm i -d \u0026\u0026 npm test\n```\n\n## Contributing\n\nPull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/glob-fs/issues/new)\n\n## Author\n\n**Jon Schlinkert**\n\n+ [github/jonschlinkert](https://github.com/jonschlinkert)\n+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)\n\n## License\n\nCopyright © 2015 Jon Schlinkert\nReleased under the MIT license.\n\n***\n\n_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on July 11, 2015._","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicromatch%2Fglob-fs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicromatch%2Fglob-fs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicromatch%2Fglob-fs/lists"}