glob-fs 
file globbing for node.js. speedy and powerful alternative to node-glob.
Usage
var glob = require('glob-fs')({ gitignore: true });
var files = glob.readdirSync('**/*.js');
Run actual examples:
Jump to docs sections:
Table of contents
(Table of contents generated by verb)
Install
Install with npm
$ npm i glob-fs --save
Usage
Params
All "read" methods take a glob pattern and an options
object. Examples:
var files = glob.readdirSync('*.js', {});
glob.readdir('*.js', function(err, files) {
console.log(files);
});
glob.readdirStream('*.js', {})
.on('data', function(file) {
console.log(file);
});
glob.readdirPromise('*.js')
.then(function(files) {
console.log(file);
});
API
Asynchronously glob files or directories that match the given pattern
.
Params
pattern
{String}: Glob pattern
options
{Object}
cb
{Function}: Callback
Example
var glob = require('glob-fs')({ gitignore: true });
glob.readdir('*.js', function (err, files) {
});
Synchronously glob files or directories that match the given pattern
.
Params
pattern
{String}: Glob pattern
options
{Object}
returns
{Array}: Returns an array of files.
Example
var glob = require('glob-fs')({ gitignore: true });
var files = glob.readdirSync('*.js');
Stream files or directories that match the given glob pattern
.
Params
pattern
{String}: Glob pattern
options
{Object}
returns
{Stream}
Example
var glob = require('glob-fs')({ gitignore: true });
glob.readdirStream('*.js')
.on('data', function (file) {
console.log(file.path);
})
.on('error', console.error)
.on('end', function () {
console.log('end');
});
Optionally create an instance of Glob
with the given options
.
Params
Example
var Glob = require('glob-fs').Glob;
var glob = new Glob();
Thin wrapper around .use()
for easily excluding files or directories that match the given pattern
.
Params
pattern
{String}
options
{Object}
Example
var gitignore = require('glob-fs-gitignore');
var dotfiles = require('glob-fs-dotfiles');
var glob = require('glob-fs')({ foo: true })
.exclude(/\.foo$/)
.exclude('*.bar')
.exclude('*.baz');
var files = glob.readdirSync('**');
Add a middleware to be called in the order defined.
Params
fn
{Function}
returns
{Object}: Returns the Glob
instance, for chaining.
Example
var gitignore = require('glob-fs-gitignore');
var dotfiles = require('glob-fs-dotfiles');
var glob = require('glob-fs')({ foo: true })
.use(gitignore())
.use(dotfiles());
var files = glob.readdirSync('*.js');
Middleware
glob-fs uses middleware to add file matching and exclusion capabilities, or other features that may or may not eventually become core functionality.
What is a middleware?
A middleware is a function that "processes" files as they're read from the file system by glob-fs.
What does "process" mean?
Typically, it means one of the following:
- matching a
file.path
, or
- modifying a property on the
file
object, or
- determining whether or not to continue recursing
Middleware examples
recursing
Here is how a middleware might determine whether or not to recurse based on a glob pattern:
var glob = require('glob-fs');
function recurse() {
return function(file) {
file.recurse = file.pattern.glob.indexOf('**') !== -1;
return file;
}
}
glob()
.use(recurse())
.readdir('**/*.js', function(err, files) {
console.log(files);
});
exclusion
Middleware for excluding file paths:
function tests(options) {
return function(file) {
if (/^test\//.test(file.dirname)) {
file.exclude = true;
}
return file;
};
}
var glob = glob({ gitignore: true })
.use(tests())
glob.readdirStream('**/*')
.on('data', function (file) {
console.log(file.path);
})
Middleware conventions
- Naming: any middleware published to npm should be prefixed with
glob-fs-
, as in: glob-fs-dotfiles
.
- Keywords: please add
glob-fs
to the keywords array in package.json
- Options: all middleware should return a function that takes an
options
object, as in the Middleware Example
- Return
file
: all middleware should return the file
object after processing.
Globbing examples
Note that the gitignore
option is already true
by default, it's just shown here as a placeholder for how options may be defined.
async
var glob = require('glob-fs')({ gitignore: true });
glob.readdir('**/*.js', function(err, files) {
console.log(files);
});
promise
var glob = require('glob-fs')({ gitignore: true });
glob.readdirPromise('**/*')
.then(function (files) {
console.log(files);
});
stream
var glob = require('glob-fs')({ gitignore: true });
glob.readdirStream('**/*')
.on('data', function (file) {
console.log(file.path);
})
sync
var glob = require('glob-fs')({ gitignore: true });
var files = glob.readdirSync('**/*.js');
console.log(files);
Events
(WIP)
The following events are emitted with all "read" methods:
include
: emits a file
object when it's matched
exclude
: emits a file
object when it's ignored/excluded
file
: emits a file
object when the iterator pushes it into the results array. Only applies to sync
, async
and promise
.
dir
: emits a file
object when the iterator finds a directory
end
when the iterator is finished reading
error
on errors
Event examples
async
var glob = require('..')({ gitignore: true });
glob.on('dir', function (file) {
console.log(file);
});
glob.readdir('**/*.js', function (err, files) {
if (err) return console.error(err);
console.log(files.length);
});
promise
var glob = require('glob-fs')({ gitignore: true });
glob.on('include', function (file) {
console.log('including:', file.path);
});
glob.on('exclude', function (file) {
console.log('excluding:', file.path);
});
glob.readdirPromise('**/*');
sync
Also has an example of a custom event, emitted from a middleware:
var glob = require('glob-fs')({ gitignore: true })
.use(function (file) {
if (/\.js$/.test(file.path)) {
this.emit('js', file);
}
return file;
});
glob.on('js', function (file) {
console.log('js file:', file.path);
});
glob.on('exclude', function (file) {
console.log('excluded:', i.excludes++);
});
glob.on('include', function (file) {
console.log('included:', i.includes++)
});
glob.on('end', function () {
console.log('total files:', this.files.length);
});
glob.readdirSync('**/*.js');
stream
var glob = require('glob-fs')({ gitignore: true })
glob.readdirStream('**/*')
.on('data', function (file) {
console.log(file.path)
})
.on('error', console.error)
.on('end', function () {
console.log('end');
});
TODO
middleware
events
tests
iterators
read methods
patterns
other
Related projects
- braces: Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces… more
- fill-range: Fill in a range of numbers or letters, optionally passing an increment or multiplier to… more
- is-glob: Returns
true
if the given string looks like a glob pattern.
- micromatch: Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. Just… more
Running tests
Install dev dependencies:
$ npm i -d && npm test
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue
Author
Jon Schlinkert
License
Copyright © 2015 Jon Schlinkert
Released under the MIT license.
This file was generated by verb-cli on July 09, 2015.