VCP::Source::vss - A VSS repository source
vcp vss:project/...
Source driver enabling vcp to extract versions form a vss repository.
The source specification for VSS looks like:
vss:filespec [<options>]
filespec may contain trailing wildcards, like /a/b/... to extract
an entire directory tree (this is the normal case).
NOTE: This does not support incremental exports, see LIMITATIONS.
-b, --bootstrap
-b ... --bootstrap=... -b file1[,file2[, etc.]] --bootstrap=file1[,file2[, etc. ]]
... 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
This is an advanced option that allows you to use a VSS workspace you establish instead of letting vcp create one in a temporary directory somewhere. This is useful if you want to read from a VSS 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.
--rev-root
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
vss:/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.
VSS has one peculiarity that this driver works around.
If a file does not contain the tag(s) used to select the source files,
vss log outputs the entire life history of that file. We don't want
to capture the entire history of such files, so VCP::Source::vss goes
ignores any revisions before and after the oldest and newest tagged file
in the range.
"What we have here is a failure to communicate!"
- The warden in Cool Hand Luke
VSS does not try to protect itself from people checking in things that look like snippets of VSS 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 "vss log" command, things will likely go awry.
At least one vss 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:...".
We lose comments attached to labels: labels are added to the last "real" (ie non-label-only) revision and the comments are ignored. This can be changed, contact me.
We assume a file has always been text or binary, don't think this is stored per-version in VSS.
Looks for deleted files: recovers them if found just long enough to cope with them, then deletes them again.
VSS does not track renames by version, so a previous name for a file is lost.
VSS lets you add a new file after deleting an old one. This module
renames the current file, restores the old one, issues its revisions,
then deletes the old on and renames the current file back. In this
case, the rev_ids from the current file start at the highest
rev_id for the deleted file and continue up.
NOTE: when recovering a deleted file and using it, the current version takes a "least opportunity to screw up the source repository" approach: it renames the not-deleted version (if any), restores the deleted one, does the History or Get, and then deletes it and renames the not-deleted version back.
This is so that if something (the OS, the hardware, AC mains, or even VCP code) crashes, the source repository is left as close to the original state as is possible. This does mean that this module can issue many more commands than minimally necessary; perhaps there should be a --speed-over-safety option.
No incremental export is supported. VSS' -V~Lfoo option, which says
"all versions since this label" does not actually cause the ss.exe
History command to emit the indicated checkin. We'll need to make the
history command much smarter to implement that.
VCP::Dest::vss, vcp, VCP::Process.
Barrie Slaymaker <barries@slaysys.com>
Copyright (c) 2000, 2001, 2002 Perforce Software, Inc. All rights reserved.
See VCP::License (vcp help license) for the terms of use.