NAME

VCP::Source::cvs - A CVS repository source

SYNOPSIS

   vcp cvs:module/... -d ">=2000-11-18 5:26:30" <dest>
                                  # All file revs newer than a date/time

   vcp cvs:module/... -r foo      # all files in module and below labelled foo
   vcp cvs:module/... -r foo:     # All revs of files labelled foo and newer,
                                  # including files not tagged with foo.
   vcp cvs:module/... -r 1.1:1.10 # revs 1.1..1.10
   vcp cvs:module/... -r 1.1:     # revs 1.1 and up on main trunk

   ## NOTE: Unlike cvs, vcp requires spaces after option letters.

DESCRIPTION

Source driver enabling vcp to extract versions form a cvs repository.

The source specification for CVS looks like:

    cvs:cvsroot/filespec [<options>]

where the cvsroot is passed to cvs with the -d option if provided (cvsroot is optional if the environment variable CVSROOT is set) and the filespec and <options> determine what revisions to extract.

filespec may contain trailing wildcards, like /a/b/... to extract an entire directory tree.

If the CVSROOT / -d option looks like a local filesystem (if it doesn't start with ":" and if it points to an existing directory or file), this module will read the RCS files directly from the hard drive unless --use-cvs is passed. This is more accurate (due to poor design of the cvs log command) and much, much faster.

OPTIONS

-b, --bootstrap

   -b ...
   --bootstrap=...
   -b file1[,file2[, etc.]]
   --bootstrap=file1[,file2[, etc. ]]

(the ... there is three periods, a Regexp::Shellish wildcard borrowed from p4 path syntax).

Forces bootstrap mode for an entire export (-b ...) or for certain files. Filenames may contain wildcards, see Regexp::Shellish for details on what wildcards are accepted.

Controls how the first revision of a file is exported. A bootstrap export contains the entire contents of the first revision in the revision range. This should only be necessary when exporting for the first time.

An incremental export contains a digest of the revision preceding the first revision in the revision range, followed by a delta record between that revision and the first revision in the range. This allows the destination import function to make sure that the incremental export begins where the last export left off.

The default is decided on a per-file basis: if the first revision in the range is revision #.1, the full contents are exported. Otherwise an incremental export is done for that file.

This option is necessary when exporting only more recent revisions from a repository.

--cd

Used to set the CVS working directory. VCP::Source::cvs will cd to this directory before calling cvs, and won't initialize a CVS workspace of it's own (normally, VCP::Source::cvs does a "cvs checkout" in a temporary directory).

This is an advanced option that allows you to use a CVS workspace you establish instead of letting vcp create one in a temporary directory somewhere. This is useful if you want to read from a CVS branch or if you want to delete some files or subdirectories in the workspace.

If this option is a relative directory, then it is treated as relative to the current directory.

-kb, -k b

Pass the -kb option to cvs, forces a binary checkout. This is useful when you want a text file to be checked out with Unix linends, or if you know that some files in the repository are not flagged as binary files and should be.

--rev-root

Experimental.

Falsifies the root of the source tree being extracted; files will appear to have been extracted from some place else in the hierarchy. This can be useful when exporting RevML, the RevML file can be made to insert the files in to a different place in the eventual destination repository than they existed in the source repository.

The default rev-root is the file spec up to the first path segment (directory name) containing a wildcard, so

   cvs:/a/b/c...

would have a rev-root of /a/b.

In direct repository-to-repository transfers, this option should not be necessary, the destination filespec overrides it.

-r

   -r v_0_001:v_0_002
   -r v_0_002:

Passed to cvs log as a -r revision specification. This corresponds to the -r option for the rlog command, not either of the -r options for the cvs command. Yes, it's confusing, but 'cvs log' calls 'rlog' and passes the options through.

IMPORTANT: When using tags to specify CVS file revisions, it would ordinarily be the case that a number of unwanted revisions would be selected. This is because the behavior of the cvs log command dumps the entire log history for any files that do not contain the tag. VCP captures the histories of such files and ignores all revisions that are older or newer than any files that match the tags.

Be cautious using HEAD as the end of a revision range, this seems to cause the delete actions for files deleted in the last revision to not be noticed. Not sure why.

--use-cvs

Do not try to read local repositories directly; use the cvs command line interface. This is much slower than reading the files directly but is useful to see if there is a bug in the RCS file parser or possible when dealing with corrupt RCS files that cvs will read.

If you find that this option makes something work, then there is a discrepancy between the code that reads the RCS files directly (in the absence of this option) and cvs itself. Please let me know (barrie@slaysys.com). Thanks.

-d

   -d "2000-11-18 5:26:30<="

Passed to 'cvs log' as a -d date specification.

WARNING: if this string doesn't contain a '>' or '<', you're probably doing something wrong, since you're not specifying a range. vcp may warn about this in the future.

Files that aren't tagged

CVS has one peculiarity that this driver works around.

If a file does not contain the tag(s) used to select the source files, cvs log outputs the entire life history of that file. We don't want to capture the entire history of such files, so VCP::Source::cvs goes ignores any revisions before and after the oldest and newest tagged file in the range.

LIMITATIONS

   "What we have here is a failure to communicate!"
       - The warden in Cool Hand Luke

CVS does not try to protect itself from people checking in things that look like snippets of CVS log file: they come out exactly like they went in, confusing the log file parser. So, if a repository contains messages in the log file that look like the output from some other "cvs log" command, things will likely go awry.

CVS stores the -k keyword expansion setting per file, not per revision, so vcp will mark all revisions of a file with the current setting of the -k flag for a file.

At least one cvs repository out there has multiple revisions of a single file with the same rev number. The second and later revisions with the same rev number are ignored with a warning like "Can't add same revision twice:...".

SEE ALSO

VCP::Dest::cvs, vcp, VCP::Process.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>

COPYRIGHT

Copyright (c) 2000, 2001, 2002 Perforce Software, Inc. All rights reserved.

See VCP::License (vcp help license) for the terms of use.