NAME

VCP::Source::vss - A VSS repository source

SYNOPSIS

   vcp vss:project/...

DESCRIPTION

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.

OPTIONS

#=item --cd # #Used to set the VSS working directory. VCP::Source::vss will cd to this #directory before calling vss, and won't initialize a VSS workspace of #it's own (normally, VCP::Source::vss does a "vss checkout" in a #temporary directory). # #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. ## #=cut

-V

   -V 5
   -V 5~3

Passed to "ss History".

undocheckout

If set, VCP will undo users' checkouts when it runs in to the "File ... is checked out by ..." error. This error occurs when scanning metadata for a file which is checked out by somebody and there is also a deleted file of the same name. NOTE: The VSS account VCP uses may need administrative prividges to perform UndoCheckout on files checked out by some other user.

Files that aren't tagged

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.

LIMITATIONS

Many and various. VSS, aside from its "normal" level of database corruption that many sites either deal with regularly or manage to ignore, also has many reporting and, from what I can tell, data model flaws that make it challenging to figure out what happened when.

files: Returns a reference to the FilesDB for this backend and repository. Creates an empty one if need be.
This is like VCP::Dest::files() but most other sources do not need to do this, so these are

VSS NOTES

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.

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_id"s from the current file start at the highest "rev_id" for the deleted file and continue up. This can cause problems if somebody has the file checked out, use the --undocheckout option to force VCP to undo the checkout and carry on.

Looks for deleted files: recovers them if found just long enough to cope with them, then deletes them again. Repeatedly, if need be.

NOTE: when recovering a deleted file and using it, the current version takes a "create the smallest window of opportunity to leave the source repository in an uncertain state" 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 or a transaction log & recovery system.

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.

Haven't tested many real-world scenarios yet.

If you specify a filespec that matches files branched from files not included in the filespec, VCP pretends that the first revision of the file at the new location is the first revision ever.

SS.EXE, which VCP uses for all SourceSafe operations, may ignore it's -I- option, which should prevent it from seeking input, and seek input. This can hang VCP, but it's usually when hitting ^C. This can leave SS.EXE running in a state consuming 100% CPU while waiting for a password. Use the Task Manager to clean up such processes.

•: Share-ing a project

AUTHOR

Barrie Slaymaker <barries@slaysys.com>

COPYRIGHT

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

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 27:: You can't have =items (as at line 46) unless the first thing after the =over is an =item
Around line 281:: '=item' outside of any '=over'
Around line 1279:: You forgot a '=back' before '=head1'