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

NAME
     pkg_version -- summarize installed versions of packages

SYNOPSIS
     pkg_version [-hIoqv] [-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-6).  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.

     -L      Limit the output to those packages whose status flag does not 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.

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

     -O      Only list packages whose registered origin is origin.

     -q      Enable  quiet  output.  Quiet output precludes printing the limchar
	     when used with -l or -L.  This is useful when used as the input  to
	     portupgrade(8).

     -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-6 is used.

FILES
     /usr/ports/INDEX-6  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-6

     The following command compares two package version strings:

	   % pkg_version -t 1.5 1.5.1

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),  portup-
     grade(8)

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 6.0			  Jul 27, 2005			  PKG_VERSION(1)

home | help