PORTSCAN(1)

NAME
portscan - scan the FreeBSD Ports Collection

SYNOPSIS
portscan [-l logdir] [-p portsdir] [-q regexp] [--categories] [--clones] [--comments] [--option-default-descriptions[=editdist]] [--options] [--progress[=interval]] [--strict] [--unknown-targets] [--unknown-variables] [--variable-values[=regex]] [origin ...]

DESCRIPTION
portscan scans the FreeBSD Ports Collection for common mistakes.

The entire collection is scanned if no port origins are given.

The following options are available:

-l logdir
    Save the log result into logdir instead of outputting to stdout. The log files will be dated and will include the current SVN revision or Git commit hash of portsdir. portscan creates portscan-latest.log and portscan-previous.log symlinks to point to the latest or previous results.

-p portsdir
    The port directory to scan. If not specified defaults to /usr/ports or the value of PORTSDIR in the environment.

-q regexp
    Filter returned values based on the given regular expressions.

--categories
    Check categories for unhooked, wrong, or misordered entries.

--clones
    Check for variables that are set twice.

--comments
    Check comments for problems. Currently checks for commented PORTREVISION or PORTEPOCH lines.

--option-default-descriptions[=editdist]
    Report redundant option descriptions. It checks them against the default descriptions in Mk/bsd.options.desc.mk. editdist is the edit distance between the default and port option description. It defaults to 3.

--options
    Include port options and option groups in the result. Use -q to filter the options.

--progress[=interval]
    Print regular progress reports. They are printed to stderr every interval seconds. interval defaults to 1 second. This option is enabled by default when stderr is a valid terminal type device. Use an interval of 0 to disable this. portscan will print progress reports when it receives SIGINFO or SIGUSR2.

--strict
    For unknown variables do not check if they are referenced elsewhere in the Makefile and always report them. Without this option referenced but otherwise unknown variables will be ignored.

--unknown-targets
    Scan for unknown or unrecognized targets.

--unknown-variables
    Scan for unknown or unrecognized variables.

--variable-values[=regex]
    Output variable values. If unconstrained this will output the value of every variable one by one. Use -q to filter the values and regex to select only a subset of all variables.

portscan will default to --categories, --clones, --comments, --option-default-descriptions, --unknown-targets, and --unknown-variables if no check was specified.

OUTPUT
The output is composed of whitespace delimited fields type, origin, name. type is made up of the following characters:

#   Problematic comment

C   Unsorted category Makefile

Ce  Nonexistent port referenced by category Makefile

Cu  Unhooked port missing in category Makefile

E   Parser or IO errors encountered during the scan

OD  Redundant port option description that matches the default one

OG  Port option group

O   Port option

V   Unknown variable

Vc  Variable that is set twice or more

Vv  Variable value

T   Unknown target

origin is the origin of the variable or target.

name is the variable or target name. name might contain whitespace as part of its value. name never starts with whitespace. Any tools that consumes portscan output should keep this in mind.

ENVIRONMENT
The following environment variables affect the execution of portscan:

PORTSDIR
    The ports directory to operate on if -p is not specified.

EXIT STATUS
portscan will exit with one of the following values:

0   The collection was scanned successfully. An exit status of 0 does not mean there were no issues in the scanned ports.

1   An error occurred.

2   There were no changes when compared to previous results. Only possible when -l was passed to portscan.

EXAMPLES
The output can have many lines (approximately 12000 lines at the time of writing) and will have many false positives. To not be overwhelmed it is best to run portscan daily in an iterative manner and compare the results with diff(1) to flag new problems:

    portscan -l .
    diff -u portscan-previous.log portscan-latest.log

Scan category Makefiles for mistakes:

    portscan --categories

SEE ALSO
portclippy(1), portedit(1), portfmt(1)

AUTHORS
Tobias Kortkamp <tobik@FreeBSD.org>