diff options
Diffstat (limited to 'cvsps.1')
| -rw-r--r-- | cvsps.1 | 205 |
1 files changed, 205 insertions, 0 deletions
@@ -0,0 +1,205 @@ +.TH "cvsps" 1 +.SH NAME +CVSps \- create patchset information from CVS +.SH SYNOPSIS +.B 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>] +.SH 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 +'atomically' to the repository. +.SH OPTIONS +.TP +.B \-h +display usage summary +.TP +.B \-x +ignore (and rebuild) ~/.cvsps/cvsps.cache file +.TP +.B \-u +update ~/.cvsps/cvsps.cache file +.TP +.B \-z <fuzz> +set the timestamp fuzz factor for identifying patch sets +.TP +.B \-g +generate diffs of the selected patch sets +.TP +.B \-s <patchset>[\-[<patchset>]][,<patchset>...] +generate a diff for a given patchsets and patchset ranges +.TP +.B \-a <author> +restrict output to patchsets created by author +.TP +.B \-f <file> +restrict output to patchsets involving file +.TP +.B \-d <date1> \-d <date2> +if just one date specified, show +revisions newer than date1. If two dates specified, +show revisions between two dates. +.TP +.B \-l <regex> +restrict output to patchsets matching regex in log message +.TP +.B \-b <branch> +restrict output to patchsets affecting history of branch. +If you want to restrict to the main branch, use a branch of 'HEAD'. +.TP +.B \-r <tag1> \-r <tag2> +if just one tag specified, show +revisions since tag1. If two tags specified, show +revisions between the two tags. +.TP +.B \-p <dir> +output individual patchsets as files in <dir> as <dir>/<patchset>.patch +.TP +.B \-v +show very verbose parsing messages +.TP +.B \-t +show some brief memory usage statistics +.TP +.B \-\-norc +when invoking cvs, ignore the .cvsrc file +.TP +.B \-\-summary\-first +when multiple patchset diffs are being generated, put the patchset +summary for all patchsets at the beginning of the output. +.TP +.B \-\-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 +.TP +.B \-\-bkcvs +(see note below) for use in parsing the BK\->CVS tree log formats only. This enables +some hacks which are not generally applicable. +.TP +.B \-\-no\-rlog +disable the use of rlog internally. Note: rlog is +required for stable PatchSet numbering. Use with care. +.TP +.B \-\-diffs\-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. +.TP +.B \-\-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. +.TP +.B \-\-debuglvl <bitmask> +enable various debug output channels. +.TP +.B \-Z <compression> +A value 1\-9 which specifies amount of compression. A value of 0 disables compression. +.TP +.B \-\-root <cvsroot> +Override the setting of CVSROOT (overrides working dir. and environment). For --cvs-direct only. +.TP +.B \-q +Be quiet about warnings. +.B \-A +Show ancestor branch when a new branch is found. +.TP +.B \<repository> +Operate on the specified repository (overrides working dir.) +.SH "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. +.PP +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. +.PP +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. +.SH "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. +.PP +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. +.SH "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. +.SH "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). +.SH "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. +.SH "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. +.SH "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, +.IP "" 4 +$ cvsps -d '2004/05/01 00:00:00' -d '2004/07/07 12:00:00' +.SH "SEE ALSO" +.BR cvs ( 1 ), +.BR ci ( 1 ), +.BR co ( 1 ), +.BR cvs ( 5 ), +.BR cvsbug ( 8 ), +.BR diff ( 1 ), +.BR grep ( 1 ), +.BR patch ( 1 ), +.BR rcs ( 1 ), +.BR rcsdiff ( 1 ), +.BR rcsmerge ( 1 ), +.BR rlog ( 1 ). +.SH "REPORTING BUGS" +Report bugs to "David Mansfield <cvsps@dm.cobite.com>" +.SH BUGS +No known bugs. + |