Find new mandoc -T lint warnings in FreeBSD manual pages, per git
commit, before they pile up.
mandoc -T lint is the standard way to check a manual page, but on a
page with existing warnings it is hard to see whether your change made
things better or worse. This script answers exactly that question: for
every manual page changed in a commit, it lints the old and the new
version and reports only the difference, the warnings that were
introduced and the ones that were fixed.
It can also check uncommitted changes before you commit them, and give an overview of which pages in a directory are lint clean and which still need work.
Download the script from https://people.freebsd.org/~wosch/src/mandoc-lint-regression/mandoc-lint-regression.sh and make it executable, e.g. on FreeBSD:
fetch https://people.freebsd.org/~wosch/src/mandoc-lint-regression/mandoc-lint-regression.sh
chmod +x mandoc-lint-regression.sh
/bin/sh (POSIX shell, no bash needed)git, mandoc(1) and file(1), all in the FreeBSD base systemRun the script anywhere inside a git checkout, e.g. freebsd-src.
mandoc-lint-regression.sh [-ck] [-d level] {commit | staged | unstaged}
mandoc-lint-regression.sh [-c] [-d level] -s path ...
mandoc-lint-regression.sh -V
| Argument / option | Meaning |
|---|---|
commit |
a commit hash, or any name git accepts: HEAD, HEAD~3, a branch, a tag |
staged |
changes in the index against HEAD (git diff --cached) |
unstaged |
changes in the working tree against the index (git diff) |
-s path ... |
lint status of all manual pages below the paths, see below |
-c |
ignore vendor code below contrib/, crypto/, cddl/ and sys/contrib/ (FreeBSD), external/ (NetBSD) and gnu/ (OpenBSD, NetBSD); for a renamed page, the new path counts |
-d level |
output level 0 to 3, see below (default: 1) |
-k |
keep the work directory with the extracted files and lint output |
-V |
print the version |
Environment variables:
| Variable | Meaning |
|---|---|
MANDOC |
mandoc binary to use, a command name or path without options (default: mandoc) |
MANPATTERN |
file names of manual pages, shell patterns separated by spaces (default: *.[1-9]) |
debug |
default output level, overridden by -d |
A file counts as a manual page if its name matches MANPATTERN and
file(1) detects it as troff input, so data files like test.1 are
skipped.
Exit status: 0 if there are no new warnings (with -s: all pages are
lint clean), 1 if there are, 2 on errors, including a mandoc that
fails to run (mandoc exit status 5 or 6). Lint messages never cause
exit status 2. This makes the script usable
in loops, git hooks and CI.
$ mandoc-lint-regression.sh -d 2 11a64dfa100d
==> lib/libpmc/pmc.amd.3 (11a64dfa100d 2026-11-08 @wosch)
log: pmc.amd.3: add missing commas between names
fixed warnings:
mandoc: lib/libpmc/pmc.amd.3:29:2: WARNING: missing comma before name: Nm pmc.k8
✓ 3 warning(s) left
==> usr.bin/find/find.1 (11a64dfa100d 2026-11-08 @wosch)
log: pmc.amd.3: add missing commas between names
✗ new warnings:
mandoc: usr.bin/find/find.1:412:23: STYLE: whitespace at end of input line
Each page is shown with the commit's short hash, date and committer,
followed by the subject of the commit message (log:).
If the commit is on a vendor branch, e.g. a vendor import, the branch
is shown as well:
==> zlib.3 (d3419e91c112 origin/vendor/zlib 2026-11-07 @delphij)
Line and column numbers are ignored when comparing, so text that only moved does not show up as a new warning. Renamed pages are compared with their old version.
On a UTF-8 terminal, the status is marked in color:
| Mark | Meaning |
|---|---|
| ✗ red | new warnings |
| ✓ yellow | warnings fixed or unchanged, but some are left |
| ✓ green | the page is lint clean (no mandoc output at all) |
In pipes and log files, or with NO_COLOR set, the output is plain
text.
Set the level with -d level:
| Level | Shows |
|---|---|
| 0 | nothing, only the exit status |
| 1 | new warnings (default) |
| 2 | also fixed warnings, and whether the page is now lint clean or how many warnings are left |
| 3 | everything: unchanged and skipped pages, and a summary |
mandoc-lint-regression.sh unstaged
mandoc-lint-regression.sh staged
New files must be known to git: git add them, or use git add -N file
for unstaged. The keywords take precedence over a branch or tag of the
same name; use e.g. refs/heads/staged in that case.
To refuse commits that add new warnings, put this into
.git/hooks/pre-commit and make it executable:
#!/bin/sh
exec mandoc-lint-regression.sh staged
With -s, the script does not compare versions, but reports the
current state of all manual pages below the given directories or files,
as they are on disk:
$ mandoc-lint-regression.sh -s usr.bin/find lib/libc
✗ lib/libc/gen/getbsize.3: 2 warning(s)
✗ usr.bin/find/find.1: 1 warning(s)
214 manual page(s) checked: 212 lint clean, 2 need fixing
Only files tracked by git are checked, so build output and other
untracked files are ignored. With -s, the output levels set with
-d level are:
| Level | Shows |
|---|---|
| 0 | nothing, only the exit status |
| 1 | the pages that need fixing, and a summary (default) |
| 2 | also their warnings |
| 3 | also the lint clean and skipped pages |
The script checks one commit per call. Use git log to pick the
commits and run the script in a loop.
Use git log --first-parent to check only the commits made on the
branch itself, e.g. main. Without it, git log also lists the commits
of branches that were merged into main, above all the vendor branches,
so you would check every single commit of a vendor import, e.g. on
vendor/zlib. With --first-parent, you get the merge commit instead.
It shows the change below contrib/, which -c can ignore.
for i in $(git log --first-parent --format=%h -100); do
mandoc-lint-regression.sh "$i"
done
With -c, manual pages in vendor code, e.g. below contrib/, are
ignored:
for i in $(git log --first-parent --format=%h \
--since="30 days ago"); do
mandoc-lint-regression.sh -c "$i"
done
Your commits of the last 90 days. With -d 2, the output also shows
the warnings you fixed, and whether a page is now lint clean:
for i in $(git log --first-parent --author="$(whoami)" --format=%h \
--since="90 days ago"); do
mandoc-lint-regression.sh -d 2 "$i"
done
Faster: with the path pattern '*.[1-9]', git lists only the commits
that change a manual page. --reverse checks them oldest first:
for i in $(git log --first-parent --reverse --format=%h \
--since="90 days ago" -- '*.[1-9]'); do
mandoc-lint-regression.sh "$i"
done
All commits on stable/15 since the 15.1 release that touch manual
pages, oldest first, ignoring vendor code with -c:
for i in $(git log --first-parent --reverse --format=%h \
release/15.1.0..origin/stable/15 -- '*.[1-9]'); do
mandoc-lint-regression.sh -c "$i"
done
The range release/15.1.0..origin/stable/15 lists the commits on
stable/15 that are not part of 15.1.0. As the release tag is on the
releng/15.1 branch, this includes the commits made on stable/15
during the release cycle, after releng/15.1 was branched. If your
remote is called freebsd, use freebsd/stable/15, and run
git fetch --tags first if the tag is missing in your clone.
The script is fast enough to check a lot of history: about 1000 commits, roughly one month of freebsd-src, take less than 20 seconds. Commits that do not change any manual page cost almost nothing.
-s runs mandoc and file once per page. Checking all manual pages
in freebsd-src takes about 3 minutes:
$ time mandoc-lint-regression.sh -s .
...
5968 manual page(s) checked: 2329 lint clean, 3639 need fixing
real 3m17.021s
.Xr references against the manual pages installed on
your machine (/usr/share/man), not against the source tree. A
commit that adds a new page and references it reports
"referenced manual not found" until the page is installed, and -s
gives the most accurate results on a system built from the same
tree.BSD-2-Clause, Copyright (c) 2026 Wolfram Schneider wosch@FreeBSD.org