prtsweep.1: initial commit

man1/prtsweep.1

@@ -0,0 +1,107 @@
+.\" 
+.\" prtsweep manual page.
+.\" (C) 2e003 by Martin Opel
+.\" Revised 2021 by John McQuah
+.\"
+.TH prtsweep 1
+.SH NAME
+prtsweep \- sweep old files from the ports directories
+.SH SYNOPSIS
+.PP
+.B prtsweep
+[\-a] [\-d] [\-n] [PORTDIR ...]
+.SH DESCRIPTION
+
+The \fIprtsweep\fP perl script sweeps port directories, deleting unneeded files.
+"Unneeded" here means not listed in the .signatures file, and not the
+built package
+.PP
+.nf
+	name#version-release.pkg.tar.?z*
+.fi
+.PP
+All other files are removed. If a traversal of the ports collections in automatic mode
+reveals an empty directory (or one of the arguments in [PORTDIR ...] is similarly missing
+the required \fBPkgfile\fP), the directory can be removed with the \fI\-d\fP option.
+
+.SH OPTIONS
+The following options are supported:
+.TP
+.I "\-a"
+This is the automatic mode. In this mode \fIprtsweep\fP reads the port
+collections defined by /etc/ports/*.{git,httpup,rsync} files and cleans all ports 
+in those collections.
+.TP
+.I "\-d"
+Removes empty directories completely. This happens when ports are moved for
+example from opt to contrib or vice versa. Note that this option only
+deletes empty directories, so accidently removing whole directory trees
+should not happen, even if you use
+.IP
+.nf
+	prtsweep \-d /
+.fi
+.IP
+To remove these moved ports completely you can run \fIprtsweep\fP twice:
+the first pass removes everything under the directory of the dropped port,
+the second pass removes the empty directory.
+.TP
+.I "\-p"
+Also removes the built package.
+.TP
+.I "\-n"
+Dry-run. Do not remove anything really.
+.TP
+.I "\-q"
+Quiet mode. Print messages only for the files that are deleted, not for the
+file that are kept. Equivalent to \fBprtsweep [args] | grep -v "keeping"\fP.
+.SH ENVIRONMENT
+In automatic mode, \fBprtsweep\fP gets a list of active port collections
+from /etc/ports/*.{rsync,httpup}, and for each collection descends into the
+individual port directories to read the associated .signature files.
+After reading .signature, \fBprtsweep\fP will be able to distinguish between
+needed sources and unneeded clutter. \fBprtsweep\fP then compares the contents
+of the port directory with this list of needed files, and any non-matching
+files are deleted (or just printed to stderr if dry-run mode is enabled).
+.PP
+\fBprtsweep\fP does not distinguish between the current version of the built package
+and previous versions. All built packages beginning with the name of the port directory (and
+ending in pkg.tar.*) are normally shielded from deletion, except when you pass the option
+\fB\-p\fP. Passing this option allows \fBprtsweep\fP to delete every built package,
+no matter how old. If you want to keep the current version of the built package but delete
+older versions, you can use the companion script \fBprtwash(1)\fP instead.
+.PP
+After a real cleaning by \fBprtsweep\fP (not dry-run mode), each port
+directory should contain only the Pkgfile, source files listed in .signature,
+and the built package (if present, and option -p was not given on the command
+line).
+
+.SH EXAMPLES
+
+You can call \fIprtsweep\fP with one port:
+.PP
+.nf
+	root@hostname:/root # prtsweep /usr/ports/opt/dialog
+	=======> /usr/ports/opt/dialog
+	+ removing file dialog-0.9b-20020814.tgz
+.fi
+.PP
+Or you could call the automatic mode, which scans your supfiles in /etc/ports
+for all ports directories and cleans them automatically:
+.PP
+.nf
+	root@hostname:/root # prtsweep -a
+	=======> /usr/ports/clc/stable/atop
+	+ removing file atop-1.8.tar.gz
+	=======> /usr/ports/clc/stable/coldsync
+	+ removing file coldsync-2.2.5-gcc3.diff
+	+ removing file coldsync-2.2.5.tar.gz
+	=======> /usr/ports/clc/stable/dnsmasq
+	+ removing file dnsmasq-1.10.tar.gz
+	...
+.fi
+
+.SH AUTHORS
+Martin Opel <mo at obbl-net dot de>, John McQuah <jmcquah at disroot dot org>
+.SH "SEE ALSO"
+prtwash(1)