#!/bin/sh # Copyright (c) Nov 2026 Wolfram Schneider # SPDX-License-Identifier: BSD-2-Clause # # mandoc-lint-regression.sh - check manual pages changed in a git commit # for new mandoc(1) lint warnings # # 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 # # commit a commit hash, or any name git accepts for a commit, # e.g. HEAD, HEAD~3, a branch or a tag # # For every manual page added or modified in the given commit (a file # matching $MANPATTERN that file(1) detects as troff), run "mandoc -T lint" # on the new version and on the version in the parent commit, and # report warnings that were introduced or fixed. Line and column # numbers are ignored for the comparison, so moved text does not show # up as a change. # # Instead of a commit, you can check local changes that are not # committed yet: # staged changes in the index against HEAD (git diff --cached) # unstaged changes in the working tree against the index (git diff) # These keywords take precedence over branches or tags of the same # name; use e.g. refs/heads/staged for such a branch. New files must # be known to git: git add them, or use "git add -N" for unstaged. # # With -s, the script does not look for regressions, but reports the # current lint status of all manual pages below the given paths, as # they are on disk: which pages are lint clean, and which need to be # fixed. Only files tracked by git are checked, so build output and # other untracked files are ignored. # # Symbolic links are never followed: like git, the script treats a # symlinked manual page as a file that contains the link target, so it # is skipped as not troff. File names with tabs or newlines are not # supported. # # Homepage: https://people.freebsd.org/~wosch/src/mandoc-lint-regression/ # See README.md there for sample output, a pre-commit hook and more # examples. # # Options: # -c ignore vendor code: manual pages below contrib/, crypto/, # cddl/ and sys/contrib/ (FreeBSD), external/ (NetBSD) and # gnu/ (OpenBSD, NetBSD) # -d level output level (default: 1, or $debug if set): # 0 print nothing, only set the exit status # 1 show new warnings # 2 show new and fixed warnings; after a fix, also show # whether the page is now lint clean (no mandoc output # at all) or how many warnings are left # 3 show everything: unchanged and skipped files, summary # with -s: # 0 print nothing, only set the exit status # 1 list the pages that need fixing, and a summary # 2 also show their warnings # 3 also list the lint clean and the skipped pages # -k keep the work directory with the files and lint output # -s show the lint status of all manual pages below the given # paths (directories or files), see above # -V print the version and exit # # Environment: # MANDOC mandoc binary to use, a command name or path without # options (default: mandoc) # MANPATTERN file names of manual pages, as shell patterns separated # by spaces (default: "*.[1-9]", FreeBSD sections 1-9), # e.g. MANPATTERN="*.[1-9] *.[1-9]lua" # debug default output level, overridden by -d # # Exit status: # 0 no new warnings; with -s: all manual pages are lint clean # 1 new warnings were introduced; with -s: at least one manual page # has warnings # 2 usage or other error, e.g. mandoc failed to run (exit status 5 # or 6 of mandoc) # # Examples: # # a single commit # mandoc-lint-regression.sh 11a64dfa100d # # # local changes before you commit them # mandoc-lint-regression.sh unstaged # mandoc-lint-regression.sh staged # # # which manual pages in usr.bin/find and lib/libc need fixing? # mandoc-lint-regression.sh -s usr.bin/find lib/libc # # # commits of the last 30 days that touch manual pages, ignoring # # vendor code # for i in $(git log --first-parent --format=%h --since="30 days ago" \ # -- '*.[1-9]'); do # mandoc-lint-regression.sh -c "$i" # done set -u : "${MANDOC:=mandoc}" : "${MANPATTERN:=*.[1-9]}" : "${debug:=1}" prog=${0##*/} version=2.4 keep=no nocontrib=no smode=no usage() { echo "usage: $prog [-ck] [-d level] {commit | staged | unstaged}" >&2 echo " $prog [-c] [-d level] -s path ..." >&2 echo " $prog -V" >&2 exit 2 } while getopts cd:ksV opt; do case $opt in d) debug=$OPTARG ;; c) nocontrib=yes ;; k) keep=yes ;; s) smode=yes ;; V) echo "$version"; exit 0 ;; *) usage ;; esac done shift $((OPTIND - 1)) if [ "$smode" = yes ]; then [ $# -ge 1 ] || usage else [ $# -eq 1 ] || usage fi case $debug in [0-3]) ;; *) echo "$prog: invalid debug level: $debug (use 0-3)" >&2; exit 2 ;; esac for cmd in "$MANDOC" file git; do if ! command -v "$cmd" > /dev/null 2>&1; then echo "$prog: $cmd: command not found" >&2 exit 2 fi done # print file names with non-ASCII characters as they are, not quoted # with octal escapes, so they still match MANPATTERN git() { command git -c core.quotePath=false "$@" } if ! top=$(git rev-parse --show-toplevel 2>/dev/null); then echo "$prog: not in a git working tree" >&2 exit 2 fi # -s: list the tracked files below the given paths, before changing the # directory, as the paths are relative to the current directory if [ "$smode" = yes ]; then for path; do if [ ! -e "$path" ]; then echo "$prog: $path: no such file or directory" >&2 exit 2 fi done files=$(git ls-files --full-name -- "$@") || exit 2 fi # git prints paths relative to the top-level directory cd "$top" || exit 2 # oldrev and newrev: a commit, INDEX or WORKTREE (see lint() below); # oldrev is empty if there is no old version, e.g. for a root commit case $smode:$1 in yes:*) info="working tree" ;; *:staged) oldrev=$(git rev-parse --verify --quiet HEAD) || oldrev= newrev=INDEX info="staged changes" changes=$(git diff --cached --name-status -M --diff-filter=ACMRT) ;; *:unstaged) oldrev=INDEX newrev=WORKTREE info="unstaged changes" changes=$(git diff --name-status --diff-filter=ACMRT) ;; *) if ! commit=$(git rev-parse --verify --quiet "$1^{commit}"); then echo "$prog: unknown commit: $1" >&2 exit 2 fi # short hash, commit date and committer, e.g. # "11a64dfa100d 2026-11-08 @wosch" for wosch@FreeBSD.org info=$(git log -1 --format='%h %cs' "$commit") committer=$(git log -1 --format='%ce' "$commit") info="$info @${committer%%@*}" # first parent; empty for a root commit oldrev=$(git rev-parse --verify --quiet "$commit^" 2>/dev/null) || oldrev= newrev=$commit if [ -n "$oldrev" ]; then changes=$(git diff --name-status -M --diff-filter=ACMRT \ "$oldrev" "$commit") else changes=$(git diff-tree -r --root --no-commit-id \ --name-status --diff-filter=ACMRT "$commit") fi ;; esac # status marks: a red cross for new warnings, or with -s for a page # that needs fixing; a green check mark if the page is lint clean, a # yellow one if warnings are left. Only on # a UTF-8 terminal and unless NO_COLOR is set; plain text in pipes and # log files. bad= ok_clean= ok_left= if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then case ${LC_ALL:-${LC_CTYPE:-${LANG:-}}} in *[Uu][Tt][Ff]-8* | *[Uu][Tt][Ff]8*) bad=$(printf '\033[31m\342\234\227\033[0m ') ok_clean=$(printf '\033[32m\342\234\223\033[0m ') ok_left=$(printf '\033[33m\342\234\223\033[0m ') ;; esac fi work=$(mktemp -d "${TMPDIR:-/tmp}/mandoc-lint.XXXXXX") || exit 2 cleanup() { if [ "$keep" = yes ]; then echo "$prog: output kept in $work" >&2 else rm -rf "$work" fi } trap cleanup EXIT trap 'exit 2' HUP INT TERM # lint rev path name dir # Extract path at rev as dir/name and run mandoc on it from within dir, # so the file name in the messages is the same for both versions, even # for a renamed file. rev is a commit, INDEX for the staged version or # WORKTREE for the file on disk. Writes dir.lint; empty if path does # not exist. A symlink in the working tree is not followed: as in git, # its content is the link target. Exits if mandoc fails to run. lint() { : > "$4.lint" || exit 2 [ -n "$1" ] || return 0 mkdir -p "$4/$(dirname -- "$3")" || exit 2 case $1 in INDEX) git show ":$2" > "$4/$3" 2>/dev/null || return 0 ;; WORKTREE) if [ -L "$2" ]; then readlink -- "$2" > "$4/$3" || return 0 else cat -- "$2" > "$4/$3" 2>/dev/null || return 0 fi ;; *) git show "$1:$2" > "$4/$3" 2>/dev/null || return 0 ;; esac # exit status 0-4: lint result; 5: bad arguments, 6: system error (cd "$4" && "$MANDOC" -T lint -- "$3" > ../"${4##*/}.lint" 2>&1) rc=$? if [ $rc -ge 5 ]; then echo "$prog: $MANDOC failed on $2 with exit status $rc:" >&2 cat -- "$4.lint" >&2 exit 2 fi return 0 } # header # Print the file name, once per manual page, before its first message. header() { [ "$shown" = no ] || return 0 shown=yes vendor_branch echo "==> $new ($info)" [ -z "$subject" ] || echo " log: $subject" case $status in A*) echo " (new file)" ;; R*) echo " (renamed from $old)" ;; esac } # vendor_branch # If the commit is on a vendor branch, e.g. a vendor import, add the # branch to info: "d3419e91c112 origin/vendor/zlib 2026-11-07 @delphij". # This takes a few seconds, so it is done only once, and only when a # header is printed. # # Also set subject to the first line of the commit message. vendor_checked=no subject= vendor_branch() { [ "$vendor_checked" = no ] || return 0 vendor_checked=yes [ -n "${commit:-}" ] || return 0 subject=$(git log -1 --format=%s "$commit") branch=$(git branch -r --contains "$commit" --list '*/vendor/*' \ 2>/dev/null | sed -n '1s/^ *//p') [ -z "$branch" ] || info="${info%% *} $branch ${info#* }" } # is_vendor path # True if path is vendor code that -c ignores. is_vendor() { case $1 in contrib/* | crypto/* | cddl/* | sys/contrib/* | external/* | gnu/*) return 0 ;; esac return 1 } # is_manpage path # True if the file name matches one of the patterns in MANPATTERN. is_manpage() { set -f # the patterns are for case, not for file globbing for pattern in $MANPATTERN; do case $1 in $pattern) set +f; return 0 ;; esac done set +f return 1 } # compare a b # Print the lines of b whose message (without line:column) does not # appear in a, counting duplicates. compare() { awk ' function norm(s) { sub(/:[0-9]+:[0-9]+:/, ":", s); return s } FILENAME == ARGV[1] { count[norm($0)]++; next } { k = norm($0); if (count[k] > 0) count[k]--; else print " " $0 } ' "$1" "$2" } n=0 pages=0 skipped=0 vendor=0 regressions=0 tab=$(printf '\t') # -s: lint status of all manual pages, then exit if [ "$smode" = yes ]; then clean=0 dirty=0 while IFS= read -r f; do is_manpage "$f" || continue # tracked, but deleted in the working tree [ -f "$f" ] || continue if [ "$nocontrib" = yes ] && is_vendor "$f"; then [ "$debug" -lt 3 ] || echo " $f: skipped, vendor code" vendor=$((vendor + 1)) continue fi n=$((n + 1)) dir=$work/$n mkdir -p "$dir" || exit 2 lint WORKTREE "$f" "$f" "$dir/new" if ! file -b "$dir/new/$f" | grep -q troff; then [ "$debug" -lt 3 ] || echo " $f: skipped, not a troff file" skipped=$((skipped + 1)) continue fi pages=$((pages + 1)) left=$(($(wc -l < "$dir/new.lint"))) if [ "$left" -eq 0 ]; then clean=$((clean + 1)) [ "$debug" -lt 3 ] || echo "${ok_clean}$f: lint clean" else dirty=$((dirty + 1)) if [ "$debug" -ge 1 ]; then echo "${bad}$f: $left warning(s)" fi if [ "$debug" -ge 2 ]; then sed 's/^/ /' "$dir/new.lint" fi fi done < $new ($info): skipped, vendor code" echo fi vendor=$((vendor + 1)) continue fi n=$((n + 1)) shown=no dir=$work/$n mkdir -p "$dir" || exit 2 echo "$new" > "$dir/name" lint "$newrev" "$new" "$new" "$dir/new" # skip files like foo.1 that are not troff, e.g. data or test input if ! file -b "$dir/new/$new" | grep -q troff; then if [ "$debug" -ge 3 ]; then echo "==> $new ($info): skipped, not a troff file" echo fi skipped=$((skipped + 1)) continue fi pages=$((pages + 1)) case $status in A*) : > "$dir/old.lint" ;; *) lint "$oldrev" "$old" "$new" "$dir/old" ;; esac added=$(compare "$dir/old.lint" "$dir/new.lint") fixed=$(compare "$dir/new.lint" "$dir/old.lint") [ -z "$added" ] || regressions=$((regressions + 1)) left=$(($(wc -l < "$dir/new.lint"))) if [ -n "$added" ] && [ "$debug" -ge 1 ]; then header echo "${bad}new warnings:" echo "$added" fi if [ -n "$fixed" ] && [ "$debug" -ge 2 ]; then header echo "fixed warnings:" echo "$fixed" if [ "$left" -eq 0 ]; then echo " ${ok_clean}manual page is now lint clean" else echo " ${ok_left}$left warning(s) left" fi fi if [ -z "$added$fixed" ] && [ "$debug" -ge 3 ]; then header if [ "$left" -eq 0 ]; then echo " ${ok_clean}lint clean" else echo " ${ok_left}no change in lint output, $left warning(s) left" fi fi [ "$shown" = no ] || echo done <