Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kaelzhang/node-glob-gitignore
Extends `glob` with support for filtering files according to gitignore rules and exposes an optional Promise API
https://github.com/kaelzhang/node-glob-gitignore
gitignore-rules glob nodejs promise
Last synced: 5 days ago
JSON representation
Extends `glob` with support for filtering files according to gitignore rules and exposes an optional Promise API
- Host: GitHub
- URL: https://github.com/kaelzhang/node-glob-gitignore
- Owner: kaelzhang
- License: other
- Created: 2017-05-17T14:39:35.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-24T11:09:16.000Z (about 1 month ago)
- Last Synced: 2024-10-30T06:26:11.598Z (8 days ago)
- Topics: gitignore-rules, glob, nodejs, promise
- Language: JavaScript
- Homepage:
- Size: 27.3 KB
- Stars: 17
- Watchers: 5
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/kaelzhang/node-glob-gitignore/actions/workflows/nodejs.yml)
# glob-gitignore
Extends [`glob`](https://www.npmjs.com/package/glob) with support for filtering files according to gitignore rules and exposes an optional Promise API, based on [`node-ignore`](https://www.npmjs.com/package/ignore).
This module is built to solve performance issues, see [Why](#why).
## Install
```sh
$ npm i glob-gitignore --save
```
## Usage
```js
import {
glob,
sync,
hasMagic
} from 'glob-gitignore'
// The usage of glob-gitignore is much the same as `node-glob`,
// and it supports an array of patterns to be matched
glob(['**'], {
cwd: '/path/to',
// Except that options.ignore accepts an array of gitignore rules,
// or a gitignore rule,
// or an `ignore` instance.
ignore: '*.bak'
})
// And glob-gitignore returns a promise
.then(files => {
console.log(files)
})
// A string of pattern is also supported.
glob('**', options)
// To glob things synchronously, use `sync`
const files = sync('**', {ignore: '*.bak'})
hasMagic('a/{b/c,x/y}') // true
```
## Why
1. The `options.ignore` of `node-glob` does not support gitignore rules.
2. It is better **NOT** to glob things then filter them by gitignore rules. Because by doing this, there will be so much unnecessary harddisk traversing, and cause performance issues, especially if there are tremendous files and directories inside the working directory. For the situation, you'd better to use this module.
`glob-gitignore` does the filtering at the very process of each decending down.
## glob(patterns, options)
Returns a `Promise`
- **patterns** `String|Array.` The pattern or array of patterns to be matched.
And negative patterns (each of which starts with an `!`) are supported, although negative patterns are **NOT** recommended. You'd better to use `options.ignore`.
```js
glob(['*.js', 'a/**', '!a/**/*.png']).then(console.log)
```
- **options** `Object` the [glob options](https://www.npmjs.com/package/glob#options) except for `options.ignore`
### `options.ignore`
Could be a `String`, an array of `String`s, or an instance of [node-`ignore`](https://www.npmjs.com/package/ignore)
Not setting this is kind of silly, since that's the whole purpose of this lib, but it is optional though.
```js
glob('**', {ignore: '*.js'})
glob('**', {ignore: ['*.css', '*.styl']})
import ignore from 'ignore'
glob('**', {
ignore: ignore().add('*.js')
})
```
## sync(patterns, options)
The synchronous globber, which returns an `Array.`.
## hasMagic(patterns, [options])
This method extends `glob.hasMagic(pattern)` and supports an array of patterns.
Returns
- `true` if there are any special characters in the pattern, or there is any of a pattern in the array has special characters.
- `false` otherwise.
```js
hasMagic('a/{b/c,x/y}') // true
hasMagic(['a/{b/c,x/y}', 'a']) // true
hasMagic(['a']) // false
```
Note that the options affect the results. If `noext:true` is set in the options object, then `+(a|b)` will not be considered a magic pattern. If the pattern has a brace expansion, like `a/{b/c,x/y}` then that is considered magical, unless `nobrace:true` is set in the options.
## License
MIT