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

NAME
     pkg_version -- summarize installed versions of packages

SYNOPSIS
     pkg_version [-hv] [-l limchar] [-L limchar] [-s string] [index]
     pkg_version [-t version1 version2]

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.

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

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

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

SEE ALSO
     fetch(1), pkg_add(1), pkg_create(1), pkg_delete(1), pkg_info(1)

FILES
     /usr/ports/INDEX  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
	   ftp://ftp.FreeBSD.org/pub/FreeBSD/branches/-current/ports/INDEX

     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>

FreeBSD 5.0			  July 17, 1998 		  PKG_VERSION(1)
home | help