.\"
.\" FreeBSD pkg - a next generation package for the installation and maintenance
.\" of non-core utilities.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\"
.\" @(#)pkg.8
.\"
.Dd July 7, 2024
.Dt PKG-VERSION 8
.Os
.Sh NAME
.Nm "pkg version"
.Nd summarize installed versions of packages
.Sh SYNOPSIS
.Nm
.Op Fl IPR
.Op Fl hoqvU
.Op Fl l Ar limchar
.Op Fl L Ar limchar
.Op Fl Cegix Ar pattern
.Op Fl r Ar reponame
.Op Fl O Ar origin | Fl n Ar pkgname
.Op Ar index
.Nm
.Fl t Ar version1 Ar version2
.Nm
.Fl T Ar pkgname Ar pattern
.Pp
.Nm
.Op Fl -{index,ports,remote}
.Op Fl -{help,origin,quiet,verbose,no-repo-update}
.Op Fl -like Ar limchar
.Op Fl -not-like Ar limchar
.Op Fl -{case-sensitive,exact,glob,case-insensitive,regex} Ar pattern
.Op Fl -repository Ar reponame
.Op Fl -match-origin Ar origin
.Op Ar index
.Nm
.Fl -test-version Ar version1 Ar version2
.Nm
.Fl -test-pattern Ar pkgname Ar pattern
.Sh DESCRIPTION
.Nm
is used for generating a report of packages installed by
.Xr pkg 8 .
.Pp
The database of available packages and versions to compare against the
installed packages may be chosen by specifying one of
.Fl P ,
.Fl R
or
.Fl I
or by setting
.Cm VERSION_SOURCE
in
.Xr pkg.conf 5 .
If not specified then the ports index file
will be used if it exists
.Fl ( I ) .
Otherwise, should a ports tree exist that will be used to compare
versions
.Fl ( P ) .
Failing either of those two choices, the repository catalogue will be
used
.Fl ( R ) .
.Pp
When
.Fl I
is used, versions of installed packages will be compared to the
versions listed in the file argument
.Ar index ,
or if that is not given explicitly, in the default ports index file
(typically located as
.Pa /usr/ports/INDEX-N ,
where
.Sy N
is the OS major version number.)
.Pp
When
.Fl R
is used,
package repository catalogues will be automatically updated whenever
.Nm
is run by a user ID with write access to the package database,
unless disabled by the
.Fl U
flag or setting
.Cm REPO_AUTOUPDATE
to
.Sy NO
in
.Xr pkg.conf 5 .
.Pp
When comparing package versions the package name and a comparison character are printed:
.Bl -tag -width indent
.It Li =
The installed version of the package is current.
.It Li \&<
The installed version of the package is older than the current version.
.It Li \&>
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.
.It Li \&?
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.
.It Li \&!
The installed package exists in the index but for some reason,
.Nm
was unable to compare the version number of the installed package
with the corresponding entry in the index.
.El
.Sh OPTIONS
The following options are supported by
.Nm :
.Bl -tag -width repository
.It Fl C , Fl -case-sensitive
Make the standard or the regular expression
.Fl ( x )
matching against
.Ar pkg-name
case sensitive.
.It Fl h , Fl -help
Displays usage information.
.It Fl I Oo Ar index Oc , Fl -index Oo Ar index Oc
Use
.Pa index
file for determining if a package is out of date.
If no
.Pa index
file name is specified, uses the default index file.
This is the default, if the index file exists.
.It Fl P , Fl -ports
Use ports for determining if a package is out of date.
This is the default if the index file is not present and a ports tree
exists.
The tree used can be overridden by PORTSDIR, see
.Xr pkg.conf 5
for more information.
.It Fl R , Fl -remote
Use repository catalogue for determining if a package is out of date.
This is the default if neither the ports index nor the ports tree
exists.
.It Fl U , Fl -no-repo-update
Suppress the automatic update of the local copy of the repository catalogue
from remote.
This only has any effect in combination with the
.Fl R
option.
Automatic repository catalogue updates are only attempted when the
effective UID of the process has write access to the package database.
Otherwise they are silently ignored.
.It Fl r Ar reponame , Fl -repository Ar reponame
Compare installed package versions to packages available from the
named repository only, irrespective of the configured
.Dq enabled
status from
.Pa repo.conf .
By default, catalogues for all enabled repositories are used for
version comparisons.
Implies
.Fl R .
.It Fl o , Fl -origin
Display package origin, instead of package name.
.It Fl q , Fl -quiet
Be quiet.
Less output will be produced.
.It Fl v , Fl -verbose
Be verbose.
.It Fl l Ar limchar , Fl -like Ar limchar
Display only the packages which status flag matches the one specified by
.Ar limchar .
.It Fl L Ar limchar , Fl -not-like Ar limchar
Does the opposite of
.Fl l
flag.
Displays the packages which status flag does not match the one
specified by
.Ar limchar .
.It Fl i , Fl -case-insensitive
Make the exact
.Fl ( e )
or regular expression
.Fl ( x )
matching against
.Ar pattern
case insensitive.
This is the default, unless modified by setting
.Ev CASE_SENSITIVE_MATCH
to true in
.Pa pkg.conf .
.It Fl x Ar pattern , Fl -regex Ar pattern
Only display the packages that match the regular expression.
Uses the "modern" or "extended" syntax of
.Xr re_format 7 .
.It Fl g Ar pattern , Fl -glob Ar pattern
Only display the packages that match the glob expression.
.It Fl e Ar string , Fl -exact Ar string
Only display the packages that exactly match the string.
.It Fl O Ar origin , Fl -match-origin Ar origin
Display only the packages which origin matches
.Ar origin .
.It Fl n Ar pkgname , Fl -match-name Ar pkgname
Display only the packages which name matches
.Ar pkgname .
.It Fl t Ar version1 Ar version2 , Fl -test-version Ar version1 Ar version2
Test a pair of version number strings and exit.
The output consists of one of the single characters
.Li =
(equal),
.Li \&<
(right-hand number greater), or
.Li \&>
(left-hand number greater) on standard output.
This flag is mostly useful for scripts or for testing.
.It Fl T Ar pkgname Ar pattern , Fl -test-pattern Ar pkgname Ar pattern
Compare
.Ar pkgname
against shell glob
.Ar pattern
and set exit code accordingly.
.Fl 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.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
See
.Xr pkg.conf 5
for further description.
.Bl -tag -width ".Ev NO_DESCRIPTIONS"
.It Ev CASE_SENSITIVE_MATCH
.It Ev INDEXDIR
.It Ev INDEXFILE
.It Ev PKG_DBDIR
.It Ev PORTSDIR
.El
.Pp
The default
.Pa index
file is searched for in
.Ev INDEXDIR ,
or if that is not set,
.Ev PORTSDIR .
.Ev INDEXFILE
is the name of the
.Pa index
relative to that directory.
If
.Ev INDEXFILE
is not set, the default file name is
.Pa INDEX-N
where
.Cm N
is the OS major version number.
.Sh FILES
See
.Xr pkg.conf 5 .
.Sh EXAMPLES
The following is a typical invocation of the
.Nm
command, which checks the installed packages against the local ports
index file:
.Pp
.Dl % pkg version -v
.Pp
The command below generates a report against the versions in the repository catalogue:
.Pp
.Dl % pkg update
.Dl % pkg version -vR
.Pp
The following lists packages needing upgrade, compared to the repository catalogue:
.Pp
.Dl % pkg update
.Dl % pkg version -vRL=
.Pp
The following command compares two package version strings:
.Pp
.Dl % pkg version -t 1.5 1.5.1
.Sh SEE ALSO
.Xr pkg_create 3 ,
.Xr pkg_printf 3 ,
.Xr pkg_repo_create 3 ,
.Xr pkg_repos 3 ,
.Xr pkg-keywords 5 ,
.Xr pkg-lua-script 5 ,
.Xr pkg-repository 5 ,
.Xr pkg-script 5 ,
.Xr pkg-triggers 5 ,
.Xr pkg.conf 5 ,
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-alias 8 ,
.Xr pkg-annotate 8 ,
.Xr pkg-audit 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-check 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-config 8 ,
.Xr pkg-create 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-key 8 ,
.Xr pkg-lock 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-repositories 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-search 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-ssh 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-triggers 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-which 8
