1  .\"
  2  .\" FreeBSD pkg - a next generation package for the installation and maintenance
  3  .\" of non-core utilities.
  4  .\"
  5  .\" Redistribution and use in source and binary forms, with or without
  6  .\" modification, are permitted provided that the following conditions
  7  .\" are met:
  8  .\" 1. Redistributions of source code must retain the above copyright
  9  .\"    notice, this list of conditions and the following disclaimer.
 10  .\" 2. Redistributions in binary form must reproduce the above copyright
 11  .\"    notice, this list of conditions and the following disclaimer in the
 12  .\"    documentation and/or other materials provided with the distribution.
 13  .\"
 14  .\"
 15  .\"     @(#)pkg.8
 16  .\"
 17  .Dd July 7, 2024
 18  .Dt PKG-VERSION 8
 19  .Os
 20  .Sh NAME
 21  .Nm "pkg version"
 22  .Nd summarize installed versions of packages
 23  .Sh SYNOPSIS
 24  .Nm
 25  .Op Fl IPR
 26  .Op Fl hoqvU
 27  .Op Fl l Ar limchar
 28  .Op Fl L Ar limchar
 29  .Op Fl Cegix Ar pattern
 30  .Op Fl r Ar reponame ...
 31  .Op Fl O Ar origin | Fl n Ar pkgname
 32  .Op Ar index
 33  .Nm
 34  .Fl t Ar version1 Ar version2
 35  .Nm
 36  .Fl T Ar pkgname Ar pattern
 37  .Pp
 38  .Nm
 39  .Op Fl -{index,ports,remote}
 40  .Op Fl -{help,origin,quiet,verbose,no-repo-update}
 41  .Op Fl -like Ar limchar
 42  .Op Fl -not-like Ar limchar
 43  .Op Fl -{case-sensitive,exact,glob,case-insensitive,regex} Ar pattern
 44  .Op Fl -repository Ar reponame ...
 45  .Op Fl -match-origin Ar origin
 46  .Op Ar index
 47  .Nm
 48  .Fl -test-version Ar version1 Ar version2
 49  .Nm
 50  .Fl -test-pattern Ar pkgname Ar pattern
 51  .Sh DESCRIPTION
 52  .Nm
 53  is used for generating a report of packages installed by
 54  .Xr pkg 8 .
 55  .Pp
 56  The database of available packages and versions to compare against the
 57  installed packages may be chosen by specifying one of
 58  .Fl P ,
 59  .Fl R
 60  or
 61  .Fl I
 62  or by setting
 63  .Cm VERSION_SOURCE
 64  in
 65  .Xr pkg.conf 5 .
 66  If not specified then the ports index file
 67  will be used if it exists
 68  .Fl ( I ) .
 69  Otherwise, should a ports tree exist that will be used to compare
 70  versions
 71  .Fl ( P ) .
 72  Failing either of those two choices, the repository catalogue will be
 73  used
 74  .Fl ( R ) .
 75  .Pp
 76  When
 77  .Fl I
 78  is used, versions of installed packages will be compared to the
 79  versions listed in the file argument
 80  .Ar index ,
 81  or if that is not given explicitly, in the default ports index file
 82  (typically located as
 83  .Pa /usr/ports/INDEX-N ,
 84  where
 85  .Sy N
 86  is the OS major version number.)
 87  .Pp
 88  When
 89  .Fl R
 90  is used,
 91  package repository catalogues will be automatically updated whenever
 92  .Nm
 93  is run by a user ID with write access to the package database,
 94  unless disabled by the
 95  .Fl U
 96  flag or setting
 97  .Cm REPO_AUTOUPDATE
 98  to
 99  .Sy NO
100  in
101  .Xr pkg.conf 5 .
102  .Pp
103  When comparing package versions the package name and a comparison character are printed:
104  .Bl -tag -width indent
105  .It Li =
106  The installed version of the package is current.
107  .It Li \&<
108  The installed version of the package is older than the current version.
109  .It Li \&>
110  The installed version of the package is newer than the current version.
111  This situation can arise with an out of date index file, or when
112  testing new ports.
113  .It Li \&?
114  The installed package does not appear in the index.
115  This could be due to an out of date index or a package taken from a PR
116  that has not yet been committed.
117  .It Li \&!
118  The installed package exists in the index but for some reason,
119  .Nm
120  was unable to compare the version number of the installed package
121  with the corresponding entry in the index.
122  .El
123  .Sh OPTIONS
124  The following options are supported by
125  .Nm :
126  .Bl -tag -width repository
127  .It Fl C , Fl -case-sensitive
128  Make the standard or the regular expression
129  .Fl ( x )
130  matching against
131  .Ar pkg-name
132  case sensitive.
133  .It Fl h , Fl -help
134  Displays usage information.
135  .It Fl I Oo Ar index Oc , Fl -index Oo Ar index Oc
136  Use
137  .Pa index
138  file for determining if a package is out of date.
139  If no
140  .Pa index
141  file name is specified, uses the default index file.
142  This is the default, if the index file exists.
143  .It Fl P , Fl -ports
144  Use ports for determining if a package is out of date.
145  This is the default if the index file is not present and a ports tree
146  exists.
147  The tree used can be overridden by PORTSDIR, see
148  .Xr pkg.conf 5
149  for more information.
150  .It Fl R , Fl -remote
151  Use repository catalogue for determining if a package is out of date.
152  This is the default if neither the ports index nor the ports tree
153  exists.
154  .It Fl U , Fl -no-repo-update
155  Suppress the automatic update of the local copy of the repository catalogue
156  from remote.
157  This only has any effect in combination with the
158  .Fl R
159  option.
160  Automatic repository catalogue updates are only attempted when the
161  effective UID of the process has write access to the package database.
162  Otherwise they are silently ignored.
163  .It Fl r Ar reponame , Fl -repository Ar reponame
164  Compare installed package versions to packages available from the
165  named repository only.
166  This option can be specified multiple times to use several repositories.
167  Packages will be compared against the named repositories only, irrespective of the configured
168  .Dq enabled
169  status from
170  .Pa repo.conf .
171  By default, catalogues for all enabled repositories are used for
172  version comparisons.
173  Implies
174  .Fl R .
175  .It Fl o , Fl -origin
176  Display package origin, instead of package name.
177  .It Fl q , Fl -quiet
178  Be quiet.
179  Less output will be produced.
180  .It Fl v , Fl -verbose
181  Be verbose.
182  .It Fl l Ar limchar , Fl -like Ar limchar
183  Display only the packages which status flag matches the one specified by
184  .Ar limchar .
185  .It Fl L Ar limchar , Fl -not-like Ar limchar
186  Does the opposite of
187  .Fl l
188  flag.
189  Displays the packages which status flag does not match the one
190  specified by
191  .Ar limchar .
192  .It Fl i , Fl -case-insensitive
193  Make the exact
194  .Fl ( e )
195  or regular expression
196  .Fl ( x )
197  matching against
198  .Ar pattern
199  case insensitive.
200  This is the default, unless modified by setting
201  .Ev CASE_SENSITIVE_MATCH
202  to true in
203  .Pa pkg.conf .
204  .It Fl x Ar pattern , Fl -regex Ar pattern
205  Only display the packages that match the regular expression.
206  Uses the "modern" or "extended" syntax of
207  .Xr re_format 7 .
208  .It Fl g Ar pattern , Fl -glob Ar pattern
209  Only display the packages that match the glob expression.
210  .It Fl e Ar string , Fl -exact Ar string
211  Only display the packages that exactly match the string.
212  .It Fl O Ar origin , Fl -match-origin Ar origin
213  Display only the packages which origin matches
214  .Ar origin .
215  .It Fl n Ar pkgname , Fl -match-name Ar pkgname
216  Display only the packages which name matches
217  .Ar pkgname .
218  .It Fl t Ar version1 Ar version2 , Fl -test-version Ar version1 Ar version2
219  Test a pair of version number strings and exit.
220  The output consists of one of the single characters
221  .Li =
222  (equal),
223  .Li \&<
224  (right-hand number greater), or
225  .Li \&>
226  (left-hand number greater) on standard output.
227  This flag is mostly useful for scripts or for testing.
228  .It Fl T Ar pkgname Ar pattern , Fl -test-pattern Ar pkgname Ar pattern
229  Compare
230  .Ar pkgname
231  against shell glob
232  .Ar pattern
233  and set exit code accordingly.
234  .Fl T
235  can also be used in `filter mode':
236  When one of the arguments is `-', standard input is used, and lines
237  with matching package names/patterns are echoed to standard output.
238  .El
239  .Sh ENVIRONMENT
240  The following environment variables affect the execution of
241  .Nm .
242  See
243  .Xr pkg.conf 5
244  for further description.
245  .Bl -tag -width ".Ev NO_DESCRIPTIONS"
246  .It Ev CASE_SENSITIVE_MATCH
247  .It Ev INDEXDIR
248  .It Ev INDEXFILE
249  .It Ev PKG_DBDIR
250  .It Ev PORTSDIR
251  .El
252  .Pp
253  The default
254  .Pa index
255  file is searched for in
256  .Ev INDEXDIR ,
257  or if that is not set,
258  .Ev PORTSDIR .
259  .Ev INDEXFILE
260  is the name of the
261  .Pa index
262  relative to that directory.
263  If
264  .Ev INDEXFILE
265  is not set, the default file name is
266  .Pa INDEX-N
267  where
268  .Cm N
269  is the OS major version number.
270  .Sh FILES
271  See
272  .Xr pkg.conf 5 .
273  .Sh EXAMPLES
274  The following is a typical invocation of the
275  .Nm
276  command, which checks the installed packages against the local ports
277  index file:
278  .Pp
279  .Dl % pkg version -v
280  .Pp
281  The command below generates a report against the versions in the repository catalogue:
282  .Pp
283  .Dl % pkg update
284  .Dl % pkg version -vR
285  .Pp
286  The following lists packages needing upgrade, compared to the repository catalogue:
287  .Pp
288  .Dl % pkg update
289  .Dl % pkg version -vRL=
290  .Pp
291  The following command compares two package version strings:
292  .Pp
293  .Dl % pkg version -t 1.5 1.5.1
294  .Sh SEE ALSO
295  .Xr pkg_create 3 ,
296  .Xr pkg_printf 3 ,
297  .Xr pkg_repo_create 3 ,
298  .Xr pkg_repos 3 ,
299  .Xr pkg-keywords 5 ,
300  .Xr pkg-lua-script 5 ,
301  .Xr pkg-repository 5 ,
302  .Xr pkg-script 5 ,
303  .Xr pkg-triggers 5 ,
304  .Xr pkg.conf 5 ,
305  .Xr pkg 8 ,
306  .Xr pkg-add 8 ,
307  .Xr pkg-alias 8 ,
308  .Xr pkg-annotate 8 ,
309  .Xr pkg-audit 8 ,
310  .Xr pkg-autoremove 8 ,
311  .Xr pkg-check 8 ,
312  .Xr pkg-clean 8 ,
313  .Xr pkg-config 8 ,
314  .Xr pkg-create 8 ,
315  .Xr pkg-delete 8 ,
316  .Xr pkg-fetch 8 ,
317  .Xr pkg-help 8 ,
318  .Xr pkg-info 8 ,
319  .Xr pkg-install 8 ,
320  .Xr pkg-key 8 ,
321  .Xr pkg-lock 8 ,
322  .Xr pkg-plugins 8 ,
323  .Xr pkg-query 8 ,
324  .Xr pkg-register 8 ,
325  .Xr pkg-repo 8 ,
326  .Xr pkg-repositories 8 ,
327  .Xr pkg-rquery 8 ,
328  .Xr pkg-search 8 ,
329  .Xr pkg-set 8 ,
330  .Xr pkg-shell 8 ,
331  .Xr pkg-shlib 8 ,
332  .Xr pkg-ssh 8 ,
333  .Xr pkg-stats 8 ,
334  .Xr pkg-triggers 8 ,
335  .Xr pkg-unregister 8 ,
336  .Xr pkg-update 8 ,
337  .Xr pkg-updating 8 ,
338  .Xr pkg-upgrade 8 ,
339  .Xr pkg-which 8