NAME
pkg_version — summarize installed versions of packages
SYNOPSIS
pkg_version [−hv] [−l limchar] [−L limchar] [
[−X] −s string ] [index]
pkg_version
[−t version1 version2]
pkg_version
[−T pkgname pattern]
DESCRIPTION
The pkg_version command is used to produce a report of non-base software packages installed using the pkg_add(1) command.
Each package’s version number is checked against one of two sources to see if that package may require updating. If the package contains information about its origin in the FreeBSD ports tree, and a version number can be determined from the port’s Makefile, then the version number from the Makefile will be used to determine whether the installed package is up-to-date or requires updating.
If no origin for a package can be found, or if the port’s Makefile cannot be located, pkg_version will search for the package in the ports collection index file (typically /usr/ports/INDEX-5). Any matching version number(s) there will be used to determine whether the installed package is up-to-date or requires updating.
Generally, using the version number from a port’s Makefile will provide a more accurate result, since, unlike the index file, it provides an unambiguous current version number, even when multiple versions of a port exist in the ports collection. Moreover, the ports collection index file is only updated at intervals, meaning that it may not completely reflect the version numbers of the software contained in the ports collection.
Each package name is printed, along with a one-character status flag:
=
The installed version of the package is current.
<
The installed version of the package is older than the current version.
>
The installed version of the package is newer than the current version. This situation can arise with an out-of-date index file, or when testing new ports.
?
The installed package does not appear in the index. This could be due to an out of date index or a package taken from a PR that has not yet been committed.
*
There are multiple versions of a particular software package listed in the index file. Examples from the FreeBSD ports collection are the Tcl toolkit or the EMACS editor.
!
The installed package exists in the index but for some reason, pkg_version was unable to compare the version number of the installed package with the corresponding entry in the index.
OPTIONS
The pkg_version utility supports several command-line arguments:
−h
Print help message.
−l
Limit the output to those packages whose status flag matches the character(s) in limchar. More than one character can be specified in limchar. Note that because some of the status flag characters are also special to the shell, it is best to quote limchar with single quotes.
−L
Limit the output to those packages whose status flag doesn’t match limchar. You may specify more than one character to match in limchar. Note that because some of the status flag characters are also special to the shell, it is best to quote limchar with single quotes.
−s
Limit the output to those packages whose names match a given string.
−X
Interpret string as a extended regular expression.
−t
Test a pair of version number strings and exit. The output consists of one of the single characters = (equal), < (right-hand number greater), or > (left-hand number greater) on standard output. This flag is mostly useful for scripts or for testing.
−T
Test whether pkgname is matched by pattern and set the exit code accordingly. −T can also be used in ’filter mode’: When one of the arguments is ’-’, standard input is used, and lines with matching package names/patterns are echoed to standard output.
−v
Enable verbose output. Verbose output includes some English-text interpretations of the version number comparisons, as well as the version numbers compared for each package. Non-verbose output is probably easier for programs or scripts to parse.
index
Specify the index to be used as a basis of comparison. This index can be specified as a filename (in the local file system) or a URL. Any URL understandable by fetch(1) can be used here. If no index file is specified on the command line, /usr/ports/INDEX-5 is used.
COMPATIBILITY
The −c option has been deprecated and is no longer supported.
SEE ALSO
fetch(1), pkg_add(1), pkg_create(1), pkg_delete(1), pkg_info(1)
FILES
/usr/ports/INDEX-5
Default index file.
EXAMPLES
The following is a typical invocation of the pkg_version command, which checks the installed packages against the local ports index file:
% pkg_version -v
The command below generates a report against the version numbers in the on-line ports collection:
% pkg_version http://www.FreeBSD.org/ports/INDEX-5
The following command compares two package version strings:
% pkg_version -t 1.5 1.5.1
AUTHORS
The pkg_version utility
was written by Jeremy D. Lea <reg [AT] FreeBSD.org>,
partially based on a Perl script written by
Bruce A. Mah <bmah [AT] FreeBSD.org>.
CONTRIBUTORS
Nik Clayton <nik [AT] FreeBSD.org>, Dominic Mitchell <dom [AT] palmerharvey.uk>, Mark Ovens <marko [AT] FreeBSD.org>, Doug Barton <DougB [AT] gorean.org>, Akinori MUSHA <knu [AT] FreeBSD.org>, Oliver Eikemeier <eik [AT] FreeBSD.org>
BSD June 29, 2004 BSD