Package: lintrunner
LintrunnerOverviewlintrunneris 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 oflintrunneris heavily inspired bylinttool, a project that exists internally at Meta.Installationpip install lintrunnerUsageFirst, you need to add a configuration file to your repo. See theLinter
configurationsection for more info.Then, simply runlintrunnerto lint your changes!How to control what paths to lintlintrunnerWhen run with no arguments,lintrunnerwill check:The files changed in theHEADcommit.The files changed in the user’s working tree.It doesnotcheck:Any files not tracked bygit;git addthem to lint them.There are multiple ways to customize how paths are checked:Pass paths as positional argumentsFor example:lintrunner foo.py bar.cppThis naturally composes withxargs, for example the canonical way to check
every path in the repo is:git grep -Il . | xargs lintrunner--configs/--config"Comma-separated paths to lintrunner configuration files.
Multiple files are merged, with later definitions overriding earlier ones.
ONLY THE FIRST is required to be present on your machine.
Defaults tolintrunner.toml, lintrunner.private.toml. Extra configs likelintrunner.private.tomlare useful for combining project-wide and local configs."--paths-cmdSome ways to invokexargswill cause multiplelintrunnerprocesses to be
run, increasing lint time (especially on huge path sets). As an alternative that
giveslintrunnercontrol of parallelization, you can use--paths-cmd. If--paths-cmdis specifiedlintrunnerwill execute that command and consider
each line of itsstdoutto be a file to lint.For example, the same command above would be:lintrunner --paths-cmd='git grep -Il .'--paths-fileIf this is specified,lintrunnerwill 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.--revisionThis value can be any<tree-ish>accepted bygit diff-tree, like a commit
hash or revspec. If this is specified,lintrunnerwill check:All paths changed from<tree-ish>toHEADAll paths changed in the user's working tree.--merge-base-withLike--revision, except the revision is determined by computing the merge-base
ofHEADand the provided<tree-ish>. This is useful for linting all commits
in a specific pull request. For example, for a pull request targeting master,
you can run:lintrunner -m master--all-filesThis will run lint on all files specified in.lintrunner.toml.--only-lint-under-config-dirIf set, will only lint files under the directory where the configuration file is located and its subdirectories.Linter configurationlintrunnerknows which linters to run and how by looking at a configuration
file, conventionally named.lintrunner.toml.Here is an example linter configuration:merge_base_with='main'[[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 foundhere.Linter protocolMost linters have their own output format and arguments. In order to impose
consistency on linter invocation and outputs,lintrunnerimplements a protocol
that it expects linters to fulfill. In most cases, a small script (called alinter adapter) is required to implement the protocol for a given external
linter. You can see some example adapters inexamples/.InvocationLinters will be invoked according to thecommandspecified 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 useargparse’sfromfile_prefix_charsfeature. In the Flake8 example above, we use@as thefromfile_prefix_charsargument, soargparsewill automatically read the{{PATHSFILE}}and supply
its contents as a list of arguments.OutputAny lint messages a linter would like to communicate the user must be
represented as aLintMessage. The linter, must printLintMessages  asJSON
Linestostdout, one message per line. Output tostderrwill be ignored.A complete description of the LintMessage schema can be foundhere.ExitingLintersshould always exit with code 0. This is true even if lint errors are
reported;lintrunneritself will determine how to exit based on what linters
report.To signal a general linter failure (which should ideally never happen!), linters
can return aLintMessagewithpath = None.In the event a linter exits non-zero, it will be caught bylintrunnerand
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.Tips for adoptinglintrunnerin a new projectWhen adopting lintrunner in a previously un-linted project, it may generate a lot
of lint messages. You can use the--output onelineoption to makelintrunnerdisplay each lint message in its separate line to quickly navigate
through them.Additionally, you can selectively run specific linters with the--takeoption,
like--take RUFF,CLANGFORMAT, to focus on resolving specific lint errors, or
use--skipto skip a long running linter likeMYPY.GitHub ActionTo uselintrunnerin a GitHub workflow, you can considerlintrunner-action.