A lint running tool and framework.
Project description
Lintrunner
Overview
lintrunner
is a tool that runs linters. It is responsible for:
- Deciding which files need to be linted.
- Invoking linters according to a common protocol.
- Gathering results and presenting them to users.
The intention is to provide a universal way to configure and invoke linters, which is useful on large polyglot projects.
The design of lintrunner
is heavily inspired by linttool
, a project that exists internally at Meta.
Installation
Currently, do:
cargo install lintrunner --force
In the future we’ll probably do binary releases through GitHub, pip
, or conda
.
Usage
First, you need to add a configuration file to your repo. See the Linter configuration section for more info.
Then, simply run lintrunner
to lint your changes!
How lintrunner
decides what paths to lint
When run with no arguments, lintrunner
will check:
- The files changed in the
HEAD
commit. - The files changed in the user’s working tree.
It does not check:
- Any files not tracked by
git
;git add
them to lint them.
There are multiple ways to customize how paths are checked:
Pass paths as positional arguments
For example:
lintrunner foo.py bar.cpp
This naturally composes with xargs
, for example the canonical way to check
every path in the repo is:
git grep -Il . | xargs lintrunner
--paths-cmd
Some ways to invoke xargs
will cause multiple lintrunner
processes to be
run, increasing lint time (especially on huge path sets). As an alternative that
gives lintrunner
control of parallelization, you can use --paths-cmd
. If
--paths-cmd
is specified lintrunner
will execute that command and consider
each line of its stdout
to be a file to lint.
For example, the same command above would be:
lintrunner --paths-cmd='git grep -Il .'
--paths-file
If this is specified, lintrunner
will read paths from the given file, one per
line, and check those. This can be useful if you have some really complex logic
to determine which paths to check.
--revision
This value can be any <tree-ish>
accepted by git diff-tree
, like a commit
hash or revspec. If this is specified, lintrunner
will check:
- All paths changed from
<tree-ish>
toHEAD
- All paths changed in the user's working tree.
Linter configuration
lintrunner
knows which linters to run and how by looking at a configuration
file, conventionally named .lintrunner.toml
.
Here is an example linter configuration:
[[linter]]
name = 'FLAKE8'
include_patterns = [
'src/**/*.py', # unix-style globs supported
'test/**/*.py',
]
exclude_patterns = ['src/my_bad_file.py']
command = [
'python3',
'flake8_linter.py',
'—-',
# {{PATHSFILE}} gets rewritten to a tmpfile containing all paths to lint
'@{{PATHSFILE}}',
]
A complete description of the configuration schema can be found here.
Linter protocol
Most linters have their own output format and arguments. In order to impose
consistency on linter invocation and outputs, lintrunner
implements a protocol
that it expects linters to fulfill. In most cases, a small script (called a
linter adapter) is required to implement the protocol for a given external
linter. You can see some example adapters in examples/
.
Invocation
Linters will be invoked according to the command
specified by their
configuration. They will be called once per lint run.
If a linter needs to know which paths to run on, it should take a
{{PATHSFILE}}
argument. During invocation, the string {{PATHSFILE}}
will be
replaced with the name of a temporary file containing which paths the linter
should run on, one path per line.
A common way to implement this in a linter adapter is to use argparse
’s
fromfile_prefix_chars
feature. In the Flake8 example above, we use @
as the fromfile_prefix_chars
argument, so argparse
will automatically read the {{PATHSFILE}}
and supply
its contents as a list of arguments.
Output
Any lint messages a linter would like to communicate the user must be
represented as a LintMessage
. The linter, must print LintMessage
s as JSON
Lines to stdout
, one message per line. Output to
stderr
will be ignored.
A complete description of the LintMessage schema can be found here.
Exiting
Linters should always exit with code 0. This is true even if lint errors are
reported; lintrunner
itself will determine how to exit based on what linters
report.
To signal a general linter failure (which should ideally never happen!), linters
can return a LintMessage
with path = None
.
In the event a linter exits non-zero, it will be caught by lintrunner
and
presented as a “general linter failure” with stdout/stderr shown to the user.
This should be considered a bug in the linter’s implementation of this protocol.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for lintrunner-0.5.4-py3-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c03bb1ee642ab2b157a990afcb2a640efae01b13605d7ac7afad2886c5c967d3 |
|
MD5 | aaf280ebc8ba467223aea4a0795b70a1 |
|
BLAKE2b-256 | 4994ffb509a022add1e4ff7a6603aeb39c6c9941b3488c3f481bace8e82d9063 |
Hashes for lintrunner-0.5.4-py3-none-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5433cea34b3dde3fc8a5b837db4dd6b6a594906e05e5de006f2b2c18432f0dba |
|
MD5 | cbf6d532a6e8fe9f3c7c9a0e4702fd42 |
|
BLAKE2b-256 | 2ea6f1d0e9e2b0588676da7076ddf02944e5dea131214a115d5141362d73e1c8 |
Hashes for lintrunner-0.5.4-py3-none-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2265fbc1791be6a87da83192cbdf6ca89c4eeae13a6d330747ac07e9caa6d0eb |
|
MD5 | 15efd139ed5ddd78029c0a46f2d84c62 |
|
BLAKE2b-256 | 2981d92dc5d9633bfc8cb3a4fb20deca0fdc5a5d2c2d06cdbd6a6e14c2b2d0ca |