./checkpatch.sh # verify every tracked file -- what CI runs
./checkpatch.sh --staged # verify staged files -- what the git hook runs
./checkpatch.sh --files a.c b.md # verify specific files
./format-coding.sh # apply every autofix
./format-coding.sh --staged # apply the autofixes to staged files only
./format-coding.sh --files a.c # apply the autofixes to specific files
./format-coding.sh --check # report, then restore -- same as --preview
./checkpatch.sh --install-hooks # run the checks automatically on commit
Exit status is 0 clean, 1 findings, 2 a usage or environment problem.
Verification runs the real fixers, so a failing run leaves their corrections in
your working tree – git diff is the remediation. --preview is the mode that
reports without mutating.
Nothing needs to be installed except pre-commit itself, which then installs a
pinned copy of every linter into an isolated environment of its own. They do not
need to be on your PATH, and the version you happen to have installed cannot
change the result:
./checkpatch.sh --bootstrap # tries pipx, then pip --user
§6.1 has the per-platform command if that fails.
.pre-commit-config.yaml <-- rules live here
.github/linters/* <-- and their rule content
|
+--------------------+--------------------+
| | |
./checkpatch.sh git pre-commit hook .github/workflows/cicd-pr-check.yml
| | |
./format-coding.sh (same hooks) (same hooks, Linux and Windows)
Every caller above runs the same hook list from the same file. None of them contains a rule, a version, a file filter or a tool invocation of its own:
| File | Owns | Must never contain |
|---|---|---|
.pre-commit-config.yaml |
which tool, which version, which arguments, which files | nothing else does this |
.github/linters/ |
rule content (.clang-format excepted, see below) |
tool selection or versions |
.editorconfig |
encoding, line endings, and shfmt’s shell indent | indent widths the formatters already own |
.gitattributes |
line-ending normalization on checkout and check-in | anything else |
checkpatch.sh |
which files to feed the engine, how to report | any rule |
format-coding.sh |
thin write-mode wrapper over checkpatch.sh |
any rule |
.github/workflows/cicd-pr-check.yml (lint jobs) |
orchestration: OS matrix, caching, Python setup | any rule or config path |
| this document | prose rationale and the parity table | rules that are not in the config |
Adding or changing a lint rule means editing .pre-commit-config.yaml (and
the matching file in .github/linters/), and updating the parity table
below. Nowhere else. A rule added to the workflow, to a script, or
to a document is drift by construction, because only the config is what the hooks
actually execute.
Bumping a tool version is its own commit, and its message quotes the blast
radius from ./format-coding.sh --check. Never as a side effect of an unrelated
change: that is how a wrong clang-format silently reformats hundreds of files.
pre-commit autoupdate proposes the bumps.
.clang-format sits at the repository rootEvery other rule file lives in .github/linters/, because that is where
super-linter looks. .clang-format cannot: clang-format itself searches upward
from each source file, so the file has to be at the root, and it is a real
file, not a symlink. A Windows checkout without symlink support materializes a
symlink as a text file containing a path, at which point clang-format silently
finds no configuration and falls back to plain LLVM style – a whole-tree
reformat waiting to happen.
| Language | Tool | Fixes | Rule file |
|---|---|---|---|
| any | pre-commit-hooks 6.0.0 – five structural guards | no | – |
| C, C++ | clang-format 23.1.3 | yes | .clang-format |
| Python | isort 9.0.2 (--profile black) |
yes | – |
| Python | black 26.10.1 (--line-length 88) |
yes | – |
| Python | flake8 7.4.1 | no | .github/linters/.flake8 |
| Python | ruff 0.17.1 | partly | .github/linters/.ruff.toml |
| Shell | shfmt 3.14.1 | yes | .editorconfig ([*.sh]) |
| Shell | shellcheck 0.11.0 | no | – |
| Markdown | markdownlint-cli 0.49.1 | yes | .github/linters/.markdown-lint.yml |
| Markdown prose | textlint 15.8.0 + terminology 4.0.1 | yes | .github/linters/.textlintrc |
| YAML | yamllint 1.38.0 | no | .github/linters/.yaml-lint.yml |
| GitHub Actions | actionlint 1.7.12 | no | .github/linters/actionlint.yaml |
| HTML | htmlhint 1.9.2 | no | .github/linters/.htmlhintrc |
| staged diff | gitleaks 8.30.1 | no | – |
| CI path filters | .github/scripts/ci/lint/check-path-filters.py |
no | .github/path_filters.yml |
| commit message | gitlint 0.19.1 | no | .github/linters/.gitlint |
The gitlint row is the one hook that does not run over files. It runs at the
commit-msg stage against the message being written, so ./checkpatch.sh –
which lints files and has no message to read – never triggers it; the git
commit-msg hook fires it locally and CI runs the same hook over a pull
request’s commits. §7 has the split between what its regular expression
enforces and what still needs a reviewer.
Read the gitleaks row narrowly. Its hook is gitleaks git --pre-commit --staged,
so it scans the staged diff and cannot scan a whole tree – in --all-files
mode nothing is staged and it passes trivially. It catches a secret you are about
to commit; whole-tree and pull-request scanning is CI’s, in the parity table
below.
A rule file must name its rules, and an argument that matters must be written down. Both halves of that were learned the hard way here:
.github/linters/.ruff.toml carries an explicit select. A config that names
no rules describes the pinned version rather than a check – ruff’s implicit
default went from about 40 rules to 413 between 0.4 and 0.16, so bumping the pin
turned one hook into 592 findings about blind excepts and datetime timezones,
none of which anybody had chosen to enforce.--line-length 88 is black’s own default, spelled out anyway, because
this document said the Python line length was 120 while the formatter had been
wrapping at 88 all along. The two numbers are not in conflict – black wraps at
88, ruff only rejects beyond 120 – but only one of them was written down.flake8 and ruff both run, and the overlap is deliberate rather than accidental.
.ruff.toml selects E, W, F – flake8’s own rule set, since flake8 declares
no select either – so the two are as close to interchangeable as they can be.
They are not yet interchangeable in one direction: ruff 0.17 does not implement
F824 (“dead global declaration”) at all; ruff rule F824 answers “unknown
rule”. flake8 7.3 found two of them here, both genuinely dead. That single rule is
the whole reason the flake8 hook still exists, which is also why its rule set is
mirrored rather than extended – when ruff grows F824, retiring flake8 is a delete
and not a re-measurement.
The five pre-commit-hooks entries are not style checks. Each one mechanically
guards a promise made elsewhere in this document and otherwise enforced by nothing:
destroyed-symlinks guards §2.1,
check-illegal-windows-names and mixed-line-ending guard
§6, check-merge-conflict is universal, and detect-private-key
is the only secret scan that runs in a bare whole-tree ./checkpatch.sh – see the
gitleaks note above for why that gap exists.
A version bump may not smuggle in a rule change, and three of the bumps in this set tried to:
textlint-rule-terminology 5.x rewrote prose in 15 files, including 18 lines of
published CHANGELOG.md history, and replaced “blank line” with “empty line” –
in a document describing git commit format, where “blank line” is git’s own
wording. The engine is bumped to textlint 15.8.0; the word list stays at
terminology 4.0.1, because the word list is rule content, not a tool version.
It lives at a pinned version for the same reason .github/linters/ exists.pymtl_wrap.c (SWIG-generated) and vmlinux.h (kernel-generated) are excluded
from clang-format.
patches/ is a vendored third-party patch series: reformatting a byte of it would
break git apply. That started life as a global exclude: ^patches/, and a
global exclude was the wrong shape twice over. It protected nothing – every
formatter here is selected by language type, a *.patch file is none of those
types, and deleting the exclude changed no hook’s result on the whole tree. And it
silently disabled check-illegal-windows-names, which reads paths rather than
content and so was the one hook the exclude could actually reach. With the hook
blinded, patches/dpdk/26.03/0012-net-ice-e830:-...patch sat in the tree with a
colon in its name; git checkout on Windows rejects that outright with error:
invalid path and exit 128, so the repository could not be cloned there at all and
the Windows CI job died during checkout, before any linter ran. The file is renamed
and the exclusion now sits on mixed-line-ending – the only hook that reads every
file regardless of type – and nowhere else.
C/C++ style is whatever .clang-format says – BasedOnStyle: Google with
ColumnLimit: 90 today. Changing it rewrites the entire tree, so it is its own
commit or it is a mistake.
Two things about clang-format 22 are worth knowing before the next bump, because
both were paid for once already. It no longer reads (type)-1 as a cast, so
((mtl_iova_t)-1) is now written ((mtl_iova_t) - 1); that is whitespace only and
the tokens are identical, and in the ((align)-1) case – a macro parameter, not
a type – the new spacing is simply correct. And from 18 on, a braced initializer
whose elements carry trailing comments is broken to one element per line. The six
le10_to_be_* permute tables in lib/src/st2110/st_avx512_vbmi.c are laid out one
pixel group per row precisely so the pattern can be read against the packing it
implements, so they sit inside a /* clang-format off */ region. That is a pin on
the layout, not an exemption from review: reformatting them cost 480 lines and all
of their readability.
Rules the language tools cannot express – the two-world rule, prefixes, lock
order, error-return conventions – are in
.github/instructions/mtl-c-coding.instructions.md
and enforced by review, not by a linter.
Not every available check is enabled. These were considered and rejected, so that “why isn’t there a hook for X” has an answer:
end-of-file-fixer, trailing-whitespace – would rewrite 152 and 34
tracked files respectively on first run. Pure churn against a tree nobody has
complained about. .editorconfig deliberately does not declare
insert_final_newline either: a rule no hook reads would just move the same
152 violations somewhere less visible.check-shebang-scripts-are-executable – fails 17 pre-existing files. The
narrower “*.sh must be executable” check that CI already had is kept instead
(see the parity table).check-json – fails 20-plus tests/tools/RxTxApp/script/**/*.json, which
use trailing commas. json-c, which RxTxApp actually parses them with, accepts
those; strict JSON does not. Turning the check on means rewriting working
fixtures, so it stays off and the fixtures stay as they are.check-case-conflict – fails, and the failure is a real defect rather than
a style preference: tests/acceptance/mtl_engine/RxTxApp.py and
tests/acceptance/mtl_engine/rxtxapp.py are both tracked, so this tree cannot be
checked out on a case-insensitive filesystem, which contradicts the macOS and
Windows support claimed in §6. Renaming a module that
mtl_engine imports is not a lint change; the hook is left off until that is
fixed on its own terms..github/linters/
while the matching validators were switched off in CI. The configs were
deleted; the validators stay off. Re-enabling either is a rule change and needs
its own discussion.The three must agree. Anything CI enforces that checkpatch.sh cannot reproduce
is listed here explicitly, and runs in the residual-linters job of
.github/workflows/cicd-pr-check.yml.
| CI check | Status | Why |
|---|---|---|
| clang-format, isort, black, flake8, ruff, shfmt, shellcheck, markdownlint, textlint, yamllint, actionlint, htmlhint | in checkpatch.sh |
pinned by .pre-commit-config.yaml; each pin measured clean over the whole tree before adoption |
VALIDATE_GITLEAKS |
residual | the hook scans the staged diff, so it cannot scan a whole tree or a pull request. Both run the same scanner at different scopes. detect-private-key covers the whole tree, but only for PEM blocks |
VALIDATE_BASH_EXEC |
residual | *.sh must keep its executable bit. No upstream hook has these exact semantics; the nearest one is broader and fails 17 files |
VALIDATE_ENV (dotenv-linter) |
dropped | the slim image had no dotenv-linter before super-linter 6.8.0, so it never ran. From there on it fails all 11 tracked *.env, most of them path manifests rather than dotenv files |
VALIDATE_TYPESCRIPT_ES |
residual | 135 *.ts files with no lintable project configuration from a clean clone: .gitignore’s blanket *.json leaves tests/tools/perf_debug_mcp/package.json untracked. .github/linters/eslint.config.mjs keeps it the parse check super-linter v6 ran |
VALIDATE_RUST_*, VALIDATE_RUST_CLIPPY |
residual | rustfmt and clippy need a Rust toolchain per environment. Carried over unchanged rather than narrowed, since narrowing the edition list would be a rule change |
VALIDATE_EDITORCONFIG |
dropped | it was default-on before, and enforced nothing: no .editorconfig existed. The one that exists now declares only charset, end_of_line and shfmt’s shell indent, all of which the hooks or .gitattributes already cover |
| commit-message style (gitlint) | own commit-messages job |
a message is not a file, so checkpatch.sh cannot reach it. The job runs the same commit-msg hook over each PR commit that the git commit-msg hook runs locally, so version and rules stay in one place. Not in residual-linters: that is the super-linter allow-list, and MTL’s capitalized, scope-free format is not one |
| Bandit | bandit job of cicd-pr-check.yml |
a security scan with a mandated test set, not a style rule. The test set is .github/code-scan/bandit.config, apart from the linter configs in .github/linters/. task ci:bandit reproduces the scan locally, with the Bandit release pinned in .github/code-scan/requirements.txt, which Dependabot updates |
| clang-tidy, on the C and C++ lines a pull request changes | own clang-tidy job in cicd-pr-check.yml |
it needs the compile commands of configured builds, which checkpatch.sh has no part in. The checks are .clang-tidy’s, run by cpp-linter/cpp-linter-action; the report is the clang-tidy-report artifact. After ./build.sh, clang-tidy-20 -p build <file> runs them on one file locally |
That job was a deny-list of nine VALIDATE_*: false keys and is now an
allow-list, so anything not named above is no longer enforced – the two real
cases are in the table, and a file type census found no tracked *.js, *.css,
*.xml, *.go, *.rb, *.java or *.sql for the rest to have applied to.
super-linter aborts if true and false are mixed, so no VALIDATE_*: false
line may be added back.
The build job of .github/workflows/cicd-pr-check.yml needs the checkpatch
matrix jobs and residual-linters (Lint checks not yet in checkpatch). A lint
failure therefore skips the build rather than wasting a DPDK compile on it, and
ci-result fails. The ci-result job is the one branch-protection check for
the workflow. It requires the file linters and commit-message check on pull
requests. Commit-message style does not block the compile.
The coupling is by job ID in needs:, in one workflow, so GitHub refuses a
rename of a lint job that does not also change the build job.
./checkpatch.sh --install-hooks
Installs the pre-commit, pre-merge-commit and commit-msg hooks. The first
two check staged files only, so they cost roughly the size of your change, not
the size of the tree; the third runs gitlint over the message you are writing
(§7).
To bypass in an emergency:
git commit --no-verify
git merge --no-verify
Bypassing is for a work-in-progress commit or a broken hook, not for merging unformatted code: CI runs the identical hook list and is the merge authority.
One surprise worth knowing before it costs you ten minutes: if
.pre-commit-config.yaml itself has unstaged modifications, the hook refuses to
run at all and every commit fails with Your pre-commit configuration is
unstaged. Stage the config, or use --no-verify while you iterate on it.
Any Linux distribution, macOS and Windows (git-bash / MSYS2) are supported, and
CI runs ./checkpatch.sh on Linux and Windows. The cross-platform claim had
already rotted once before that job existed: a tracked filename containing a
colon made the tree impossible to check out on Windows (see the patches/ note
in §3). check-illegal-windows-names now fails locally
on any path Windows cannot represent, which is a cheaper place to find out.
You need git, Python 3.10 or newer (what pre-commit 4.x requires), and network
access on the first run. Nothing else – no distribution package of clang-format,
shfmt, shellcheck, Node.js or Go.
./checkpatch.sh --bootstrap # pipx if present, else pip --user
Most current distributions mark their system Python as externally managed
(PEP 668), which makes pip install --user fail. That is not a broken repository
– it means you should take the distribution’s own package, or pipx:
| Platform | Command |
|---|---|
| Fedora, RHEL, CentOS Stream | sudo dnf install pre-commit |
| Arch, Manjaro | sudo pacman -S python-pre-commit |
| Debian, Ubuntu | sudo apt install pre-commit |
| openSUSE | sudo zypper install python3-pre-commit |
| macOS | brew install pre-commit |
| Windows, git-bash / MSYS2 | py -m pip install pre-commit |
| anything with pipx | pipx install pre-commit |
Then, once per clone:
./checkpatch.sh --install-hooks
The first run builds the pinned tools into ~/.cache/pre-commit – about 560 MB
and a few minutes, once per .pre-commit-config.yaml change. PRE_COMMIT_HOME
moves it, which is what CI does to keep the cache workspace-relative.
Ten hooks are Python wheels; the other four need no system toolchain either.
gitleaks is a Go hook and pre-commit downloads Go itself when it is not on
PATH. markdownlint, textlint and htmlhint are Node hooks, and the config
pins default_language_version: node so pre-commit fetches that exact Node
rather than using whatever the host has – markdownlint-cli 0.49 needs Node 20 or
newer merely to parse its own source, so an older system Node was a crash and a
newer one was an unpinned variable.
One thing genuinely not pinned is the engine: the config’s floor is
minimum_pre_commit_version: 3.5.0, CI runs the release that
.github/linters/requirements.txt locks, and a distribution package may be
older than either. If a hook behaves differently for you than in CI, check
pre-commit --version first – CI is authoritative.
mapfile, no nproc, no grep -oP, no
readlink -f, no in-place sed -i. macOS ships bash 3.2 and a BSD userland;
MSYS2 ships neither GNU coreutils defaults nor a POSIX filesystem.pre-commit verbatim, which resolves them itself. Rewriting
them in shell breaks MSYS2, where pwd is not a path native Python can resolve..gitattributes, which converts on check-in:
what is already committed is left alone, so one tracked CRLF Markdown file
remains and is fine. What must not happen is a mixed file, which would fail
shfmt and clang-format alike – mixed-line-ending is the hook that checks it,
with --fix=no, because normalizing endings is .gitattributes’ job.MTL follows Conventional Commits
with two deviations: structural elements are capitalized, and Add is accepted
for feat plus build(deps) for dependency bumps.
Build: changes to the build tooling or external dependenciesCi: changes to CI configuration and scriptsDocs: documentation onlyFeat / Add: a new featureFix: a bugfixPerf: a change that improves performanceRefactor: a change that neither fixes a bug nor adds a featureStyle: changes that do not affect the meaning of the codeTest: adding or correcting testsThe mechanical half of that format is automated, by gitlint. The
commit-msg git hook runs it on every git commit locally, and the
commit-messages job in .github/workflows/cicd-pr-check.yml runs the same hook over
each commit a pull request adds. checkpatch.sh itself still checks only
files – it has no message to read – so message linting rides the commit-msg
stage, not a checkpatch.sh run. The rules are in .github/linters/.gitlint,
the version is pinned in .pre-commit-config.yaml, and both callers run the one
hook, so they cannot drift.
gitlint enforces what a regular expression can judge: the type prefix comes from the fixed
set above, capitalized; a capital follows it; the subject is at most 72
characters with no trailing period; and git commit -s’s Signed-off-by
trailer is present. It deliberately does not use its own conventional-commit
rule, which wants a lowercase feat: with scopes – the opposite of MTL’s
format. Body-line wrapping is left off because a valid Fixes: or
Signed-off-by footer legitimately runs past 72 and would false-positive.
Everything the mtl-commit skill asks
for that a regular expression cannot judge – imperative mood, “explain why, not how”, no
chat-or-process leakage, body wrapping – stays a reviewer’s call, in the same
bucket as the two-world rule and the prefixes in
.github/instructions/mtl-c-coding.instructions.md.
The diagrams in doc/png/ use the five palette colors.
| Color | Hex | Use |
|---|---|---|
| Intel Classic Blue | #0068B5 |
The MTL logo, png/mtl_logo.svg |
| Hex | Use in the diagrams |
|---|---|
#1F271B |
Text, lines, arrows and borders |
#0B4F6C |
Session blocks and the control plane panel |
#145C9E |
The MTL block and the data plane panel |
#CBB9A8 |
Group panels, for example Pipeline API and Device |
#DCC7BE |
Page background and labels |
The logo letters are polygons. Thus, installed fonts do not change the logo.