.Dd July 1, 2020
.Dt PKGIN 1
.Os
.Sh NAME
.Nm pkgin
.Nd pkgsrc binary package manager
.Sh SYNOPSIS
.Nm
.Op Fl 46dfhnPpVvy
.Op Fl c Ar chroot_path
.Op Fl l Ar limit_chars
.Op Fl t Ar log_file
.Cm command
.Op Ar package Ar
.Sh DESCRIPTION
.Nm
is a package manager for binary package sets that have been produced by
.Xr pkgsrc 7 .
.Pp
By parsing
.Xr pkg_summary 5
files stored within each configured repository, it supports
installing, upgrading, removing, and querying available packages.
.Sh OPTIONS
The following command line arguments are supported:
.Bl -tag -width 15n -offset 6n
.It Fl 4
Forces
.B pkgin
to only use IPv4 addresses.
.It Fl 6
Forces
.B pkgin
to only use IPv6 addresses.
.It Fl c Ar chroot_path
Enable chrooting
.Nm
in the given repository
.It Fl d
Download only
.It Fl f
Force database update
.It Fl h
Displays help for the command
.It Fl l Ar limit_chars
Only include the packages with the specified
.Dv STATUS FLAGS
.It Fl n
Assumes
.Dq no
as default answer and print results of actions to be taken line per line
.It Fl P
Displays packages versions instead of globs (sd, sfd, srd)
.It Fl p
Displays results in a parsable format
.It Fl t Ar log_file
Logs package browsing (dependencies and impact) to a given log file
.It Fl V
Be verbose when (un)installing
.It Fl v
Displays
.Nm
version
.It Fl y
Assumes
.Dq yes
as default answer, except for autoremove
.El
.Pp
The
.Nm
utility provides several commands:
.Bl -tag -width 12n
.It Cm autoremove
Automatically removes orphan dependencies.
When used with the
.Fl n
flag, it can be used to show packages that are possibly not necessary.
.It Cm avail
Lists all packages available in the repository.
.It Cm clean
Delete downloaded packages from the cache directory.
.It Cm export
Export the list of non-autoremovable packages to stdout (one
category/package by line).
.It Cm import Ar file
Import a list of packages to be installed from file (one
category/package by line)
.It Cm install Ar package Ns | Ns Ar glob Ar
Performs installation or upgrade of package.
If more than one packages are specified on the command-line, all will
be installed (or upgraded).
Instead of a package name, a glob can be specified in order to install
specific versions.
.Pp
Example:
.Dl pkgin install 'mysql-server>=5.6<5.7'
.It Cm keep Ar package Ar
Marks package as "non auto-removable".
A
.Cm keep Ns No -able
package is equivalent to a non-automatic package in
.Xr pkgsrc 7
terminology.
.It Cm list
Lists all packages installed locally on a system.
If the
.Fl l
modifier is added to this command, show only packages matching the
status flag.
.It Cm pkg-build-defs Ar package
Show remote package build definitions.
.It Cm pkg-content Ar package
Show remote package content.
.It Cm pkg-descr Ar package
Show remote package long-description.
.It Cm provides Ar package
Shows what a package provides to others.
.It Cm remove Ar package Ar
Removes package as well as all packages depending on it.
When more than one package are specified, they will all be
uninstalled.
By default, it will prompt you to confirm before package removals.
.It Cm requires Ar package
Shows what a package requires from other packages.
.It Cm search Ar pattern
Performs a regular expression search for the pattern
.Ar pattern
in the repository.
.It Cm show-deps Ar package
Displays all direct dependencies.
.It Cm show-full-deps Ar package
Displays all direct dependencies recursively.
.It Cm show-rev-deps Ar package
Displays all reverse direct dependencies for package.
If more than one package is specified,
.Nm
will show recursively reverse direct dependencies for all packages on
the command-line.
.It Cm show-category Ar category
Show packages belonging to
.Ar category .
.It Cm show-pkg-category Ar package
Show package category.
.It Cm show-keep
Display
.Dq non auto-removable
packages.
.It Cm show-no-keep
Display
.Dq auto-removable
packages.
.It Cm unkeep Ar package Ar
Marks package as
.Dq auto-removable .
If no other package depends on it, it will be removed when using the
.Cm autoremove
modifier.
It is equivalent to an
.Dv automatic
package in
.Xr pkgsrc 7
terminology.
.It Cm update
Creates and populates the initial database of locally installed
packages and available packages (from the remote
.Xr pkg_summary 5
list).
This is done automatically when
.Nm
is first used, when the system package database has been modified, or
when
.Nm
is upgraded to a new database version.
.It Cm upgrade
Upgrade all packages to the newest versions available in the
repository.
.El
.Sh STATUS FLAGS
When using the
.Fl l
flag along with the list command, the following status flag must be set:
.Bl -tag -width 2n
.It \&=
The installed version of the package is current.
.It \&<
The installed version of the package is older than the current
version.
.It \&>
The installed version of the package is newer than the current version.
.El
.Sh ENVIRONMENT
.Bl -tag -width 10n
.It Ev PKG_REPOS
The
.Ev PKG_REPOS
environment variable can be pointed to a suitable repository or a list
of space separated repositories in order to override
.Pa /usr/pkg/etc/pkgin/repositories.conf .
.El
.Sh FILES
.Bl -tag -width 12n
.It Pa /usr/pkg/etc/pkgin/repositories.conf
This file contains a list of repository URIs that
.Nm
will use.
It may contain macros
.Dv $arch
to define the machine hardware platform and
.Dv $osrelease
to define the release version for the operating system (as reported by
.Xr uname 1 ) .
.It Pa /usr/pkg/etc/pkgin/preferred.conf
This file contains a list of preferences regarding packages to be
installed or upgraded.
Each line defines a package preference taking the form of a simple
.Xr glob 3 ,
such as:
.Pp
.Dl autoconf=2.69.*
.Dl mysql-server<5.6
.Dl php>=5.4
.It Pa /var/db/pkgin
This directory contains the individual files and
directories used by
.Nm
listed below.
.It Pa /var/db/pkgin/cache
This directory contains the packages downloaded by
.Nm .
It is safe to empty it if necessary by running:
.Pp
.Dl # pkgin clean
.It Pa /var/db/pkgin/pkgin.db
This is the main
.Nm pkgin
sqlite database.
This format has been chosen in order to parse, query, match and order
packages using the SQL language thus making packages list manipulation
a lot easier.
.It Pa /var/db/pkgin/pkg_install-err.log
This file contains errors and warnings given by
.Xr pkg_add 1
and
.Xr pkg_delete 1 ,
which are the tools called by
.Nm
to manipulate packages themselves.
.It Pa /var/db/pkgin/sql.log
This file contains SQL errors that might have occurred on a sqlite
query.
Mainly for debugging purposes.
.El
.Sh EXAMPLES
Setup the initial database:
.Pp
.Dl # vi /usr/pkg/etc/pkgin/repositories.conf
.Dl https://cdn.netbsd.org/pub/pkgsrc/packages/NetBSD/$arch/9.0/All
.Pp
.Dl # pkgin update
.Pp
Listing all packages available in the repository:
.Pp
.Dl # pkgin avail
.Pp
Search for specific packages:
.Pp
.Dl # pkgin search '^abook|lbdb|mutt|xlhtml'
.Dl abook-0.6.1          Text-based addressbook program
.Dl lbdb-0.48.1nb1       The little brother's database
.Dl mutt-1.14.5 =        Text-based MIME mail client with PGP & S/MIME support
.Dl xlhtml-0.5nb2        Microsoft xls/ppt to HTML converter
.Pp
.Dl # pkgin search '^php-'
.Dl php-7.4.7            PHP Hypertext Preprocessor version 7.4
.Dl php-7.3.19           PHP Hypertext Preprocessor version 7.3
.Dl php-7.2.31nb1        PHP Hypertext Preprocessor version 7.2
.Dl php-5.6.40nb3        PHP Hypertext Preprocessor version 5.6
.Dl php-mode-1.13.1      PHP editing mode for Emacs
.Pp
Install packages and their dependencies:
.Pp
.Dl # pkgin install abook lbdb mutt xlhtml
.Pp
.Dl # pkgin install 'php>=7.3<7.4'
.Pp
Upgrade all packages:
.Pp
.Dl # pkgin upgrade
.Pp
Remove packages and their reverse dependencies:
.Pp
.Dl # pkgin remove mutt
.Pp
Remove orphaned dependencies:
.Pp
.Dl # pkgin autoremove
.Sh SEE ALSO
.Xr pkg_add 1 ,
.Xr pkg_info 1 ,
.Xr pkg_summary 5 ,
.Xr pkgsrc 7
.Sh AUTHORS
.Bl -tag -width 25n
.It Emile Ao iMil Ac Heitor
Initial work and ongoing development.
.It Jonathan Perkin
Primary maintainer 0.9.0 onwards.
.El
.Sh CONTRIBUTORS
.Bl -tag -width 25n
.It Jeremy C. Reed
Testing and refinements.
.It Arnaud Ysmal
Tests and patches
.It Claude Charpentier
SQLite schema, and SQL queries debugging.
.It Guillaume Lasmayous
Man page
.It Antonio Huete Jimenez
.Dx
port
.It Min Sik Kim
Darwin port
.It Filip Hajny
SunOS port
.It Baptiste Daroussin
.Fx
port and patches
.It Gautam B.T.
MINIX port
.It Thomas Ao wiz Ac Klausner
Testing and refinements.
.It Youri Ao yrmt Ac Mouton
OSX testing and patches
.El
.Sh BUGS
We're hunting them.