Index of /wp-content/ac/root/usr/share/doc/node-ignore
Name Last modified Size Description
Parent Directory -
README.txt.gz 2021-12-21 05:02 3.7K
TODO.Debian 2020-05-08 23:39 157
changelog.Debian.gz 2021-12-21 05:02 910
copyright 2021-10-09 06:15 1.7K
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>README</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
</head>
<body>
<h1 id="ignore">ignore</h1>
<p><code>ignore</code> is a manager, filter and parser which implemented in pure JavaScript according to the <a href="http://git-scm.com/docs/gitignore">.gitignore spec 2.22.1</a>.</p>
<p><code>ignore</code> is used by eslint, gitbook and <a href="https://www.npmjs.com/browse/depended/ignore">many others</a>.</p>
<p>Pay <strong>ATTENTION</strong> that <a href="https://www.npmjs.org/package/minimatch"><code>minimatch</code></a> (which used by <code>fstream-ignore</code>) does not follow the gitignore spec.</p>
<p>To filter filenames according to a .gitignore file, I recommend this npm package, <code>ignore</code>.</p>
<p>To parse an <code>.npmignore</code> file, you should use <code>minimatch</code>, because an <code>.npmignore</code> file is parsed by npm using <code>minimatch</code> and it does not work in the .gitignore way.</p>
<h3 id="tested-on">Tested on</h3>
<p><code>ignore</code> is fully tested, and has more than <strong>five hundreds</strong> of unit tests.</p>
<ul>
<li>Linux + Node: <code>0.8</code> - <code>7.x</code></li>
<li>Windows + Node: <code>0.10</code> - <code>7.x</code>, node < <code>0.10</code> is not tested due to the lack of support of appveyor.</li>
</ul>
<p>Actually, <code>ignore</code> does not rely on any versions of node specially.</p>
<p>Since <code>4.0.0</code>, ignore will no longer support <code>node < 6</code> by default, to use in node < 6, <code>require('ignore/legacy')</code>. For details, see <a href="https://github.com/kaelzhang/node-ignore/blob/master/CHANGELOG.md">CHANGELOG</a>.</p>
<h2 id="table-of-main-contents">Table Of Main Contents</h2>
<ul>
<li><a href="#usage">Usage</a></li>
<li><a href="#pathname-conventions"><code>Pathname</code> Conventions</a></li>
<li>See Also:
<ul>
<li><a href="https://www.npmjs.com/package/glob-gitignore"><code>glob-gitignore</code></a> matches files using patterns and filters them according to gitignore rules.</li>
</ul></li>
<li><a href="#upgrade-guide">Upgrade Guide</a></li>
</ul>
<h2 id="install">Install</h2>
<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true"></a><span class="ex">npm</span> i ignore</span></code></pre></div>
<h2 id="usage">Usage</h2>
<div class="sourceCode" id="cb2"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true"></a><span class="im">import</span> ignore <span class="im">from</span> <span class="st">'ignore'</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true"></a><span class="kw">const</span> ig <span class="op">=</span> <span class="fu">ignore</span>()<span class="op">.</span><span class="fu">add</span>([<span class="st">'.abc/*'</span><span class="op">,</span> <span class="st">'!.abc/d/'</span>])</span></code></pre></div>
<h3 id="filter-the-given-paths">Filter the given paths</h3>
<div class="sourceCode" id="cb3"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true"></a><span class="kw">const</span> paths <span class="op">=</span> [</span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true"></a> <span class="st">'.abc/a.js'</span><span class="op">,</span> <span class="co">// filtered out</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true"></a> <span class="st">'.abc/d/e.js'</span> <span class="co">// included</span></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true"></a>]</span>
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true"></a></span>
<span id="cb3-6"><a href="#cb3-6" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">filter</span>(paths) <span class="co">// ['.abc/d/e.js']</span></span>
<span id="cb3-7"><a href="#cb3-7" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'.abc/a.js'</span>) <span class="co">// true</span></span></code></pre></div>
<h3 id="as-the-filter-function">As the filter function</h3>
<div class="sourceCode" id="cb4"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true"></a>paths<span class="op">.</span><span class="fu">filter</span>(ig<span class="op">.</span><span class="fu">createFilter</span>())<span class="op">;</span> <span class="co">// ['.abc/d/e.js']</span></span></code></pre></div>
<h3 id="win32-paths-will-be-handled">Win32 paths will be handled</h3>
<div class="sourceCode" id="cb5"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">filter</span>([<span class="st">'.abc</span><span class="sc">\\</span><span class="st">a.js'</span><span class="op">,</span> <span class="st">'.abc</span><span class="sc">\\</span><span class="st">d</span><span class="sc">\\</span><span class="st">e.js'</span>])</span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true"></a><span class="co">// if the code above runs on windows, the result will be</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true"></a><span class="co">// ['.abc\\d\\e.js']</span></span></code></pre></div>
<h2 id="why-another-ignore">Why another ignore?</h2>
<ul>
<li><p><code>ignore</code> is a standalone module, and is much simpler so that it could easy work with other programs, unlike <a href="https://npmjs.org/~isaacs">isaacs</a>'s <a href="https://npmjs.org/package/fstream-ignore">fstream-ignore</a> which must work with the modules of the fstream family.</p></li>
<li><p><code>ignore</code> only contains utility methods to filter paths according to the specified ignore rules, so</p>
<ul>
<li><code>ignore</code> never try to find out ignore rules by traversing directories or fetching from git configurations.</li>
<li><code>ignore</code> don't cares about sub-modules of git projects.</li>
</ul></li>
<li><p>Exactly according to <a href="http://git-scm.com/docs/gitignore">gitignore man page</a>, fixes some known matching issues of fstream-ignore, such as:</p>
<ul>
<li>'<code>/*.js</code>' should only match '<code>a.js</code>', but not '<code>abc/a.js</code>'.</li>
<li>'<code>**/foo</code>' should match '<code>foo</code>' anywhere.</li>
<li>Prevent re-including a file if a parent directory of that file is excluded.</li>
<li>Handle trailing whitespaces:
<ul>
<li><code>'a '</code>(one space) should not match <code>'a '</code>(two spaces).</li>
<li><code>'a \ '</code> matches <code>'a '</code></li>
</ul></li>
<li>All test cases are verified with the result of <code>git check-ignore</code>.</li>
</ul></li>
</ul>
<h1 id="methods">Methods</h1>
<h2 id="addpattern-string--ignore-this">.add(pattern: string | Ignore): this</h2>
<h2 id="addpatterns-arraystring--ignore-this">.add(patterns: Array<string | Ignore>): this</h2>
<ul>
<li><strong>pattern</strong> <code>String | Ignore</code> An ignore pattern string, or the <code>Ignore</code> instance</li>
<li><strong>patterns</strong> <code>Array<String | Ignore></code> Array of ignore patterns.</li>
</ul>
<p>Adds a rule or several rules to the current manager.</p>
<p>Returns <code>this</code></p>
<p>Notice that a line starting with <code>'#'</code>(hash) is treated as a comment. Put a backslash (<code>'\'</code>) in front of the first hash for patterns that begin with a hash, if you want to ignore a file with a hash at the beginning of the filename.</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true"></a><span class="fu">ignore</span>()<span class="op">.</span><span class="fu">add</span>(<span class="st">'#abc'</span>)<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'#abc'</span>) <span class="co">// false</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true"></a><span class="fu">ignore</span>()<span class="op">.</span><span class="fu">add</span>(<span class="st">'</span><span class="sc">\#</span><span class="st">abc'</span>)<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'#abc'</span>) <span class="co">// true</span></span></code></pre></div>
<p><code>pattern</code> could either be a line of ignore pattern or a string of multiple ignore patterns, which means we could just <code>ignore().add()</code> the content of a ignore file:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true"></a><span class="fu">ignore</span>()</span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true"></a><span class="op">.</span><span class="fu">add</span>(fs<span class="op">.</span><span class="fu">readFileSync</span>(filenameOfGitignore)<span class="op">.</span><span class="fu">toString</span>())</span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true"></a><span class="op">.</span><span class="fu">filter</span>(filenames)</span></code></pre></div>
<p><code>pattern</code> could also be an <code>ignore</code> instance, so that we could easily inherit the rules of another <code>Ignore</code> instance.</p>
<h2 id="addignorefilepath">.addIgnoreFile(path)</h2>
<p>REMOVED in <code>3.x</code> for now.</p>
<p>To upgrade <code>ignore@2.x</code> up to <code>3.x</code>, use</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true"></a><span class="im">import</span> fs <span class="im">from</span> <span class="st">'fs'</span></span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true"></a></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true"></a><span class="cf">if</span> (fs<span class="op">.</span><span class="fu">existsSync</span>(filename)) {</span>
<span id="cb8-4"><a href="#cb8-4" aria-hidden="true"></a> <span class="fu">ignore</span>()<span class="op">.</span><span class="fu">add</span>(fs<span class="op">.</span><span class="fu">readFileSync</span>(filename)<span class="op">.</span><span class="fu">toString</span>())</span>
<span id="cb8-5"><a href="#cb8-5" aria-hidden="true"></a>}</span></code></pre></div>
<p>instead.</p>
<h2 id="filterpaths-arraypathname-arraypathname">.filter(paths: Array<Pathname>): Array<Pathname></h2>
<div class="sourceCode" id="cb9"><pre class="sourceCode ts"><code class="sourceCode typescript"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true"></a><span class="kw">type</span> Pathname <span class="op">=</span> <span class="dt">string</span></span></code></pre></div>
<p>Filters the given array of pathnames, and returns the filtered array.</p>
<ul>
<li><strong>paths</strong> <code>Array.<Pathname></code> The array of <code>pathname</code>s to be filtered.</li>
</ul>
<h3 id="pathname-conventions"><code>Pathname</code> Conventions:</h3>
<h4 id="1-pathname-should-be-a-pathrelatived-pathname">1. <code>Pathname</code> should be a <code>path.relative()</code>d pathname</h4>
<p><code>Pathname</code> should be a string that have been <code>path.join()</code>ed, or the return value of <code>path.relative()</code> to the current directory,</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true"></a><span class="co">// WRONG, an error will be thrown</span></span>
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'./abc'</span>)</span>
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true"></a></span>
<span id="cb10-4"><a href="#cb10-4" aria-hidden="true"></a><span class="co">// WRONG, for it will never happen, and an error will be thrown</span></span>
<span id="cb10-5"><a href="#cb10-5" aria-hidden="true"></a><span class="co">// If the gitignore rule locates at the root directory,</span></span>
<span id="cb10-6"><a href="#cb10-6" aria-hidden="true"></a><span class="co">// `'/abc'` should be changed to `'abc'`.</span></span>
<span id="cb10-7"><a href="#cb10-7" aria-hidden="true"></a><span class="co">// ```</span></span>
<span id="cb10-8"><a href="#cb10-8" aria-hidden="true"></a><span class="co">// path.relative('/', '/abc') -> 'abc'</span></span>
<span id="cb10-9"><a href="#cb10-9" aria-hidden="true"></a><span class="co">// ```</span></span>
<span id="cb10-10"><a href="#cb10-10" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'/abc'</span>)</span>
<span id="cb10-11"><a href="#cb10-11" aria-hidden="true"></a></span>
<span id="cb10-12"><a href="#cb10-12" aria-hidden="true"></a><span class="co">// WRONG, that it is an absolute path on Windows, an error will be thrown</span></span>
<span id="cb10-13"><a href="#cb10-13" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'C:</span><span class="sc">\\</span><span class="st">abc'</span>)</span>
<span id="cb10-14"><a href="#cb10-14" aria-hidden="true"></a></span>
<span id="cb10-15"><a href="#cb10-15" aria-hidden="true"></a><span class="co">// Right</span></span>
<span id="cb10-16"><a href="#cb10-16" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'abc'</span>)</span>
<span id="cb10-17"><a href="#cb10-17" aria-hidden="true"></a></span>
<span id="cb10-18"><a href="#cb10-18" aria-hidden="true"></a><span class="co">// Right</span></span>
<span id="cb10-19"><a href="#cb10-19" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(path<span class="op">.</span><span class="fu">join</span>(<span class="st">'./abc'</span>)) <span class="co">// path.join('./abc') -> 'abc'</span></span></code></pre></div>
<p>In other words, each <code>Pathname</code> here should be a relative path to the directory of the gitignore rules.</p>
<p>Suppose the dir structure is:</p>
<pre><code>/path/to/your/repo
|-- a
| |-- a.js
|
|-- .b
|
|-- .c
|-- .DS_store
</code></pre>
<p>Then the <code>paths</code> might be like this:</p>
<div class="sourceCode" id="cb12"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true"></a>[</span>
<span id="cb12-2"><a href="#cb12-2" aria-hidden="true"></a> <span class="st">'a/a.js'</span></span>
<span id="cb12-3"><a href="#cb12-3" aria-hidden="true"></a> <span class="st">'.b'</span><span class="op">,</span></span>
<span id="cb12-4"><a href="#cb12-4" aria-hidden="true"></a> <span class="st">'.c/.DS_store'</span></span>
<span id="cb12-5"><a href="#cb12-5" aria-hidden="true"></a>]</span></code></pre></div>
<h4 id="2-filenames-and-dirnames">2. filenames and dirnames</h4>
<p><code>node-ignore</code> does NO <code>fs.stat</code> during path matching, so for the example below:</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true"></a><span class="co">// First, we add a ignore pattern to ignore a directory</span></span>
<span id="cb13-2"><a href="#cb13-2" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">add</span>(<span class="st">'config/'</span>)</span>
<span id="cb13-3"><a href="#cb13-3" aria-hidden="true"></a></span>
<span id="cb13-4"><a href="#cb13-4" aria-hidden="true"></a><span class="co">// `ig` does NOT know if 'config', in the real world,</span></span>
<span id="cb13-5"><a href="#cb13-5" aria-hidden="true"></a><span class="co">// is a normal file, directory or something.</span></span>
<span id="cb13-6"><a href="#cb13-6" aria-hidden="true"></a></span>
<span id="cb13-7"><a href="#cb13-7" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'config'</span>)</span>
<span id="cb13-8"><a href="#cb13-8" aria-hidden="true"></a><span class="co">// `ig` treats `config` as a file, so it returns `false`</span></span>
<span id="cb13-9"><a href="#cb13-9" aria-hidden="true"></a></span>
<span id="cb13-10"><a href="#cb13-10" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'config/'</span>)</span>
<span id="cb13-11"><a href="#cb13-11" aria-hidden="true"></a><span class="co">// returns `true`</span></span></code></pre></div>
<p>Specially for people who develop some library based on <code>node-ignore</code>, it is important to understand that.</p>
<p>Usually, you could use <a href="http://npmjs.org/package/glob"><code>glob</code></a> with <code>option.mark = true</code> to fetch the structure of the current directory:</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true"></a><span class="im">import</span> glob <span class="im">from</span> <span class="st">'glob'</span></span>
<span id="cb14-2"><a href="#cb14-2" aria-hidden="true"></a></span>
<span id="cb14-3"><a href="#cb14-3" aria-hidden="true"></a><span class="fu">glob</span>(<span class="st">'**'</span><span class="op">,</span> {</span>
<span id="cb14-4"><a href="#cb14-4" aria-hidden="true"></a> <span class="co">// Adds a / character to directory matches.</span></span>
<span id="cb14-5"><a href="#cb14-5" aria-hidden="true"></a> <span class="dt">mark</span><span class="op">:</span> <span class="kw">true</span></span>
<span id="cb14-6"><a href="#cb14-6" aria-hidden="true"></a>}<span class="op">,</span> (err<span class="op">,</span> files) <span class="kw">=></span> {</span>
<span id="cb14-7"><a href="#cb14-7" aria-hidden="true"></a> <span class="cf">if</span> (err) {</span>
<span id="cb14-8"><a href="#cb14-8" aria-hidden="true"></a> <span class="cf">return</span> <span class="bu">console</span><span class="op">.</span><span class="fu">error</span>(err)</span>
<span id="cb14-9"><a href="#cb14-9" aria-hidden="true"></a> }</span>
<span id="cb14-10"><a href="#cb14-10" aria-hidden="true"></a></span>
<span id="cb14-11"><a href="#cb14-11" aria-hidden="true"></a> <span class="kw">let</span> filtered <span class="op">=</span> <span class="fu">ignore</span>()<span class="op">.</span><span class="fu">add</span>(patterns)<span class="op">.</span><span class="fu">filter</span>(files)</span>
<span id="cb14-12"><a href="#cb14-12" aria-hidden="true"></a> <span class="bu">console</span><span class="op">.</span><span class="fu">log</span>(filtered)</span>
<span id="cb14-13"><a href="#cb14-13" aria-hidden="true"></a>})</span></code></pre></div>
<h2 id="ignorespathname-pathname-boolean">.ignores(pathname: Pathname): boolean</h2>
<blockquote>
<p>new in 3.2.0</p>
</blockquote>
<p>Returns <code>Boolean</code> whether <code>pathname</code> should be ignored.</p>
<div class="sourceCode" id="cb15"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'.abc/a.js'</span>) <span class="co">// true</span></span></code></pre></div>
<h2 id="createfilter">.createFilter()</h2>
<p>Creates a filter function which could filter an array of paths with <code>Array.prototype.filter</code>.</p>
<p>Returns <code>function(path)</code> the filter function.</p>
<h2 id="testpathname-pathname-since-500">.test(pathname: Pathname) since 5.0.0</h2>
<p>Returns <code>TestResult</code></p>
<div class="sourceCode" id="cb16"><pre class="sourceCode ts"><code class="sourceCode typescript"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true"></a>interface TestResult {</span>
<span id="cb16-2"><a href="#cb16-2" aria-hidden="true"></a> ignored<span class="op">:</span> <span class="dt">boolean</span></span>
<span id="cb16-3"><a href="#cb16-3" aria-hidden="true"></a> <span class="co">// true if the `pathname` is finally unignored by some negative pattern</span></span>
<span id="cb16-4"><a href="#cb16-4" aria-hidden="true"></a> unignored<span class="op">:</span> <span class="dt">boolean</span></span>
<span id="cb16-5"><a href="#cb16-5" aria-hidden="true"></a>}</span></code></pre></div>
<ul>
<li><code>{ignored: true, unignored: false}</code>: the <code>pathname</code> is ignored</li>
<li><code>{ignored: false, unignored: true}</code>: the <code>pathname</code> is unignored</li>
<li><code>{ignored: false, unignored: false}</code>: the <code>pathname</code> is never matched by any ignore rules.</li>
</ul>
<h2 id="static-ignoreispathvalidpathname-boolean-since-500">static <code>ignore.isPathValid(pathname): boolean</code> since 5.0.0</h2>
<p>Check whether the <code>pathname</code> is an valid <code>path.relative()</code>d path according to the <a href="#1-pathname-should-be-a-pathrelatived-pathname">convention</a>.</p>
<p>This method is <strong>NOT</strong> used to check if an ignore pattern is valid.</p>
<div class="sourceCode" id="cb17"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true"></a>ignore<span class="op">.</span><span class="fu">isPathValid</span>(<span class="st">'./foo'</span>) <span class="co">// false</span></span></code></pre></div>
<h2 id="ignoreoptions">ignore(options)</h2>
<h3 id="optionsignorecase-since-400"><code>options.ignorecase</code> since 4.0.0</h3>
<p>Similar as the <code>core.ignorecase</code> option of <a href="https://git-scm.com/docs/git-config">git-config</a>, <code>node-ignore</code> will be case insensitive if <code>options.ignorecase</code> is set to <code>true</code> (the default value), otherwise case sensitive.</p>
<div class="sourceCode" id="cb18"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true"></a><span class="kw">const</span> ig <span class="op">=</span> <span class="fu">ignore</span>({</span>
<span id="cb18-2"><a href="#cb18-2" aria-hidden="true"></a> <span class="dt">ignorecase</span><span class="op">:</span> <span class="kw">false</span></span>
<span id="cb18-3"><a href="#cb18-3" aria-hidden="true"></a>})</span>
<span id="cb18-4"><a href="#cb18-4" aria-hidden="true"></a></span>
<span id="cb18-5"><a href="#cb18-5" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">add</span>(<span class="st">'*.png'</span>)</span>
<span id="cb18-6"><a href="#cb18-6" aria-hidden="true"></a></span>
<span id="cb18-7"><a href="#cb18-7" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'*.PNG'</span>) <span class="co">// false</span></span></code></pre></div>
<h3 id="optionsignorecase-boolean-since-520"><code>options.ignoreCase?: boolean</code> since 5.2.0</h3>
<p>Which is alternative to <code>options.ignoreCase</code></p>
<h3 id="optionsallowrelativepaths-boolean-since-520"><code>options.allowRelativePaths?: boolean</code> since 5.2.0</h3>
<p>This option brings backward compatibility with projects which based on <code>ignore@4.x</code>. If <code>options.allowRelativePaths</code> is <code>true</code>, <code>ignore</code> will not check whether the given path to be tested is <a href="#pathname-conventions"><code>path.relative()</code>d</a>.</p>
<p>However, passing a relative path, such as <code>'./foo'</code> or <code>'../foo'</code>, to test if it is ignored or not is not a good practise, which might lead to unexpected behavior</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true"></a><span class="fu">ignore</span>({</span>
<span id="cb19-2"><a href="#cb19-2" aria-hidden="true"></a> <span class="dt">allowRelativePaths</span><span class="op">:</span> <span class="kw">true</span></span>
<span id="cb19-3"><a href="#cb19-3" aria-hidden="true"></a>})<span class="op">.</span><span class="fu">ignores</span>(<span class="st">'../foo/bar.js'</span>) <span class="co">// And it will not throw</span></span></code></pre></div>
<hr />
<h1 id="upgrade-guide">Upgrade Guide</h1>
<h2 id="upgrade-4x---5x">Upgrade 4.x -> 5.x</h2>
<p>Since <code>5.0.0</code>, if an invalid <code>Pathname</code> passed into <code>ig.ignores()</code>, an error will be thrown, unless <code>options.allowRelative = true</code> is passed to the <code>Ignore</code> factory.</p>
<p>While <code>ignore < 5.0.0</code> did not make sure what the return value was, as well as</p>
<div class="sourceCode" id="cb20"><pre class="sourceCode ts"><code class="sourceCode typescript"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true"></a><span class="op">.</span><span class="fu">ignores</span>(pathname<span class="op">:</span> Pathname)<span class="op">:</span> <span class="dt">boolean</span></span>
<span id="cb20-2"><a href="#cb20-2" aria-hidden="true"></a></span>
<span id="cb20-3"><a href="#cb20-3" aria-hidden="true"></a><span class="op">.</span><span class="fu">filter</span>(pathnames<span class="op">:</span> Array<span class="op"><</span>Pathname<span class="op">></span>)<span class="op">:</span> Array<span class="op"><</span>Pathname<span class="op">></span></span>
<span id="cb20-4"><a href="#cb20-4" aria-hidden="true"></a></span>
<span id="cb20-5"><a href="#cb20-5" aria-hidden="true"></a><span class="op">.</span><span class="fu">createFilter</span>()<span class="op">:</span> (pathname<span class="op">:</span> Pathname) <span class="kw">=></span> <span class="dt">boolean</span></span>
<span id="cb20-6"><a href="#cb20-6" aria-hidden="true"></a></span>
<span id="cb20-7"><a href="#cb20-7" aria-hidden="true"></a><span class="op">.</span><span class="fu">test</span>(pathname<span class="op">:</span> Pathname)<span class="op">:</span> {ignored<span class="op">:</span> <span class="dt">boolean</span><span class="op">,</span> unignored<span class="op">:</span> <span class="dt">boolean</span>}</span></code></pre></div>
<p>See the convention <a href="#1-pathname-should-be-a-pathrelatived-pathname">here</a> for details.</p>
<p>If there are invalid pathnames, the conversion and filtration should be done by users.</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true"></a><span class="im">import</span> {isPathValid} <span class="im">from</span> <span class="st">'ignore'</span> <span class="co">// introduced in 5.0.0</span></span>
<span id="cb21-2"><a href="#cb21-2" aria-hidden="true"></a></span>
<span id="cb21-3"><a href="#cb21-3" aria-hidden="true"></a><span class="kw">const</span> paths <span class="op">=</span> [</span>
<span id="cb21-4"><a href="#cb21-4" aria-hidden="true"></a> <span class="co">// invalid</span></span>
<span id="cb21-5"><a href="#cb21-5" aria-hidden="true"></a> <span class="co">//////////////////</span></span>
<span id="cb21-6"><a href="#cb21-6" aria-hidden="true"></a> <span class="st">''</span><span class="op">,</span></span>
<span id="cb21-7"><a href="#cb21-7" aria-hidden="true"></a> <span class="kw">false</span><span class="op">,</span></span>
<span id="cb21-8"><a href="#cb21-8" aria-hidden="true"></a> <span class="st">'../foo'</span><span class="op">,</span></span>
<span id="cb21-9"><a href="#cb21-9" aria-hidden="true"></a> <span class="st">'.'</span><span class="op">,</span></span>
<span id="cb21-10"><a href="#cb21-10" aria-hidden="true"></a> <span class="co">//////////////////</span></span>
<span id="cb21-11"><a href="#cb21-11" aria-hidden="true"></a></span>
<span id="cb21-12"><a href="#cb21-12" aria-hidden="true"></a> <span class="co">// valid</span></span>
<span id="cb21-13"><a href="#cb21-13" aria-hidden="true"></a> <span class="st">'foo'</span></span>
<span id="cb21-14"><a href="#cb21-14" aria-hidden="true"></a>]</span>
<span id="cb21-15"><a href="#cb21-15" aria-hidden="true"></a><span class="op">.</span><span class="fu">filter</span>(isValidPath)</span>
<span id="cb21-16"><a href="#cb21-16" aria-hidden="true"></a></span>
<span id="cb21-17"><a href="#cb21-17" aria-hidden="true"></a>ig<span class="op">.</span><span class="fu">filter</span>(paths)</span></code></pre></div>
<h2 id="upgrade-3x---4x">Upgrade 3.x -> 4.x</h2>
<p>Since <code>4.0.0</code>, <code>ignore</code> will no longer support node < 6, to use <code>ignore</code> in node < 6:</p>
<div class="sourceCode" id="cb22"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true"></a><span class="kw">var</span> ignore <span class="op">=</span> <span class="pp">require</span>(<span class="st">'ignore/legacy'</span>)</span></code></pre></div>
<h2 id="upgrade-2x---3x">Upgrade 2.x -> 3.x</h2>
<ul>
<li>All <code>options</code> of 2.x are unnecessary and removed, so just remove them.</li>
<li><code>ignore()</code> instance is no longer an <a href="nodejs.org/api/events.html"><code>EventEmitter</code></a>, and all events are unnecessary and removed.</li>
<li><code>.addIgnoreFile()</code> is removed, see the <a href="#addignorefilepath">.addIgnoreFile</a> section for details.</li>
</ul>
<hr />
<h1 id="collaborators">Collaborators</h1>
<ul>
<li><a href="https://github.com/whitecolor">@whitecolor</a> <em>Alex</em></li>
<li><a href="https://github.com/SamyPesse">@SamyPesse</a> <em>Samy Pessé</em></li>
<li><a href="https://github.com/azproduction">@azproduction</a> <em>Mikhail Davydov</em></li>
<li><a href="https://github.com/TrySound">@TrySound</a> <em>Bogdan Chadkin</em></li>
<li><a href="https://github.com/JanMattner">@JanMattner</a> <em>Jan Mattner</em></li>
<li><a href="https://github.com/ntwb">@ntwb</a> <em>Stephen Edgar</em></li>
<li><a href="https://github.com/kasperisager">@kasperisager</a> <em>Kasper Isager</em></li>
<li><a href="https://github.com/sandersn">@sandersn</a> <em>Nathan Shively-Sanders</em></li>
</ul>
</body>
</html>