fix bug in aging view, add man pages

[zpackage] / doc / zpm-gc.8

diff --git a/doc/zpm-gc.8 b/doc/zpm-gc.8
new file mode 100644 (file)
index 0000000..f35fd79
--- /dev/null
+++ b/doc/zpm-gc.8
@@ -0,0 +1,78 @@
+.TH zpm-gc 8 2018-12-10 "ZPM 0.4"
+.SH NAME
+zpm-gc \- garbage collect a database
+.SH SYNOPSIS
+.B zpm gc [-f \fIdb\fB] [-cCP] [-l retention] [-n retention]
+.SH DESCRIPTION
+\fBzpm-gc\fR removes unneeded or unwanted elements from a zpm database.
+Actions taken will be logged in the database and written to stdout.
+Each action is described below.
+.SS Old packages
+Unused packages will be removed, unless they need to be retained to keep a
+library installed, or if they are within the keep target.  By default, two old
+versions of a package will be kept.  This phase is run by default,
+but can be suppressed with the \-P option.  The keep target can
+be set with the -k option or the ZPM_KEEP_PACKAGES environment
+variable.  If both are used, the command line option takes precedence.
+.PP
+Packages kept by the keep target do not include packages otherwise retained for
+library dependencies, so it is possible that more than the keep target older
+packages will be retained.  Only packages in an "updated" or "removed" status
+are eligible for garbage collection, so an admin can keep any arbitrary package
+from being garbage collected by setting the status of the package to some other
+value.
+.SS Log entries
+Old log entries can be removed by passing the \-l option.  The -l
+option takes an argument specifying which log entries to delete.
+.SS Notes
+Notes can be removed with the \-n option.
+.SS Unreferenced file content
+File content unreferenced by either a package, note, or script
+will be removed by default.  This action can be suppressed with \-C.
+.SS Package file content
+File content belonging to packages can be removed with the \-F option.
+This is not done by default, and the action can be restricted to
+a specific package with the \-p option.
+.SS Compact
+Re-write the database file out completely to minimize the amount
+of disk space it uses.  This option can take a few minutes
+for large (gigabyte sized) databases, and is not run by default.
+It can be enabled with the \-c option.
+.SH OPTIONS
+.TP
+\-f \fIdbfile\fR
+Use \fIdbfile\fR as the database to run against, instead of the default.
+.TP
+\-l \fIretention\fR
+Delete old logentries that correspond to the retention.
+A retention starting with a '+' is taken as the number of days to retain.
+A retention containing only digits is taken as a number of log entries to
+retain, anything else is interpreted as a timestamp.
+.TP
+\-n \fIretention\fR
+Delete old notes that correspond to the retention.
+A retention is interpreted the same way as for the \-l option.
+.TP
+\-z
+Zero out the set of actions to preform.
+Specific actions can be specified as options after the \-z.
+.TP
+\-k \fIn\fR
+Set the number of old packages to retain to \fIn\fR.  These are in addition to
+any packages retained because they contain libraries that are still needed.
+.SH EXAMPLES
+.PP
+.nf
+zpm-gc
+.fi
+.SH EXIT STATUS
+0 if successful, non-zero if there was an error
+.SH FILES
+None
+.SH ENVIRONMENT
+ZPMDB ZPM_KEEP_PACKAGES
+.SH AUTHOR
+Nathan Wagner
+.SH SEE ALSO
+.BR zpm (8)
+.BR zpm-log (8)