NAME
CVSps - create patchset information from CVS
SYNOPSIS
cvsps [-h] [-x] [-u] [-z <fuzz>] [-g] [-s <patchset>] [-a <author>] [-f
<file>] [-d <date1> [-d <date2>]] [-l <text>] [-b <branch>] [-r <tag>
[-r <tag>]] [-p <directory>] [-v] [-t] [--norc] [--summary-first]
[--test-log <filename>] [--bkcvs] [--no-rlog] [--diff-opts <option
string>] [--cvs-direct] [--debuglvl <bitmask>] [-Z <compression>]
[--root <cvsroot>] [-q] [-A] [<repository>]
DESCRIPTION
CVSps is a program for generating ’patchset’ information from a CVS
repository. A patchset in this case is defined as a set of changes
made to a collection of files, and all committed at the same time
(using a single ’cvs commit’ command). This information is valuable to
seeing the big picture of the evolution of a cvs project. While cvs
tracks revision information, it is often difficult to see what changes
were committed
OPTIONS
-h display usage summary
-x ignore (and rebuild) ~/.cvsps/cvsps.cache file
-u update ~/.cvsps/cvsps.cache file
-z <fuzz>
set the timestamp fuzz factor for identifying patch sets
-g generate diffs of the selected patch sets
-s <patchset>[-[<patchset>]][,<patchset>...]
generate a diff for a given patchsets and patchset ranges
-a <author>
restrict output to patchsets created by author
-f <file>
restrict output to patchsets involving file
-d <date1> -d <date2>
if just one date specified, show revisions newer than date1. If
two dates specified, show revisions between two dates.
-l <regex>
restrict output to patchsets matching regex in log message
-b <branch>
restrict output to patchsets affecting history of branch. If
you want to restrict to the main branch, use a branch of ’HEAD’.
-r <tag1> -r <tag2>
if just one tag specified, show revisions since tag1. If two
tags specified, show revisions between the two tags.
-p <dir>
output individual patchsets as files in <dir> as
<dir>/<patchset>.patch
-v show very verbose parsing messages
-t show some brief memory usage statistics
--norc when invoking cvs, ignore the .cvsrc file
--summary-first
when multiple patchset diffs are being generated, put the
patchset summary for all patchsets at the beginning of the
output.
--test-log <captured cvs log file>
for testing changes, you can capture cvs log output, then test
against this captured file instead of hammering some poor CVS
server
--bkcvs
(see note below) for use in parsing the BK->CVS tree log formats
only. This enables some hacks which are not generally
applicable.
--no-rlog
disable the use of rlog internally. Note: rlog is required for
stable PatchSet numbering. Use with care.
--diff-opts <option string>
send a custom set of options to diff, for example to increase
the number of context lines, or change the diff format.
--cvs-direct (--no-cvs-direct)
enable (disable) built-in cvs client code. This enables the
’pipelining’ of multiple requests over a single client, reducing
the overhead of handshaking and authentication to one per
PatchSet instead of one per file.
--debuglvl <bitmask>
enable various debug output channels.
-Z <compression>
A value 1-9 which specifies amount of compression. A value of 0
disables compression.
--root <cvsroot>
Override the setting of CVSROOT (overrides working dir. and
environment). For --cvs-direct only.
-q Be quiet about warnings. -A Show ancestor branch when a new
branch is found.
<repository>
Operate on the specified repository (overrides working dir.)
NOTE ON TAG HANDLING
Tags are fundamentally ’file at a time’ in cvs, but like everything
else, it would be nice to imagine that they are ’repository at a time.’
The approach cvsps takes is that a tag is assigned to a patchset. The
meaning of this is that after this patchset, every revision of every
file is after the tag (and conversely, before this patchset, at least
one file is still before the tag). However, there are two kinds of
inconsistent (or ’funky’) tags that can be created, even when following
best practices for cvs.
The first is what is called a FUNKY tag. A funky tag is one where
there are patchsets which are chronologically (and thus by patchset id)
earlier than the tag, but are tagwise after. These tags will be marked
as ’**FUNKY**’ in the Tag: section of the cvsps output. When a funky
tag is specified as one of the ’-r’ arguments, there are some number of
patchsets which need to be considered out of sequence. In this case,
the patchsets themselves will be labeled FUNKY and will be processed
correctly.
The second is called an INVALID tag. An invalid tag is a tag where
there are patchsets which are chronologically (and thus by patchset id)
earlier than the tag, but which have members which are tagwise both
before, and after the tag, in the same patchset. If an INVALID tag is
specified as one of the ’-r’ arguments, cvsps will flag each member of
the affected patchsets as before or after the tag and the patchset
summary will indicate which members are which, and diffs will be
generated accordingly.
NOTE ON CVS VERSIONS
Among the different cvs subcommands used by cvsps is the ’rlog’
command. The rlog command is used to get revision history of a module,
and it disregards the current working directory. The important
difference between ’rlog’ and ’log’ (from cvsps perspective) is the
’rlog’ will include log data for files not in the current working
directory. The impact of this is mainly when there are directories
which at one time had files, but are now empty, and have been pruned
from the working directory with the ’-P’ option. If ’rlog’ is not
used, these files logs will not be parsed, and the PatchSet numbering
will be unstable.
The main problem with ’rlog’ is that, until cvs version 1.11.1, ’rlog’
was an alias for the ’log’ command. This means, for old versions of
cvs, ’rlog’ has different semantics and usage. cvsps will attempt to
work around this problem by detecting capable versions of cvs. If an
old version is detected, ’log’ will be used instead of ’rlog’, and
YMMV.
NOTE ON GENERATED DIFFS
Another important note is that cvsps will attempt, whenever possible,
to use the r-commands (rlog, rdiff and co) instead of the local
commands (log, diff, and update). This is to allow cvsps to function
without a completely checked out tree. Because these r-commands are
used, the generated diffs will include the module directory in them,
and it is recommended to apply them in the working directory with the
-p1 option to the patch command. However, if the --diff-opts option is
specified (to change, for example, the lines of context), then rdiff
cannot be used, because it doesn’t support arbitrary options. In this
case, the patches will be generated without the module directory in the
path, and -p0 will be required when applying the patch. When diffs are
generated in cvs-direct mode (see below), however, they will always be
-p1 style patches.
NOTE ON BKCVS
The --bkcvs option is a special operating mode that should only be used
when parsing the log files from the BK -> CVS exported linux kernel
trees. cvsps uses special semantics for recreating the BK ChangeSet
metadata that has been embedded in the log files for those trees. The
--bkcvs option should only be specified when the cache file is being
created or updated (i.e. initial run of cvsps, or when -u and -x
options are used).
NOTE ON CVS-DIRECT
As of version 2.0b6 cvsps has a partial implementation of the cvs
client code built in. This reduces the RTT and/or handshaking overhead
from one per patchset member to one per patchset. This dramatically
increases the speed of generating diffs over a slow link, and improves
the consistency of operation. Currently the --cvs-direct option turns
on the use of this code, but it very well may be default by the time
2.0 comes out. The built-in cvs code attempts to be compatible with
cvs, but may have problems, which should be reported. It honors the
CVS_RSH and CVS_SERVER environment variables, but does not parse the
~/.cvsrc file.
NOTE ON CVSPS RC FILE
CVSps parses an rc file at startup. This file should be located in
~/.cvsps/cvspsrc. The file should contain arguments, in the exact
syntax as the command line, one per line. If an argument takes a
parameter, the parameter should be on the same line as the argument.
NOTE ON DATE FORMATS
All dates are reported in localtime. This can be overridden (as usual)
using the TZ environment variable. Dates as arguments must be in the
format ’yyyy/mm/dd hh:mm:ss’; for example,
$ cvsps -d ’2004/05/01 00:00:00’ -d ’2004/07/07 12:00:00’
SEE ALSO
cvs(1), ci(1), co(1), cvs(5), cvsbug(8), diff(1), grep(1), patch(1),
rcs(1), rcsdiff(1), rcsmerge(1), rlog(1).
REPORTING BUGS
Report bugs to "David Mansfield <cvsps@dm.cobite.com>"
BUGS
No known bugs.
cvsps(1)