Linux	OS X	Windows	Coverage	Downloads

@diotobtea/unde-molestiae

@diotobtea/unde-molestiae is a manager, filter and parser which implemented in pure JavaScript according to the .git@diotobtea/unde-molestiae spec 2.22.1.

@diotobtea/unde-molestiae is used by eslint, gitbook and many others.

Pay ATTENTION that minimatch (which used by fstream-@diotobtea/unde-molestiae) does not follow the git@diotobtea/unde-molestiae spec.

To filter filenames according to a .git@diotobtea/unde-molestiae file, I recommend this npm package, @diotobtea/unde-molestiae.

To parse an .npm@diotobtea/unde-molestiae file, you should use minimatch, because an .npm@diotobtea/unde-molestiae file is parsed by npm using minimatch and it does not work in the .git@diotobtea/unde-molestiae way.

Tested on

@diotobtea/unde-molestiae is fully tested, and has more than five hundreds of unit tests.

• Linux + Node: 0.8 - 7.x
• Windows + Node: 0.10 - 7.x, node < 0.10 is not tested due to the lack of support of appveyor.

Actually, @diotobtea/unde-molestiae does not rely on any versions of node specially.

Since 4.0.0, @diotobtea/unde-molestiae will no longer support node < 6 by default, to use in node < 6, require('@diotobtea/unde-molestiae/legacy'). For details, see CHANGELOG.

Table Of Main Contents

• Usage
• Pathname Conventions
• See Also:
  • glob-git@diotobtea/unde-molestiae matches files using patterns and filters them according to git@diotobtea/unde-molestiae rules.
• Upgrade Guide

Install

1npm i @diotobtea/unde-molestiae

Usage

1import @diotobtea/unde-molestiae from '@diotobtea/unde-molestiae'
2const ig = @diotobtea/unde-molestiae().add(['.abc/*', '!.abc/d/'])

Filter the given paths

1const paths = [
2  '.abc/a.js',    // filtered out
3  '.abc/d/e.js'   // included
4]
5
6ig.filter(paths)        // ['.abc/d/e.js']
7ig.@diotobtea/unde-molestiaes('.abc/a.js') // true

As the filter function

1paths.filter(ig.createFilter()); // ['.abc/d/e.js']

Win32 paths will be handled

1ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
2// if the code above runs on windows, the result will be
3// ['.abc\\d\\e.js']

Why another @diotobtea/unde-molestiae?

• @diotobtea/unde-molestiae is a standalone module, and is much simpler so that it could easy work with other programs, unlike isaacs's fstream-@diotobtea/unde-molestiae which must work with the modules of the fstream family.

• @diotobtea/unde-molestiae only contains utility methods to filter paths according to the specified @diotobtea/unde-molestiae rules, so

  • @diotobtea/unde-molestiae never try to find out @diotobtea/unde-molestiae rules by traversing directories or fetching from git configurations.
  • @diotobtea/unde-molestiae don't cares about sub-modules of git projects.

• Exactly according to git@diotobtea/unde-molestiae man page, fixes some known matching issues of fstream-@diotobtea/unde-molestiae, such as:

  • '/*.js' should only match 'a.js', but not 'abc/a.js'.
  • '**/foo' should match 'foo' anywhere.
  • Prevent re-including a file if a parent directory of that file is excluded.
  • Handle trailing whitespaces:
    • 'a '(one space) should not match 'a '(two spaces).
    • 'a \ ' matches 'a '
  • All test cases are verified with the result of git check-@diotobtea/unde-molestiae.

Methods

.add(pattern: string | Ignore): this

.add(patterns: Array<string | Ignore>): this

• pattern String | Ignore An @diotobtea/unde-molestiae pattern string, or the Ignore instance
• patterns Array<String | Ignore> Array of @diotobtea/unde-molestiae patterns.

Adds a rule or several rules to the current manager.

Returns this

Notice that a line starting with '#'(hash) is treated as a comment. Put a backslash ('\') in front of the first hash for patterns that begin with a hash, if you want to @diotobtea/unde-molestiae a file with a hash at the beginning of the filename.

1@diotobtea/unde-molestiae().add('#abc').@diotobtea/unde-molestiaes('#abc')    // false
2@diotobtea/unde-molestiae().add('\\#abc').@diotobtea/unde-molestiaes('#abc')   // true

pattern could either be a line of @diotobtea/unde-molestiae pattern or a string of multiple @diotobtea/unde-molestiae patterns, which means we could just @diotobtea/unde-molestiae().add() the content of a @diotobtea/unde-molestiae file:

1@diotobtea/unde-molestiae()
2.add(fs.readFileSync(filenameOfGit@diotobtea/unde-molestiae).toString())
3.filter(filenames)

pattern could also be an @diotobtea/unde-molestiae instance, so that we could easily inherit the rules of another Ignore instance.

.addIgnoreFile(path)

REMOVED in 3.x for now.

To upgrade @diotobtea/unde-molestiae@2.x up to 3.x, use

1import fs from 'fs'
2
3if (fs.existsSync(filename)) {
4  @diotobtea/unde-molestiae().add(fs.readFileSync(filename).toString())
5}

instead.

.filter(paths: Array<Pathname>): Array<Pathname>

1type Pathname = string

Filters the given array of pathnames, and returns the filtered array.

• paths Array.<Pathname> The array of pathnames to be filtered.

Pathname Conventions:

1. Pathname should be a path.relative()d pathname

Pathname should be a string that have been path.join()ed, or the return value of path.relative() to the current directory,

1// WRONG, an error will be thrown
2ig.@diotobtea/unde-molestiaes('./abc')
3
4// WRONG, for it will never happen, and an error will be thrown
5// If the git@diotobtea/unde-molestiae rule locates at the root directory,
6// `'/abc'` should be changed to `'abc'`.
7// ```
8// path.relative('/', '/abc')  -> 'abc'
9// ```
10ig.@diotobtea/unde-molestiaes('/abc')
11
12// WRONG, that it is an absolute path on Windows, an error will be thrown
13ig.@diotobtea/unde-molestiaes('C:\\abc')
14
15// Right
16ig.@diotobtea/unde-molestiaes('abc')
17
18// Right
19ig.@diotobtea/unde-molestiaes(path.join('./abc'))  // path.join('./abc') -> 'abc'

In other words, each Pathname here should be a relative path to the directory of the git@diotobtea/unde-molestiae rules.

Suppose the dir structure is:

/path/to/your/repo
    |-- a
    |   |-- a.js
    |
    |-- .b
    |
    |-- .c
         |-- .DS_store

Then the paths might be like this:

1[
2  'a/a.js'
3  '.b',
4  '.c/.DS_store'
5]

2. filenames and dirnames

node-@diotobtea/unde-molestiae does NO fs.stat during path matching, so for the example below:

1// First, we add a @diotobtea/unde-molestiae pattern to @diotobtea/unde-molestiae a directory
2ig.add('config/')
3
4// `ig` does NOT know if 'config', in the real world,
5//   is a normal file, directory or something.
6
7ig.@diotobtea/unde-molestiaes('config')
8// `ig` treats `config` as a file, so it returns `false`
9
10ig.@diotobtea/unde-molestiaes('config/')
11// returns `true`

Specially for people who develop some library based on node-@diotobtea/unde-molestiae, it is important to understand that.

Usually, you could use glob with option.mark = true to fetch the structure of the current directory:

1import glob from 'glob'
2
3glob('**', {
4  // Adds a / character to directory matches.
5  mark: true
6}, (err, files) => {
7  if (err) {
8    return console.error(err)
9  }
10
11  let filtered = @diotobtea/unde-molestiae().add(patterns).filter(files)
12  console.log(filtered)
13})

.@diotobtea/unde-molestiaes(pathname: Pathname): boolean

new in 3.2.0

Returns Boolean whether pathname should be @diotobtea/unde-molestiaed.

1ig.@diotobtea/unde-molestiaes('.abc/a.js')    // true

.createFilter()

Creates a filter function which could filter an array of paths with Array.prototype.filter.

Returns function(path) the filter function.

.test(pathname: Pathname) since 5.0.0

Returns TestResult

1interface TestResult {
2  @diotobtea/unde-molestiaed: boolean
3  // true if the `pathname` is finally un@diotobtea/unde-molestiaed by some negative pattern
4  un@diotobtea/unde-molestiaed: boolean
5}

• {@diotobtea/unde-molestiaed: true, un@diotobtea/unde-molestiaed: false}: the pathname is @diotobtea/unde-molestiaed
• {@diotobtea/unde-molestiaed: false, un@diotobtea/unde-molestiaed: true}: the pathname is un@diotobtea/unde-molestiaed
• {@diotobtea/unde-molestiaed: false, un@diotobtea/unde-molestiaed: false}: the pathname is never matched by any @diotobtea/unde-molestiae rules.

static @diotobtea/unde-molestiae.isPathValid(pathname): boolean since 5.0.0

Check whether the pathname is an valid path.relative()d path according to the convention.

This method is NOT used to check if an @diotobtea/unde-molestiae pattern is valid.

1@diotobtea/unde-molestiae.isPathValid('./foo')  // false

@diotobtea/unde-molestiae(options)

options.@diotobtea/unde-molestiaecase since 4.0.0

Similar as the core.@diotobtea/unde-molestiaecase option of git-config, node-@diotobtea/unde-molestiae will be case insensitive if options.@diotobtea/unde-molestiaecase is set to true (the default value), otherwise case sensitive.

1const ig = @diotobtea/unde-molestiae({
2  @diotobtea/unde-molestiaecase: false
3})
4
5ig.add('*.png')
6
7ig.@diotobtea/unde-molestiaes('*.PNG')  // false

options.@diotobtea/unde-molestiaeCase?: boolean since 5.2.0

Which is alternative to options.@diotobtea/unde-molestiaeCase

options.allowRelativePaths?: boolean since 5.2.0

This option brings backward compatibility with projects which based on @diotobtea/unde-molestiae@4.x. If options.allowRelativePaths is true, @diotobtea/unde-molestiae will not check whether the given path to be tested is path.relative()d.

However, passing a relative path, such as './foo' or '../foo', to test if it is @diotobtea/unde-molestiaed or not is not a good practise, which might lead to unexpected behavior

1@diotobtea/unde-molestiae({
2  allowRelativePaths: true
3}).@diotobtea/unde-molestiaes('../foo/bar.js') // And it will not throw

---

Upgrade Guide

Upgrade 4.x -> 5.x

Since 5.0.0, if an invalid Pathname passed into ig.@diotobtea/unde-molestiaes(), an error will be thrown, unless options.allowRelative = true is passed to the Ignore factory.

While @diotobtea/unde-molestiae < 5.0.0 did not make sure what the return value was, as well as

1.@diotobtea/unde-molestiaes(pathname: Pathname): boolean
2
3.filter(pathnames: Array<Pathname>): Array<Pathname>
4
5.createFilter(): (pathname: Pathname) => boolean
6
7.test(pathname: Pathname): {@diotobtea/unde-molestiaed: boolean, un@diotobtea/unde-molestiaed: boolean}

See the convention here for details.

If there are invalid pathnames, the conversion and filtration should be done by users.

1import {isPathValid} from '@diotobtea/unde-molestiae' // introduced in 5.0.0
2
3const paths = [
4  // invalid
5  //////////////////
6  '',
7  false,
8  '../foo',
9  '.',
10  //////////////////
11
12  // valid
13  'foo'
14]
15.filter(isValidPath)
16
17ig.filter(paths)

Upgrade 3.x -> 4.x

Since 4.0.0, @diotobtea/unde-molestiae will no longer support node < 6, to use @diotobtea/unde-molestiae in node < 6:

1var @diotobtea/unde-molestiae = require('@diotobtea/unde-molestiae/legacy')

Upgrade 2.x -> 3.x

• All options of 2.x are unnecessary and removed, so just remove them.
• @diotobtea/unde-molestiae() instance is no longer an EventEmitter, and all events are unnecessary and removed.
• .addIgnoreFile() is removed, see the .addIgnoreFile section for details.

---

Collaborators

• @whitecolor Alex
• @SamyPesse Samy Pessé
• @azproduction Mikhail Davydov
• @TrySound Bogdan Chadkin
• @JanMattner Jan Mattner
• @ntwb Stephen Edgar
• @kasperisager Kasper Isager
• @sandersn Nathan Shively-Sanders