| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The previous commit shipped the documentation for `make tools` and the `.gitignore`
line for the venv it creates, and not the target itself. A `git reset --hard`,
undoing a throwaway probe commit, took the working tree with it -- which is what
`--hard` does. The `.gitignore` line was noticed missing and rewritten; the three
files it was standing next to were not, so `docs/design.md` has been describing a
target that did not exist. This is that target.
`ruff` is not a system package on most machines, and `pip install --user ruff` is
refused outright on a distro python (PEP 668):
$ make tools
ruff 0.16.3 in .venv
survives make clean; rm -rf .venv to start over
clang-format stays a system package, because everywhere it is one; `make tools`
says so when it is missing rather than pretending it handled it.
**The venv is looked in before `$PATH`, and that order is the point.** `ruff.toml`
now pins the version with ruff's own `required-version`, so a ruff of the wrong one
refuses to run and names both versions. Preferring `$PATH` would then strand
somebody with 0.14 from their package manager and 0.16.3 sitting in the `.venv` the
repo just built them -- refused by the tool, with the fix on disk and nothing
looking at it. Tested with exactly that, for `make fmt-check` and for the hook.
The pin exists because a formatter whose output moves between releases turns
"formatted" into "formatted by whoever committed last", and the diff lands on the
next person to touch the file. Bumping it is one line in `ruff.toml`, one in the
Makefile, and a reformat commit -- the honest cost of a new version.
The hook resolves ruff the same way, off `git rev-parse --show-toplevel` so it works
from a subdirectory, and its message when ruff is missing now says `make tools`.
Verified from a deleted `.venv`: `make fmt` stops with `ruff not found. run: make
tools`; after `make tools` both `fmt` and `fmt-check` work with nothing on `$PATH`;
`make fmt` over the whole tree changes nothing, so the pinned version agrees with
what is committed; the hook formats a staged Python file through the venv, and still
does with 0.14.0 ahead of it on `$PATH`.
The hook was tested by running `.githooks/pre-commit` directly against a staged
file. The obvious way -- a real probe commit -- needs the working tree clean to be
meaningful, and getting there is what caused the mess this commit is repairing.
|
|
|
The other half of the pre-commit hook. C goes through clang-format, Python through
ruff: `ruff check --select I --fix` to sort the imports, then `ruff format` to lay
them out. `make fmt` does both, `make fmt-check` reports, `make hooks` installs it.
ruff rather than black because it is one static binary instead of a Python
dependency chain, and fast enough that a hook is free. Its formatter is
black-compatible, so this is the ecosystem's formatting rather than a dialect --
measured at 9,935 changed lines against black's 9,953, which is the same answer.
**Left entirely at the defaults**, which is the opposite of what `.clang-format`
does. That file argues with LLVM in five places because the C here was
hand-formatted into a house style worth keeping. The Python was not, and a
formatter of this kind is only worth having when there is nothing left to argue
about: every knob turned is an argument somebody has to have again later. 88
columns, double quotes, ruff's own line breaking.
**Import sorting is on, and C include sorting stays off.** Not an inconsistency: a
C include order can be load-bearing -- `_GNU_SOURCE` ahead of the system headers,
and a grouping somebody wrote by hand -- while Python import order is not. Where it
genuinely is, a statement between imports ends the block ruff will sort, and the
test files lean on exactly that:
import sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from harness import Session, check, report
`from harness import` cannot be hoisted above the line that makes it importable,
because the `sys.path.insert` between them is a barrier. Verified before touching
anything, since getting it wrong would have broken every test in the suite at once.
Two details in the hook worth naming. `--select I` is passed on the command line as
well as set in `ruff.toml`, so a stray `select` in somebody's own config cannot
turn a formatting hook into a linter that refuses a commit over an unused variable.
And the two tools are named together when either is missing, so setting up a
machine installs both at once instead of finding the second one on the next commit.
`set -e` and `[ -n "$c_files" ] && clang-format ...` do not mix: when the list is
empty the AND-list returns non-zero and the shell exits, so a Python-only commit
would have aborted with no message at all. They are `if` blocks. Found by testing
the case rather than by reading it.
Verified in a scratch clone, seven paths: Python alone, C alone, both in one
commit, imports sorted with the `sys.path` barrier intact, a `contrib/` script that
is Python with no extension on it, a partly staged Python file refused with `HEAD`
unchanged, and a commit with no code in it drawing no comment.
|
