file globbing for node.js. speedy and powerful alternative to node-glob.
var glob = require('glob-fs')({ gitignore: true });
var files = glob.readdirSync('**/*.js');
Jump to docs sections:
(Table of contents generated by verb)
Install with npm
$ npm i glob-fs --save
Params
All "read" methods take a glob pattern and an options
object.
pattern
{String}: Glob pattern to use for matching. (multiple pattern support is planned)options
{Object}: Options for glob-fs
or middleware.Examples:
// sync
var files = glob.readdirSync('*.js', {});
// async
glob.readdir('*.js', function(err, files) {
console.log(files);
});
// stream
glob.readdirStream('*.js', {})
.on('data', function(file) {
console.log(file);
});
// promise
glob.readdirPromise('*.js')
.then(function(files) {
console.log(file);
});
Asynchronously glob files or directories that match the given pattern
.
Params
pattern
{String}: Glob patternoptions
{Object}cb
{Function}: CallbackExample
var glob = require('glob-fs')({ gitignore: true });
glob.readdir('*.js', function (err, files) {
//=> do stuff with `files`
});
Synchronously glob files or directories that match the given pattern
.
Params
pattern
{String}: Glob patternoptions
{Object}returns
{Array}: Returns an array of files.Example
var glob = require('glob-fs')({ gitignore: true });
var files = glob.readdirSync('*.js');
//=> do stuff with `files`
Stream files or directories that match the given glob pattern
.
Params
pattern
{String}: Glob patternoptions
{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
options
{Object}Example
var Glob = require('glob-fs').Glob;
var glob = new Glob();
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('**');
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')()
.exclude(/\.foo$/)
.exclude('*.bar')
.exclude('*.baz');
var files = glob.readdirSync('**');
//=> ['index.js', 'README.md', ...]
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.
Additionally, middleware can:
include
or exclude
a file based on some condition, like whether or not one of its properties matches a regex or glob pattern.file
objectfile
objectIgnoring files
In the following example, notemp
is a complete and functional middleware for excluding any filepath that has the substring temp
:
var glob = require('glob-fs')();
function notemp(file) {
if (/temp/.test(file.path)) {
file.exclude = true;
}
return file;
}
glob.use(notemp)
.readdirStream('**/*.js')
.on('data', function(file) {
console.log(file.relative);
});
Matching
Pattern 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 for matching files.
var glob = require('glob-fs')({ gitignore: true });
var mm = require('micromatch');
glob.use(function(file) {
if (mm.isMatch(file.relative, 'vendor/**')) file.exclude = true;
return file;
})
.readdirStream('**/*.js')
.on('data', function(file) {
console.log(file.relative);
});
recursion
Here is how a middleware might determine whether or not to recurse based on a certain pattern:
var glob = require('glob-fs')();
// this specific check is already done by glob-fs, it's just used here as an example
function recurse(file) {
// `file.pattern` is an object with a `glob` (string) property
file.recurse = file.pattern.glob.indexOf('**') !== -1;
return file;
}
// use the middleware
glob.use(recurse)
.readdir('**/*.js', function(err, files) {
console.log(files);
});
Built-in middleware
Currently glob-fs includes and runs the following middleware automatically:
.gitignore
Disabling built-ins
To disable built-in middleware and prevent them from running, pass builtins: false
on the global options. This will disable all built-in middleware.
Example:
var glob = require('glob-fs')({builtins: false});
To 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.
glob-fs-
, as in: glob-fs-dotfiles
.glob-fs
to the keywords array in package.jsonoptions
object, as in the Middleware Examplefile
: all middleware should return the file
object after processing.file
object.file.exclude
to true
, or file.include
to true
, never both.this.options
Note that the gitignore
option is already true
by default, it's just shown here as a placeholder for how options may be defined.
var glob = require('glob-fs')({ gitignore: true });
glob.readdir('**/*.js', function(err, files) {
console.log(files);
});
var glob = require('glob-fs')({ gitignore: true });
glob.readdirPromise('**/*')
.then(function (files) {
console.log(files);
});
var glob = require('glob-fs')({ gitignore: true });
glob.readdirStream('**/*')
.on('data', function (file) {
console.log(file.path);
})
var glob = require('glob-fs')({ gitignore: true });
var files = glob.readdirSync('**/*.js');
console.log(files);
(WIP)
The following events are emitted with all "read" methods:
read
: emitted immediately before an iterator calls the first middleware.include
: emits a file
object when it's matchedexclude
: emits a file
object when it's ignored/excludedfile
: 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 directoryend
when the iterator is finished readingerror
on errorsasync
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)) {
// custom event
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');
});
path
, dirname
, and fs stat
object and other pertinent information that makes it easier to make decisions about inclusion and exclusion later on.file
objects are decorated with a parse
method that is used to calculate the file.relative
and file.absolute
properties.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.file.relative
is the file path that's actually pushed into the files
array that is ultimately returned.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.middleware
events
tests
iterators
read methods
patterns
other
./lib
(Add your project to the .verb.md template do a PR!)
.gitignore
true
if the given string looks like a glob pattern.Install dev dependencies:
$ npm i -d && npm test
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue
Jon Schlinkert
Copyright © 2015 Jon Schlinkert Released under the MIT license.
This file was generated by verb-cli on July 11, 2015.