Documentation/man1/prtwash.1

.TH prtwash 1 "May 28, 2022" "prtwash 1.2.1" ""
.SH NAME
\fBprtwash \fP- a script to clean the port dirs in CRUX.
\fB
.SH SYNOPSIS
.nf
.fam C
\fBprtwash\fP [-p] [-b] [-d] [-s] [-t] [-q] [-a] <path> [<path> ...]
.fam T
.fi
.SH DESCRIPTION
\fBprtwash\fP is a perl script to clean the ports tree of a CRUX
distribution. You can clean a single directory, multiple directories,
or the entire ports tree. With the given options it is possible to
choose what kind of files the program should delete.
A test mode is provided.
.PP
\fBprtwash\fP was inspired by Martin Opel's prtsweep script.
.SH OPTIONS
By default prtwash will NOT delete the following items
in a port directory:
.IP \(bu 3
The Pkgfile
.IP \(bu 3
The sources (as stated in the Pkgfile)
.IP \(bu 3
The built package
.IP \(bu 3
The .signature, .footprint, .32bit and .nostrip files
.IP \(bu 3
Additional files: README, FAQ, pre-install, post-install
.PP
All items not included in the previous list WILL be deleted
(e.g.: the 'work' dir of pkgmk, if present).
.PP
You can choose to delete some of the above by passing the proper
option:
.TP
.B \-p
remove the built package (current version)
.TP
.B \-b
remove older builds (any package tarball that does NOT match
the current version)
.TP
.B \-d
remove add-on files provided by CRUX maintainers
(patches and initscripts downloaded with \fBports -u\fP)
.TP
.B \-s
remove upstream sources (those NOT obtained via \fBports -u\fP)
.TP
.B \-t
(test mode) display the target files without deleting
.TP
.B \-q
(quiet mode) suppress messages about files that are kept;
basically the same as \fBprtwash [OPTIONS] | grep -v "keeping"\fP
.TP
.B \-a
(automatic mode) take the port collections from the
/etc/prt-get.conf file and do a recursive cleaning;
if omitted, the command line must contain at least one <path> specifying
a valid port directory
.PP
Misc options
.TP
.B \-\-parse\-pkgmk\-conf
Revert to the v0.9 behaviour of parsing /etc/pkgmk.conf to determine the
compression mode of built packages
.TP
.B \-h
Display usage information
.TP
.B \-v
Display version
.SH ENVIRONMENT
In automatic mode, \fBprtwash\fP gets a list of repositories from
/etc/prt-get.conf, and for each repository descends into the
individual port directories to read the associated Pkgfiles. In non-automatic
mode, \fBprtwash\fP only cleans the paths given on the command line. Directories
without a Pkgfile are skipped entirely, and a warning is given unless you
pass the option \fB\-q\fP. After reading the Pkgfile and /etc/pkgmk.conf,
\fBprtwash\fP will know the source filenames, the package filename, and the
distinction between sources under CRUX version control and sources downloaded
directly from upstream.
.PP
Sources under CRUX version control are only deleted if you pass the
option \fB\-d\fP. Sources from upstream are only deleted if you pass the
option \fB\-s\fP.
.PP
You can also delete the built package (current version) by passing
the option \fB\-p\fP. To select only older versions for deletion,
pass the option \fB\-b\fP instead. These two options operate independently,
allowing you to target four distinct subsets of packages (including the empty set)
for deletion.
.PP
By passing the option \fB\-\-parse\-pkgmk\-conf\fP, you can modify the behaviour
of the pattern matching performed to detect built packages. By default, the
regexp searches are done with the patterns
.B /${name}#${version}.*.pkg.tar.(gz|lz|xz|bz2)/
and
.B /${name}#.*pkg.tar.(gz|lz|xz|bz2)/
using the variables defined in the \fBPkgfile\fP(5). Passing the option
.B \-\-parse\-pkgmk\-conf
will result in a more narrow regexp search, allowing the deletion of any package
tarball that uses a different compression algorithm than the one currently defined
in /etc/pkgmk.conf (which is how the v0.9 bash script worked).

.SH COMPARISON WITH OTHER UTILITIES
Because \fBprtwash\fP reads the location of port collections from \fB/etc/prt-get.conf\fP(5),
you can easily control which collections are cleaned in automatic mode by commenting
or uncommenting the appropriate \fIprtdir\fP directives in that file. This detection
algorithm makes it easy to wash all your locally-curated repositories, in contrast
to the algorithm in \fBprtsweep\fP(1) which looks at the sup files used by \fBports\fP(8).
.PP
Another contrast between the two tools is that \fBprtwash\fP sources each Pkgfile to
generate its keep list, whereas \fBprtsweep\fP reads the SHA256 or MD5 sums from a manifest. 
Spawning an external bash shell for each port should in theory make \fBprtwash\fP slower
than \fBprtsweep\fP (which does everything in native perl), but on modern hardware the
difference is basically undetectable.
.PP
Neither \fBprtwash\fP nor \fBprtsweep\fP will ever touch anything outside your ports tree
or the directories passed on the command line. If you have centralized directories outside
the ports tree for all downloaded sources and built packages, you might find
\fBoldfiles\fP(1) more useful. Nevertheless, the pace of CRUX port updates is fast enough that
some cruft is bound to accumulate in the ports tree, and for this reason \fBprtwash\fP and
\fBprtsweep\fP still have their place in a CRUX admin's toolbox.
.SH EXAMPLES
.TP
.B prtwash \-a \-t
does a default wash action on the entire port tree;
doesn't really delete the files
.TP
.B prtwash \-a \-p \-s
now we're getting serious: removes all downoaded files
and built packages from the entire port tree
.TP
.B prtwash \-a \-p \-s \-d
same as the above, but also removes patches, initscripts, etc
.TP
.B prtwash \-p \-s /usr/ports/contrib/sitecopy
removes all downoaded files
and built packages from the sitecopy directory
.TP
.B prtwash /usr/ports/contrib/*
does the default wash action on the entire contrib collection
.SH AUTHORS
Simone Rota <sip at varlock dot com>, John McQuah <jmcquah at disroot dot org>
.SH SEE ALSO
\fBprtsweep\fP(1), \fBoldfiles\fP(1)