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