home | help
PKG_VERSION(1)		     General Commands Manual		  PKG_VERSION(1)

NAME
     pkg_version -- summarize installed versions of packages

SYNOPSIS
     pkg_version [-hIov] [-l limchar] [-L limchar] [[-X] -s string] [-O origin]
		 [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 de-
     termined 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 unam-
     biguous 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  ver-
     sion 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 ver-
	     sion.

     >	     The installed version of the package is newer than the current ver-
	     sion.   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  in-
	     stalled package with the corresponding entry in the index.

OPTIONS
     The pkg_version utility supports several command-line arguments:

     -h      Print help message.

     -I      Use  only	the  index  file  for determining if a package is out of
	     date.  This is much faster than using the	version  number  from  a
	     port's  Makefile, at the expense of potentially giving an incorrect
	     result if the index file is out of date.

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

     -o      Show the origin recorded on package generation instead of the pack-
	     age name.

     -O      Only list packages whose registered origin is origin.

     -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 con-
	     sists of one of the single characters = (equal), < (right-hand num-
	     ber 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@FreeBSD.org>,
     partially based on a Perl script written by
     Bruce A. Mah <bmah@FreeBSD.org>.

CONTRIBUTORS
     Nik Clayton <nik@FreeBSD.org>, Dominic  Mitchell  <dom@palmerharvey.co.uk>,
     Mark  Ovens  <marko@FreeBSD.org>,	Doug  Barton <DougB@gorean.org>, Akinori
     MUSHA <knu@FreeBSD.org>, Oliver Eikemeier <eik@FreeBSD.org>

FreeBSD 5.5			  Jul 27, 2005			  PKG_VERSION(1)

home | help