include-exclude-precedence

include-exclude-precedence.md

Include/exclude precedence in lint-like tools

Ad hoc research for deciding how to implement file inclusion/exclusion logic in elm-doc.

Notes:

• Listed up lint-like tools I know off the top of my head, and then supplemented by cherry-picking tools from awesome-static-analysis
• "Included" here means explicitly included by being specified in the command line, not just in a config file.
• I either tried out each tool to see how it actually behaves, or looked at existing issues or actual code.
• Numbers
  • Total number of tools covered: 12
  • Excludes takes precedence over includes: 7
  • Includes takes precedence over excludes: 1
  • Can't exclude: 4
• As I was looking around, rsync and Python distutils stood out as having a different approach than those covered here: they allow specifying targets with multiple include/exclude directives, where order matters. If a tool is about operating on a large set of heterogenous files, this approach will provide the greatest flexibility.

Excludes take precedence over explicit includes

coala

★1,532 coala provides a unified command-line interface for linting and fixing all your code, regardless of the programming languages you use.

$ coala --version
0.11.0
$ coala -I --bears CSSLintBear --ignore test.css --files test.css
Executing section cli...
[WARNING][13:53:52] No files matching '/path/to/test.css' were found.

cpplint

★11,110 (repo holds styleguides for various languages, not just cpplint) This is automated checker to make sure a C++ file follows Google's C++ style guide.

$ pip freeze | grep cpplint
cpplint==1.3.0
$ cpplint --exclude test.cc test.cc
$ cpplint test.cc
test.cc:0:  No copyright message found.  You should have a line: "Copyright [year] <Copyright Owner>"  [legal/copyright] [5]
Done processing test.cc

csslint

★3,918 Automated linting of Cascading Stylesheets.

$ csslint --version
v1.0.4
$ csslint --exclude-list=test.css test.css
csslint: No files specified.

eslint [has option to override]

★8,711 A fully pluggable tool for identifying and reporting on patterns in JavaScript.

As of version 4.8.0:

0:0 warning File ignored because of your .eslintignore file. Use --no-ignore to override. https://eslint.org/docs/user-guide/configuring#ignored-file-warnings

jshint

★7,437 JSHint is a tool that helps to detect errors and potential problems in your JavaScript code.

$ jshint --version
jshint v2.9.5
$ echo 'console.log(GLOBAL)' > test.js
$ jshint --exclude test.js test.js
$ jshint test.js
test.js: line 1, col 20, Missing semicolon.

1 error

Relevant code line.

pycodestyle/pep8

★2,464 Simple Python style checker in one Python file.

As of version 2.3.1:

exclude wins over the commandline include of the directory PyCQA/pycodestyle#348

However, note that this is considered a bug, not a feature.

scss_lint

★2,863 Configurable tool for writing clean and consistent SCSS.

$ scss-lint --version
scss-lint 0.38.0
$ scss-lint --exclude test.css test.css
All files matched by the patterns [test.css] were excluded by the patterns: [/path/to/test.css]

Explicit include takes precedence over exclude

rubocop [has option to override]

--force-exclusion Force excluding files specified in the configuration Exclude even if they are explicitly passed as arguments. https://github.com/bbatsov/rubocop/blob/ae0d8cfe41f4dd035c6c1547157021ecf5e765c4/lib/rubocop/options.rb#L303

Can’t exclude

golint

★2,003 This is a linter for Go source code.

2017/10/01: Looking at golint.go, there doesn’t seem to have a way of excluding files.

hlint

★465 Haskell source code suggestions.

2017/10/01: There is an outstanding issue that asks for a way to exclude files and directories.

shellcheck

★8,897 ShellCheck, a static analysis tool for shell scripts.

As of 0.4.6: It doesn't seem to provide an option to exclude files or directories.

$ shellcheck --version
...
version: 0.4.6
...
$ shellcheck
No files specified.

Usage: shellcheck [OPTIONS...] FILES...
  -e CODE1,CODE2..  --exclude=CODE1,CODE2..  exclude types of warnings
  -f FORMAT         --format=FORMAT          output format
  -C[WHEN]          --color[=WHEN]           Use color (auto, always, never)
  -s SHELLNAME      --shell=SHELLNAME        Specify dialect (sh,bash,dash,ksh)
  -x                --external-sources       Allow 'source' outside of FILES.
  -V                --version                Print version information

credo

★2,116 A static code analysis tool for the Elixir language with a focus on code consistency and teaching.

2017/10/01: There is an outstanding issue that proposes to add an option to exclude files and directories.

Different approaches

Order of rules matters, and each rule adds or subtracts

Python distutils

The order of commands in the manifest template matters: initially, we have the list of default files as described above, and each command in the template adds to or removes from that list of files. https://docs.python.org/3/distutils/sourcedist.html#specifying-the-files-to-distribute

Order of rules matters, and first match wins

rsync

As the list of files/directories to transfer is built, rsync checks each name to be transferred against the list of include/exclude patterns in turn, and the first matching pattern is acted on: if it is an exclude pattern, then that file is skipped; if it is an include pattern then that filename is not skipped; if no matching pattern is found, then the filename is not skipped. https://download.samba.org/pub/rsync/rsync.html