madskristensen/WebEssentials2013 — pull request #1250 by am11 (2014-06-27 06:10:56+00:00)
Title: Feature: WEIgnore (#589)

Fixes #589, #638, #1241 and this [UserVoice ticket](http://webessentials.uservoice.com/forums/140520-general/suggestions/5341144-allow-less-files-to-be-ignored).

---

*The docs should go to http://www.github.com/madskristensen/vswebessentials.com/ which would eventually appear at http://www.vswebessentials.com/.*

---

# WEIgnore

WEIgnore, `.weignore`, is a file containing the list of linefeed-separated file-path patterns to prevent compilers and linters used in Web Essentials (WE). As per @nschonni's [kind suggestion](https://github.com/madskristensen/WebEssentials2013/issues/603#issuecomment-34477078) and @SLaks' cool [Minimatch](http://github.com/slaks/minimatch) utility -- a port of Nodejs' minimatch; it supports both Unix-like and Windows-like file paths.

That said, it support all styles supported by `.jshintignore`.

**Limitations:**

Currently it only targets nodejs pipeline services, meaning TypeScript compilation (*not TSLint*) and Markdown are out. For markdown, we would probably shift to nodejs-based [marked](https://github.com/chjj/marked/) compiler, once [this feature](https://github.com/chjj/marked/issues/382) is implemented.

**Discoverability:**

It works just like `.jscs`,`.jshintrc`, `coffee.json`, `coffeelint.js` and `tslint.json`. For each request, it looks for `.weignore` file in the current directory, then its parent till the drive's root. After that it will look into user's HOME directory (`c:\users\`).

**How it works:**

The first file that is found in the aforementioned chain takes effect on the existing file. All the file-path patterns inside the `.weignore` file are relative to the source file being processed, *not the `.weignore` file itself*.

**Basic Usage:**

* To ignore file path including the word "style":

```text
**/**style**
```

* To ignore path with `.min.js` at the end:

```text
**/**.min.js
```

* To ignore file path including the folder name "slug":

```text
**\slug\**
```

or:

```text
**/slug/**
```

* To ignore the absolute path:

```text
C:\temp\foo.ts
```

Or:

```text
C:/temp/foo.ts
```

**Intermediate Complexity:**

* To negate the ignore, use `!` before the path:

```text
!**/**Content
```

* To ignore the file from any kind of compilation (*only*), specify the term "compiler" after the pattern, separated by TAB:

```text
**/doodle.less	compiler
```

**Note:** The space between `doodle.less` and `compiler` is a TAB `\t`. Although TAB is [not the disallowed character](http://en.wikipedia.org/wiki/Filename#Comparison_of_filename_limitations) in any major file-system, but it's extremely obscure in usage -- hence the best candidate of our separator. If you have files with TAB anywhere file path, you are out of luck! :(

* To ignore the file from being processed by LESS compiler, use the word `less`:

```text
**/doodle.less	less
```

* To ignore the file from being processed by Autoprefixer, use the word `autoprefixer`:

```text
**/bug.scss	autoprefixer
```

* To ignore the file from being processed by a linter, use the word `linter`:

```text
**/*.js	linter
```

* You can also specify a linter's name:

```text
**/random.js	jscs
```

* If there a case which requires specifying multiple service names, use comma-separated list:

```text
**/doodle.less	less, autoprefixer
```

Here is the list of all the (node-based) compilers and linters currently supported by WE:

* compiler
* autoprefixer
* coffeescript
* icedcoffeescript
* less
* livescript
* scss
* sweetjs
* linter
* jscs
* jshint
* tslint

The parent list items are referred as service-categories and sub-list contains service-names.

**Advanced Usage (going crazy):**

You can have negation for service type and service names as well!

```text
**/doodle.less	!less, autoprefixer
```

It will only ignore autoprefixer.

```text
!**/*.coffee	!coffeescript
```

But this will *not* ignore coffeescript compilation, because the negation of pattern will take precedence. We can implement this logic, if its really desired. Meanwhile its recommended to keep your logic simplified (see this Wolfarm|Alpha's [logic expression simplifier](http://www.wolframalpha.com/widget/widgetPopup.jsp?p=v&id=4c86f3bbcab249f879058d1825887571&title=Boolean%20Algebra%20Calculator&theme=green)).

**Precedence:**

As describe above, it first skip the negative patterns `!patterns` to be ignored.

Then it looks for service-category or service-name. If none is found, it tests the pattern match.

If there was tab-separated service category/name mentioned on the line, before matching the pattern, it checks if the caller service needs to be ignored and skips if not.