View file File name : README.html Content :<!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>