README

   1 CVSps (c) 2001,2002,2003 David Mansfield
   2 ------------------------------
   3
   4 Overview.
   5 --------
   6
   7 CVSps is a program for generating 'patchset' information from a CVS
   8 repository.  A patchset in this case is defined as a set of changes made
   9 to a collection of files, and all committed at the same time (using a
  10 single 'cvs commit' command).  This information is valuable to seeing the
  11 big picture of the evolution of a cvs project.  While cvs tracks revision
  12 information, it is often difficult to see what changes were committed
  13 'atomically' to the repository.
  14
  15 Compiling.
  16 ---------
  17
  18 CVSps is a relatively small program, with only a few modules.
  19 The Makefile is very simple and should work in most GNU type environments.
  20 Unfortunately, I've only been able to test on Red Hat Linux, so YMMV.  As
  21 CVSps matures, I'm sure a more sophisticated build environment will evolve
  22 with it.  For now, just try 'make' and 'make install'.  If you have any
  23 problems let me know.
  24
  25 Dependencies.
  26 ------------
  27
  28 CVSps depends on the following libraries:
  29   - tsearch (from search.h)
  30         MinGW 3.4.5 (August 2007) does not contain tsearch
  31         However, you are in luck since this version of CVSps includes a
  32                 patch found here:
  33         http://sourceware.org/cgi-bin/cvsweb.cgi/src/winsup/mingw/?cvsroot=src
  34   - regex (regular expressions)
  35         Download from http://sourceforge.net/project/showfiles.php?group_id=2435
  36         Click on "Contributed"
  37         Find "mingw-regex" (tested with version 2.5.1)
  38         Download "mingw-libgnurx-2.5.1-dev.tar.gz"
  39         Extract into your C:\MinGW directory
  40         Download "mingw-libgnurx-2.5.1-bin.tar.gz"
  41         Extract into your C:\MinGW directory
  42   - libz (compression)
  43         You can download and run zlib-1.2.3-mingwPORT-1.tar.bz2 which is
  44         a collection of scripts to be run by MSYS. Requres that you have
  45         MSYS installed.
  46
  47 CVSps depends on the following programs (at run time):
  48   - diff
  49   - sed
  50
  51 Running.
  52 -------
  53
  54 Note: not all options are necessarily discussed here.  Please check the
  55 output of 'cvsps -h' and/or the manual page for the most up-to-date info.
  56
  57 CVSps operates by parsing the 'cvs log' output.  So to run it, you must
  58 be in the working directory of a cvs project.  CVSps handles
  59 subdirectories fine, so run it in the top directory of your project.
  60
  61 a) the ~/.cvsps/cvsps.cache file (or so it's called)
  62
  63 Because you may have a *lot* of revision history in your project, and/or
  64 your connection to the cvs server may be slow or congested, CVSps uses a
  65 cache file for most operations.  The first time you run CVSps, just issue:
  66
  67 cvsps
  68
  69 and will begin reading and parsing the cvs log.  When it is finished it
  70 will output all of the patchset information to stdout, and it will also
  71 generate the '~/.cvsps/cvsps.cache' file.  Note: for historical reasons
  72 this file is still called the cvsps.cache file, but in reality it is named
  73 based on the CVS/Root and CVS/Repository contents, and thus is shared for
  74 the same repository checked out in multiple places.
  75
  76 If the cache file exists, it won't ever be automatically updated.  To
  77 update the cache with cvs activity that has occurred since the ~/.cvsps/cvsps.cache
  78 was last updated, use:
  79
  80 cvsps -u
  81
  82 If you question the integrity of the ~/.cvsps/cvsps.cache, or for some other reason
  83 want to force a full cache rebuild, use (you could also 'rm' the cache file):
  84
  85 cvsps -x
  86
  87 b) Reading the output.
  88
  89 CVSps's output is information about patchsets.  A patchset looks like:
  90
  91 ---------------------
  92 PatchSet 999
  93 Date: 2002/07/11 19:50:46
  94 Author: alan
  95 Branch: HEAD
  96 Tag: (none)
  97 Log:
  98 [PATCH] Fix several pdc202xx problems
  99
 100 Misnaming of 20270 as 20268R
 101 Failure of LBA48 on 20262
 102 Incorrect speed detection because the old driver used host not drive side
 103 cable detect
 104 PDC202xx handling for quirks in udma reporting off some drives
 105 LBA48 for PIO mode
 106
 107 BKrev: 3d2dd386wJMnehoOAhv3wL991IfXVQ
 108
 109 Members:
 110   ChangeSet:1.999->1.1000
 111   MAINTAINERS:1.74->1.75
 112   drivers/ide/ide-features.c:1.4->1.5
 113   drivers/ide/ide-pci.c:1.18->1.19
 114   drivers/ide/pdc202xx.c:1.11->1.12
 115   include/linux/pci_ids.h:1.44->1.45
 116
 117 ---------------------
 118
 119 This patchset is taken from the linux kernel BK->CVS tree.  It shows the date,
 120 the author, log message and each file that was modified.  For each file the
 121 pre-commit and post-commit revisions are given.  You can also see (if
 122 applicable, not in this case) if the files are on a branch, as well as the
 123 tag (see TAGS below).
 124
 125 Patchsets are ordered by commit timestamp, so as long as the clock on your
 126 cvs server is monotonic, the numbering of patchsets should be invariant
 127 across cache-rebuilds. (see COMPATIBILITY below).
 128
 129 c) Limiting the patchset output.
 130
 131 The default output of CVSps is to show all patchsets.  This can be
 132 filtered in one of many ways.  These flags can be combined to really
 133 limit the output to what you're interested in.
 134
 135 By id.  With the -s <ps range> you can specify individual PatchSets by
 136 number or by range.  Ranges can be of the form '<number>', '<number>-',
 137 '-<number>' and of course '<number>-<number>'.  Multiple ranges can be
 138 specified seperated by commas.  E.g.
 139
 140 cvsps -s 999-1020,1025,4956-
 141
 142 By author.  With the -a <author> flag you limit the output to patchsets
 143 committed by a given author.  The author is usually the UNIX login id.
 144
 145 By file.  With the -f <file regex> flag you limit the output to patchsets
 146 that have modified the given file.  Because a regular expression can have
 147 many pieces 'or'ed together, you can specify many different files here,
 148 for example (note also the use of the ^ character):
 149
 150 cvsps -f '^net/ipv4|^net/core'
 151
 152 By date.  With one date specification, CVSps shows only patchsets newer
 153 than the date given, and with two dates, it shows patchsets between the
 154 two dates.
 155
 156 *NOTE ON DATE FORMAT*.  Because I'm lazy, only one date format is
 157 currently acceptable. 'YYYY/MM/DD HH:MM:SS'  where time is given as
 158 localtime, and HH is in 24 hour format.  NOTE ALSO that cvs tends to
 159 display times as GMT, but parse dates as localtime, so when using the '-D'
 160 with cvs you need to convert from GMT to localtime in your head.  CVSps is
 161 not as fancy.  It treats all dates as if in localtime, and therefore you
 162 give CVSps dates the same way it gives them to you.
 163
 164 By branch.  With the -b <branch> flag you limit the output to patchsets
 165 that have modified the history of the given branch.  Note, this
 166 doesn't necessarily mean the commit itself was made on the branch, since
 167 the files in question may have existed prior to the branch point, in which
 168 case changes made to a given file before the branch point affect the file
 169 as it exists in the head of the branch.  If you want to restrict to the
 170 main branch, use a branch of 'HEAD'.
 171
 172 By log comment.  With the -l <regex> flag you can limit the ouptut to
 173 patchsets with the commit message matching the regex.
 174
 175 By tag.  With the -r <tag1> -r <tag2> you can limit the patchsets to
 176 commits after a given tag1 and, optionally, before tag2.
 177
 178 d) viewing the changes made by a patchset.
 179
 180 To show the 'diff' output for a given patchset, use -g.
 181
 182 It will show you the diff of changes made by the selected commits.
 183 Some effort was made to ensure that the patches are valid, even in the
 184 case of removing or creating files, a case in which 'cvs diff' fails.
 185 The patches generated are, generally speaking, applyable in the working
 186 directory with the '-p1' option to the patch command.
 187
 188 e) what is timestamp fuzz factor (-z option)?
 189
 190 There's another annoying feature of cvs.  When you commit a large change,
 191 the timestamp on the change is created per file committed.  For example:
 192 if you commit changes to 60 files on a slow server, taking, say, 60
 193 seconds, the 'commit time' as given in the log message for the first file
 194 will differ from that of the last file by 60 seconds.
 195
 196 The fuzz factor attempts to workaround this by saying: commits by the same
 197 author, using the same log message, within <fuzz> seconds are considered
 198 part of the same patchset.  The default fuzz is 300 seconds (5 minutes).
 199
 200 TAGS
 201 ----
 202
 203 Please read the manual page.
 204
 205 COMPATIBILITY
 206 -------------
 207
 208 One of the main goals of cvsps was to make the patchset numbering stable across
 209 all time, as long as no funny-business is done to the repository files themselves.
 210
 211 Unfortunately, as bugs have been fixed, the numbering has changed.  This is most
 212 regrettable, but unavoidable.
 213
 214 Additionally, in version 2.0, two changes have been made which will 'renumber'
 215 the patch sets.
 216
 217 1) The false 'globbing' of two commits from nearly the exact same time, by the
 218 same person, with the same log description but to different branches.  Now,
 219 these will be reported as 2 patchsets instead of one.
 220
 221 2) The creation of a large volume of patchsets for 'file xyz was originally added on
 222 branch' log messages.  This occurs whenever a file is originally born on a branch,
 223 and is exacerbated by the fact that even when all of these files are created with
 224 a single commit, the 'file xyz...' messages, which contains the actual file name,
 225 are different, causing a proliferation of these unwanted patchsets.  These patchsets
 226 are now silently eliminated from the output.
 227
 228 Reporting bugs / submitting patches.
 229 -----------------------------------
 230
 231 Although the current version is perfect and bug free, you can still send
 232 bug reports, feature requests and patches to me at:
 233
 234 cvsps@dm.cobite.com
 235
 236 I will try to maintain CVSps and make releases regularly.  The most recent
 237 version of CVSps will always be available at http://www.cobite.com/cvsps
 238
 239 Special thanks to my employer Cobite and Robert Lippman, who've given me
 240 time to develop this tool.
 241
 242 Known Problems (this will become the FAQ if anyone ever A any Q).
 243 ----------------------------------------------------------------
 244
 245 1) What is the '*** file xyz doesn't match strip_path abc' error?
 246
 247 This error occurs when one of the subdirectories of the directory you
 248 ran CVSps in is checked out from a different repository.  CVSps tries
 249 to remove the repository path information from the filenames that it
 250 gets to give you working-directory local pathnames.  It does this
 251 at startup by parsing the CVS/Root and CVS/Repository files.  If
 252 the contents of these two files is different for some subdirectory,
 253 all of the files in that subdirectory will be ignored.
 254
 255 You can always run CVSps in that subdirectory, and since it IS a
 256 separate repository, that does make a little bit of sense.