mandoc-lint-regression

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

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

Requirements

Run the script anywhere inside a git checkout, e.g. freebsd-src.

Usage

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.

Checking a commit

$ 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.

Output levels

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

Checking uncommitted changes

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

Status of a directory

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

Checking history

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.

The last 100 commits

for i in $(git log --first-parent --format=%h -100); do
    mandoc-lint-regression.sh "$i"
done

The last 30 days, ignoring vendor code

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 own commits, with fixed warnings

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

Only commits that touch manual pages

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

A stable branch since a release

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.

Performance

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

Limitations and security

License

BSD-2-Clause, Copyright (c) 2026 Wolfram Schneider wosch@FreeBSD.org