home | help 
PORTSCAN(1)		     General Commands Manual		     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  revi-
	     sion   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 refer-
	     enced 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 pos-
	     sible 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>

FreeBSD ports 15.quarterly     September 22, 2021		     PORTSCAN(1)
home | help