'\" t
.\"     Title: pepper
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 10/16/2013
.\"    Manual: User commands
.\"    Source: pepper 0.3.2
.\"  Language: English
.\"
.TH "PEPPER" "1" "10/16/2013" "pepper 0\&.3\&.2" "User commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pepper \- Repository statistics and report tool
.SH "SYNOPSIS"
.sp
\fBpepper\fR [\fIoptions\fR] \fIreport\fR [\fIreport options\fR] [\fIrepository\fR]
.SH "DESCRIPTION"
.sp
\fBpepper\fR is a command\-line tool for retrieving statistics and generating reports from source code repositories\&. If invoked with valid options,it runs a \fBlua\fR(1) script given by \fIreport\fR on the given \fIrepository\fR, producing textual or graphical output\&.
.sp
If the \fIreport\fR argument doesn\(cqt point to a \fBlua\fR(1) report script, a number of paths will be searched for a report with the given name (see \fBENVIRONMENT VARIABLES\fR)\&. Thus, the built\-in reports can be launched by specifying their name only\&. Report\-specific options can be passed as \fIreport options\fR following the report script name\&. To retrieve a listing of options supported by the respective report, pass \fB\-\-help\fR as described in \fBOPTIONS\fR\&.
.sp
If no \fIrepository\fR argument is present, the current directory will be used\&. Normally, the type of the repository is automatically detected, and an appropriate backend implementation will be selected\&. Some backends provide additional options, e\&.g\&. user authentication for remote repositories\&. Those options will be listed if you pass the \fB\-\-help\fR flag as described in \fBOPTIONS\fR\&.
.SH "OPTIONS"
.PP
\fB\-?\fR, \fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a nice help screen\&. If the command line includes a report script name or path, report options will be shown\&. Additionally, backend options will be shown for the selected repository or backend\&.
.RE
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
Set verbosity level to minimum\&. Only warnings and errors will be shown\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Increase verbosity level\&. Can be specified multiple times\&.
.RE
.PP
\fB\-\-no\-cache\fR
.RS 4
Neither read from nor write to the local revision cache\&.
.RE
.PP
\fB\-\-list\-reports\fR
.RS 4
List all reports that can be found in the current report search directories\&.
.RE
.PP
\fB\-\-list\-backends\fR
.RS 4
List all built\-in repository backends\&.
.RE
.PP
\fB\-bARG, \-\-backend=ARG\fR
.RS 4
Force usage of backend named
\fBARG\fR\&. Use
\fB\-\-list\-backends\fR
to retrieve a list of all available backends\&.
.RE
.SH "REVISION CACHE"
.sp
\fBpepper\fR uses a local revision cache, located at $HOME/\&.pepper/cache\&. It contains meta\-data and diffstats of revisions that have been requested in previous invocations of the program\&.
.sp
If the program complains that your revision cache is invalid (probably because of abnormal program termination or power failure), please run the \fBcheck_cache\fR report to fix it and remove faulty revisions\&.
.SH "ENVIRONMENT VARIABLES"
.PP
\fBPEPPER_REPORTS\fR
.RS 4
A colon\-separated list of paths used to search for report scripts\&.
.RE
.PP
\fBPEPPER_CACHEDIR\fR
.RS 4
A path that overrides the default cache location\&.
.RE
.SH "EXAMPLES"
.sp
Let\(cqs assume that the current directory is the repository of interest\&.
.PP
pepper \-\-list\-reports
.RS 4
This lists all reports in the current search path with their descriptions\&. The names from this listing can be used as the program\(cqs
\fIreport\fR
argument\&.
.RE
.PP
pepper loc
.RS 4
A classic "Lines of Code" graph will be generated, with the actual plotting done by
\fBgnuplot\fR(1)\&. If the user is running X11, a detached window containing the plot will be shown\&. Else, output in SVG format will be written to
\fIstdout\fR\&. All meta\-data and diffstats fetched during this session will be written to the revision cache\&.
.RE
.PP
pepper loc \-\-type=png \-\-output=loc\&.png
.RS 4
The same as above, now probably significantly faster because the revisions of interest are already cached\&. This time, a PNG image will be generated and written to "loc\&.png"\&.
.RE
.PP
pepper authors \-n4 \-\-tags="2\&.6\&.[0\-9]*$"
.RS 4
This time, the code contribution by the 4 busiest authors will be be plotted\&. Additionally, vertical tag marks will be show for all tags that look like releases (of the Linux kernel)\&.
.RE
.PP
pepper \-\-username=user commit_counts \-\-period=14d \m[blue]\fBhttp://svn\&.example\&.org\fR\m[]
.RS 4
This generates a histogram of commit frequencies for the last 14 days\&. This time, a remote Subversion repository requiring authentication is being used\&. If a password is required, the program will prompt for it\&.
.RE
.PP
pepper shortlog \-\-branch=stable \-\-summary
.RS 4
This will print a simple commit summary from the "stable" branch to
\fIstdout\fR, looking like
\fBgit\-shortlog\fR(1)\&.
.RE
.SH "CUSTOM REPORTS"
.sp
\fBpepper\fR provides an API for writing custom report scripts in \fBlua\fR(1)\&. The \fBpepper\fR homepage at \m[blue]\fBhttp://scm\-pepper\&.sourceforge\&.net\fR\m[] contains more information about this topic, including a scripting tutorial covering common tasks and an API reference manual\&.
.SH "EXIT STATUS"
.sp
0 on success, 1 on failure\&. Any error messages, warnings and progress will be printed to \fIstderr\fR\&.
.SH "SEE ALSO"
.sp
\fBgit\fR(1), \fBsvn\fR(1), \fBhg\fR(1), \fBlua\fR(1), \fBgnuplot\fR(1)
.SH "AUTHOR"
.sp
Copyright \(co 2010\-2012 Jonas Gehring <jonas\&.gehring@boolsoft\&.org>\&. Released under the GNU General Public License\&.