CVSps (c) 2001 David Mansfield
------------------------------

Overview.
--------

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
'atomically' to the repository.

Compiling.
---------

CVSps is a simple program, all in one .c file, with a few utility modules.
The Makefile is very simple and should work in most GNU type environments.
Unfortunately, I've only been able to test on Red Hat Linux, so YMMV.  As
CVSps matures, I'm sure a more sophisticated build environment will evolve
with it.  For now, just try 'make' and 'make install'.

Running.
-------

CVSps operates by parsing the 'cvs log' output.  So to run it, you must
be in the working directory of a cvs project.  CVSps handles
subdirectories fine, so run it in the top directory of your project.

a) the CVS/cvsps.cache file

Because you may have a *lot* of revision history in your project, and/or
your connection to the cvs server may be slow or congested, CVSps uses a
cache file for most operations.  The first time you run CVSps, just issue:

cvsps

and will begin reading and parsing the cvs log.  When it is finished it
will output all of the patchset information to stdout, and it will also
generate the 'CVS/cvsps.cache' file.

If the cache file exists, it won't ever be automatically updated.  To
update the cache with cvs activity that has occurred since the CVS/cvsps.cache
was last updated, use:

cvsps -u

If you question the integrity of the CVS/cvsps.cache, or for some other reason
want to force a full cache rebuild, use (you could alse 'rm' the cache):

cvsps -x

b) Reading the output.

CVSps's output is information about patchsets.  A patchset looks like:

---------------------
PatchSet 1701
Date: 2001/11/06 19:49:04
Author: joe
Log:
this release completes line summary find

Members: 
   Makefile:1.3.4.9->1.3.4.10 [v4_1-production-patches]
   apache_mod/lineSummary.C:1.66.2.2->1.66.2.3 [v4_1-production-patches]
   apache_mod/tbill_sql.C:1.59.2.5->1.59.2.6 [v4_1-production-patches]

---------------------

This patchset is taken from an internal project.  It shows the date, the
author, log message and each file that was modified.  For each file the
pre-commit and post-commit revisions are given.  In this case, you can see
that the files are on a branch, and the branch tag is shown (for each
file) inside square brackets.

Patchsets are ordered by commit timestamp, so as long as the clock on your
cvs server is monotonic, the numbering of patchsets should be invariant
across cache-rebuilds.

c) Limiting the patchset output.

The default output of CVSps is to show all patchsets.  This can be
filtered in one of many ways.  These flags can be combined to really
limit the output to what you're interested in.

By author.  With the -a <author> flag you limit the output to patchsets
committed by a given author.  The author is usually the UNIX login id.

By file.  With the -f <file> flag you limit the output to patchsets that
have modified the given file.  File is given as the BASENAME of the file,
not the entire path. (I think!)

By date.  With one date specification, CVSps shows only patchsets newer
than the date given, and with two dates, it shows patchsets between the
two dates.

*NOTE ON DATE FORMAT*.  Because I'm lazy, only one date format is
currently acceptable. 'YYYY/MM/DD HH:MM:SS'  where time is given as
localtime, and HH is in 24 hour format.  NOTE ALSO that cvs tends to
display times as GMT, but parse dates as localtime, so when using the '-D'
with cvs you need to convert from GMT to localtime in your head.  CVSps is
not as fancy.  It treats all dates as if in localtime, and therefore you
give CVSps dates the same way it gives them to you.

By branch.  With the -b <branch> flag you limit the output to patchsets
that have modified the history of the given branch.  Note, this 
doesn't necessarily mean the commit itself was made on the branch, since
the files in question may have existed prior to the branch point, in which
case changes made to a given file before the branch point affect the file
as it exists in the head of the branch.  If you want to restrict to the
main branch, use a branch of 'TRUNK'.

d) viewing the changes made by a patchset.

To show the 'diff' output for a given patchset, use:

cvsps -s <patchset number>

It will show you the diff of changes made by the commit.  Some effort was
made to ensure that the patches are valid, even in the case of removing or
creating files, a case in which 'cvs diff' fails.

e) what is timestamp fuzz factor (-z option)?

There's another annoying feature of cvs.  When you commit a large change,
the timestamp on the change is created per file committed.  For example:
if you commit changes to 60 files on a slow server, taking, say, 60
seconds, the 'commit time' as given in the log message for the first file
will differ from that of the last file by 60 seconds.

The fuzz factor attempts to workaround this by saying: commits by the same
author, using the same log message, within <fuzz> seconds are considered
part of the same patchset.  The default fuzz is 300 seconds (5 minutes).

Reporting bugs / submitting patches.
-----------------------------------

Although the current version is perfect and bug free, you can still send
bug reports, feature requests and patches to me at:

cvsps@dm.cobite.com

I will try to maintain CVSps and make releases regularly.  The most recent
version of CVSps will always be available at http://www.cobite.com/cvsps

Special thanks to my employer Cobite and Robert Lippman, who've given me
time to develop this tool.

Known Problems (this will become the FAQ if anyone ever A any Q).
----------------------------------------------------------------

1) What is the '*** file xyz doesn't match strip_path abc' error?

This error occurs when one of the subdirectories of the directory you
ran CVSps in is checked out from a different repository.  CVSps tries
to remove the repository path information from the filenames that it
gets to give you working-directory local pathnames.  It does this 
at startup by parsing the CVS/Root and CVS/Repository files.  If 
the contents of these two files is different for some subdirectory,
all of the files in that subdirectory will be ignored. 

You can always run CVSps in that subdirectory, and since it IS a 
separate repository, that does make a little bit of sense.


