Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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	 soft-
       ware 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  in-
       formation  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 in-
       stalled package is up-to-date or	requires updating.

       If no origin for	a package can be found,	or if the port's Makefile can-
       not be located, pkg_version will	search for the package	in  the	 ports
       collection  index  file	(typically  /usr/ports/INDEX-8).  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 in-
       dex file	is only	updated	at intervals, meaning that  it	may  not  com-
       pletely	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 col-
	       lection 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, --help
	       Print help message.

       -I, --index-only
	       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	incor-
	       rect result if the index	file is	out of date.

       -l, --status limchar
	       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, --no-status limchar
	       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-origin
	       Show  the  origin recorded on package generation	instead	of the
	       package name.

       -O, --origin origin
	       Only list packages whose	registered origin is origin.

       -q, --quiet
	       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, --match string
	       Limit the output	to those packages whose	names  match  a	 given
	       string.

       -X, --extended
	       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 stan-
	       dard 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-8 is used.

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

       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),
       portupgrade(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	7.1			 May 30, 2008			PKG_VERSION(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pkg_version&manpath=FreeBSD+7.1-RELEASE>

home | help