path: root/man/man8/ports.8

.Dd October 17, 2026
.Dt PORTS 8
.Os
.Sh NAME
.Nm ports
.Nd sync, list, compare and clean port collections
.Sh SYNOPSIS
.Nm
.Fl u
.Op Ar name ...
.Nm
.Fl l
.Op Ar collection ...
.Nm
.Fl d
.Op Ar collection ...
.Nm
.Fl x Ns Op Ar dfsw
.Op Ar collection ...
.Nm
.Fl h | v
.Sh DESCRIPTION
.Nm
keeps the port collections up to date and reports on them.
Collections are configured by files in
.Pa /etc/ports/
ending in
.Pa .rsync
or
.Pa .git ;
see
.Sx CONFIGURATION .
Files with any other name, such as the shipped
.Pa ports.rsync.inactive ,
are ignored.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d
Compare the port tree with the package database.
For every installed package whose port has a different
.Ar version Ns - Ns Ar release ,
print the collection, port, installed version and port version.
.It Fl h , Fl Fl help
Print a usage summary.
.It Fl l
List every port, as
.Ar collection Ns / Ns Ar port .
.It Fl u Op Ar name ...
Sync the collections from their remotes.
A
.Ar name
may be a configuration file without its extension, which syncs all of
its collections, or a collection name.
Without a
.Ar name ,
everything is synced.
Requires root.
.It Fl v , Fl Fl version
Print the version.
.It Fl x Ns Op Ar dfsw
Clean the port directories: remove package files other than the one
the port's recipe would build.
Further letters remove more:
.Bl -tag -width Ds
.It Cm d
Source archives that the recipe does not list.
.It Cm f
.Pa .footprint
files.
.It Cm s
.Pa .signature
files.
.It Cm w
.Pa work
directories.
.El
.Pp
Requires root.
.El
.Pp
.Fl l ,
.Fl d
and
.Fl x
work on every configured collection: each collection of an rsync
configuration, under its key, and each git configuration, under its
file name.
If no configuration is active they use
.Pa /ports/core ,
.Pa /usr/ports/libs ,
.Pa /usr/ports/devel ,
.Pa /usr/ports/python ,
.Pa /usr/ports/perl
and
.Pa /usr/ports/opt
instead.
Every directory in
.Pa /usr/local/ports/
is a collection as well.
Naming one or more
.Ar collection Ns s
restricts them to those.
.Pp
A directory is a port if it holds a
.Pa MAKEPKG
or a
.Pa MAKEPKG.lock .
The recipe of a port is
.Pa MAKEPKG.lock
if there is one, else
.Pa MAKEPKG ,
as for
.Xr mkpkg 8 .
.Sh SYNCING
Only the recipes and the files that belong with them are synced.
Package archives,
.Pa work/
directories and
.Pa *.lock
files are never transferred and never deleted, so locked ports keep
their lock; see
.Xr mkpkg 8 .
Neither are the sources a port downloaded: the usual archive names are
excluded outright, and every other file a recipe lists in
.Va source
is protected by name, whatever it is called.
An update never removes a download; the sources a recipe no longer
lists are removed by
.Fl xd .
File owners are not copied, and modes become 755 for directories and
644 for files.
.Pp
With rsync, a port directory that exists upstream is made identical to
it.
Nothing else in the destination is deleted by the transfer, so a
collection may live in a directory it shares with other files, such as
.Pa /usr/src .
.Pp
In a directory the collection owns, a port that upstream no longer has
is removed after the transfer, but only if its directory holds a
.Pa MAKEPKG
and no
.Pa MAKEPKG.lock ;
a locked port is kept and reported.
Other directories and files are never touched.
A port that was never upstream is indistinguishable from one upstream
dropped, so in a directory marked
.Cm shared
this pass is skipped altogether and nothing at the top level is
removed; see
.Sx CONFIGURATION .
.Pp
With git, the destination is cloned if it is not a git checkout yet,
and otherwise updated with
.Ic git pull --ff-only .
.Sh CONFIGURATION
An rsync configuration,
.Pa /etc/ports/ Ns Ar name Ns Pa .rsync ,
has
.Ar key Ns = Ns Ar value
lines:
.Bl -tag -width Ds
.It Cm host
The rsync server.
.It Cm module
The rsync module.
.It Cm token
Optional.
Used as user name and, through
.Ev RSYNC_PASSWORD ,
as password.
.It Ar collection Ns = Ns Ar directory Op Ar flag ...
Any other key is a collection: the remote directory
.Ar module Ns / Ns Ar collection Ns /
is synced into
.Ar directory .
The flags are
.Cm strict ,
the default, for a directory that belongs to the collection, where a
port upstream retired is removed, and
.Cm shared
for a directory that holds more than this collection's ports, where
nothing at the top level is ever removed.
Use
.Cm shared
for a collection syncing into
.Pa /usr/src
beside kernel trees and ports of your own.
.El
.Pp
A git configuration,
.Pa /etc/ports/ Ns Ar name Ns Pa .git ,
has
.Cm url ,
.Cm branch ,
which defaults to
.Li main ,
and
.Cm destination .
.Pp
Empty lines and lines starting with
.Ql #
are ignored.
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/ports/*.rsync , /etc/ports/*.git
Collection configuration.
.It Pa /var/lib/pkg/db
Package database, read by
.Fl d .
.El
.Sh EXIT STATUS
.Ex -std
.Fl u
fails if any collection failed to sync.
.Sh EXAMPLES
An rsync configuration with two collections:
.Bd -literal -offset indent
host=rsync.rawnix.org
module=ports
token=YOUR_TOKEN

core=/ports/core
linux=/usr/src shared
.Ed
.Pp
Sync only the
.Li core
collection:
.Pp
.Dl # ports -u core
.Sh SEE ALSO
.Xr rsync 1 ,
.Xr MAKEPKG 5 ,
.Xr bulk 8 ,
.Xr mkpkg 8