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:
- Install
- Usage
- API
- Middleware
- Globbing examples
- Events
- FAQ
- TODO
- Community middleware
- Related projects
- Running tests
- Contributing
- Author
- License
(Table of contents generated by verb)
Install with npm
$ npm i glob-fs --saveParams
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 forglob-fsor 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}: Callback
Example
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 theGlobinstance, 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:
- be chained
includeorexcludea file based on some condition, like whether or not one of its properties matches a regex or glob pattern.- determine whether or not to continue recursing in a specific directory
- modifying an existing property to the
fileobject - add a new property to the
fileobject
Ignoring 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:
- glob-fs-dotfiles: glob-fs middleware for automatically ignoring dotfiles.
- glob-fs-gitignore: glob-fs middleware for automatically ignoring files specified in
.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.
- Naming: any middleware published to npm should be prefixed with
glob-fs-, as in:glob-fs-dotfiles. - Keywords: please add
glob-fsto the keywords array in package.json - Options: all middleware should return a function that takes an
optionsobject, as in the Middleware Example - Return
file: all middleware should return thefileobject after processing.
- A middleware should only do one specific thing.
- Multiple middleware libs can be bundled together to create a single middleware.
- Pattern matching should be extremely specific. Don't force downstream middleware to reverse your mistakes.
- As mentioned in the middleware conventions section, always return the
fileobject. - A single conditional should only set
file.excludetotrue, orfile.includetotrue, never both. - It's completely okay to check
this.options - Middleware modules should be fully documented.
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 afileobject when it's matchedexclude: emits afileobject when it's ignored/excludedfile: emits afileobject when the iterator pushes it into the results array. Only applies tosync,asyncandpromise.dir: emits afileobject when the iterator finds a directoryendwhen the iterator is finished readingerroron errors
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)) {
// 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');
});- when files are read from the file system, an object is created to keep a record of the file's
path,dirname, and fsstatobject and other pertinent information that makes it easier to make decisions about inclusion and exclusion later on. fileobjects are decorated with aparsemethod that is used to calculate thefile.relativeandfile.absoluteproperties.- the
file.parse()method is called in the iterator, right after the call tofs.statsand just before the call to the middleware handler (.handle()). This ensures that all middleware have access to necessary path information. file.relativeis the file path that's actually pushed into thefilesarray that is ultimately returned.file.relativeis calculated usingpath.relative(file.path, cwd), wherecwdis passed on the options (globally, or on a middleware), andfile.pathis typically the absolute, actual file path to the file being globbed.
middleware
- middleware
- middleware handler
- externalize middleware to modules (started, prs welcome!)
events
- events
tests
- unit tests (need to be moved)
iterators
- sync iterator
- async iterator
- stream iterator
- promise iterator
read methods
- glob.readdir (async)
- glob.readdirSync
- glob.readdirStream
- glob.readdirPromise
patterns
- Multiple pattern support. will need to change pattern handling, middleware handling. this is POC currently
- Negation patterns (might not do this, since it can be handled in middleware)
- matching method, memoized/cached/bound to a glob pattern or patterns, so it can be reused without having to recompile the regex.
other
- clean up
./lib - comparsion to [node-glob][]
(Add your project to the .verb.md template do a PR!)
- glob-fs-dotfiles: glob-fs middleware for automatically ignoring dotfiles.
- glob-fs-gitignore: glob-fs middleware for automatically ignoring files specified in
.gitignore
- 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
trueif 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
Install dev dependencies:
$ npm i -d && npm testPull 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent