Lintrunner

Warnings

• gotcha Lintrunner primarily functions as a command-line tool. While you can write custom linter adapters in Python that adhere to its JSON Lines output protocol, direct programmatic import of `lintrunner` as a library for general linting within Python code is not its primary use case. Its internal components are not designed for public API consumption.
  Fix: Use `lintrunner` via its command-line interface and `.lintrunner.toml` configuration. Develop custom linter adapters if integration with specific tools or logic is needed.
• gotcha By default, `lintrunner` checks files changed in the HEAD commit or the user's working tree. Files not tracked by Git will not be linted.
  Fix: Ensure all relevant files are tracked by Git (`git add <file>`). To lint all files, use `lintrunner --all-files`. To lint specific paths, pass them as arguments (e.g., `lintrunner foo.py bar.cpp`).
• breaking Linters invoked by `lintrunner` are expected to exit with code 0, even if lint errors are reported. A non-zero exit code from a linter is treated by `lintrunner` as a 'general linter failure', indicating an issue with the linter's implementation of the protocol, rather than reported lint messages.
  Fix: Ensure custom linter adapters (or the underlying linters they wrap) always exit successfully (code 0) and report any linting issues as `LintMessage` JSON Lines to stdout.
• gotcha Excluding patterns in `.lintrunner.toml` might not always work as expected, especially with newly added files or complex globbing. Issues have been reported where `exclude_patterns` are ignored.
  Fix: Double-check `include_patterns` and `exclude_patterns` syntax. If issues persist, consider more specific path arguments or adjusting the linter's command itself to filter paths. Monitor GitHub issues for updates on specific exclusion bugs.
• gotcha Due to its incremental linting approach, `lintrunner` might occasionally suggest unexpected or 'destructive' changes, especially when interacting with linters that are sensitive to partial file inputs.
  Fix: Always review suggested changes carefully. If unexpected behavior occurs, try running the linter directly on the full file or codebase to isolate if the issue lies with the linter or `lintrunner`'s incremental invocation.

Install

• pip install lintrunner Install core library
• pip install lintrunner-adapters Install official linter adapters (recommended)

Quickstart

To get started with `lintrunner`, first install the tool. Then, create a `.lintrunner.toml` file in your project's root directory to define the linters and their rules. `lintrunner` primarily operates as a command-line tool, checking files that have changed in your working tree or HEAD commit by default. You can use `lintrunner init` for an initial setup that may install additional linter dependencies. For linters that aren't Python-based, `lintrunner` uses 'adapter' scripts to conform to its standard JSON Lines output protocol.

# 1. Create a .lintrunner.toml configuration file
# Example .lintrunner.toml (save this to your project root)
# merge_base_with = 'main'
#
# [[linter]]
# name = 'EXAMPLE_LINTER'
# include_patterns = ['**/*.py']
# command = ['python3', '-c',
#   'import sys; import json;\n'
#   'for path in sys.stdin.read().splitlines():\n'
#   '    with open(path) as f:\n'
#   '        content = f.read()\n'
#   '        if "TODO" in content:\n'
#   '            print(json.dumps({"path": path, "line": 1, "char": 1, "code": "TODO_FOUND", "severity": "warning", "name": "TODO check", "message": "Found a TODO in the file."}))\n'
# ]

# 2. Create a dummy Python file to lint (e.g., my_file.py)
# print("This is a test file.")
# # TODO: implement this feature

# 3. Run lintrunner from your terminal in the project root:
# pip install lintrunner
# # For basic setup, you might need to run lintrunner init
# # lintrunner init # This can install various linter dependencies
# lintrunner

# Expected output for my_file.py with the EXAMPLE_LINTER:
# Path                   Line Char Code       Severity  Name          Message
# -------------------- ------ ---- ---------- --------- ------------- ------------------------
# my_file.py                1    1 TODO_FOUND warning   TODO check    Found a TODO in the file.