vcp - Copy versions of files between repositories and/or RevML

   # interactive mode:

   vcp [vcp_opts]

   # scriptable command line mode:

   vcp [vcp_opts] <source> <dest>

   # getting options from a file:

   vcp vcp:config.vcp

   # help output:

   vcp help
   vcp help [topic]

CWvcp ('version copy') copies versions of files from one repository to another, translating as much metadata as possible along the way. This allows you to copy and translate files and their histories between revision storage systems.

Supported source and destination types are CWcvs:, CWp4:, and CWrevml:.

The general syntax of the vcp command line is:

   vcp [<vcp options>] <source> <dest>

The three portions of the command line are: Command line options that control the operation of the CWvcp command, like CW-d for debugging or CW-h for help. There are very few global options, these are covered below. Note that they must come before the CW<source> specification. Were to extract versions from, including any command line options needed to control what is extracted and how. See the next section. Where to insert versions, including any command line options needed to control how files are stored. See the next section.

The CW<source> and CW<dest> specifications specify a repository and provide any options needed for accessing that repository.

These spefications may be a simple filename for reading or writing RevML files (if the requisite XML handling modules are installed). or a full repository specification like CWcvs:/home/cvs/root:module or CWp4:user:password@server:port://depot/dir.

When using the long form to access a repository, CW<source> and CW<dest> specification have several fields delimited by CW: and CW@, and may have trailing command line options. The full (rarely used) syntax is:

   scheme:user(view):password@repository:filespec [<options>]

where The repository type (CWp4:, CWcvs:, CWrevml:). Optional values for authenticating with the repository and identifying which view to use. CWcvs does not use CWview. For CWp4, CWview is the client setting (equibalent to setting CWP4CLIENT or using CWp4's CW-c option). The repository spec, CVSROOT for CVS or P4PORT for p4. Which versions of what files to move. As much as possible, this spec is similar to the native filespecs used by the repository indicated by the scheme. Command line options that usually mimic the options provided by the underlying repositories' command line tools (CWcvs, CWp4, etc).

Most of these fields are omitted in practice, only the CWscheme field is required, though (in most cases) the CWrepository field is also needed unless you set the appropriate environment variables (CWCVSROOT, CWP4PORT, etc).

The a bit confusing, here are some examples specs:

   cvs:server:/foo
   p4:user@server://depot/foo/...
   p4:user:password@public.perforce.com:1666://depot/foo/...

Options and formats for of individual schemes can be found in the relevant help topics, for instance:

   vcp help source::cvs

Run CWvcp help for a list of topics.

When reading and writing RevML files, a simple filename will do (although the long form may also be used). The special value - means to read/write stdin and stdout when used as a source or destination name, respectively. - is assumed if a specification is not provided, so these invocations all accomplish the same thing, reading and writing RevML:

   vcp
   vcp -
   vcp revml:-
   vcp revml:
   vcp - -
   vcp - revml:-
   vcp - revml:
   vcp revml:- revml:-
   vcp revml: revml:

--debug, -d

Enables logging of debugging information.

--help, -h, -?

These are all equivalent to CWvcp help.

--output-config-file=$filename

Write the settings (parsed from the UI, the command line, or a config file to a file. Useful for capturing settings or user interface output. Does not affect running. Use - to emit to STDOUT. NOTE 1: This does not emit an Options: section containing global options (those listed here). Almost all of these options are not useful to emit; we can add an option to force their emission if need be. NOTE 2: When using the interactive user interface, this option takes effect after the last interactive portion and, if vcp goes on to run a conversion, before any conversion is run. This occurs in addition to any configuration files the user may ask the interactive interface to write. This may change in the future (for instance, if the interactive dialog includes an option to extract and analyze metadata).

--dont-convert

Do not run a conversion. Useful when you just want to emit a .vcp file.

--versions

Emits the version numbers of bundled files.

--terse, -t

Suppress verbose explanations when running the interactive UI. Has no effect on operation if all settings are read from the command line or a .vcp file.

--quiet, -q

Suppresses the banner and progress bars.

(See also Generating HTML Documentation, below).

There is a slightly different command line format for requesting help:

   vcp help [<topic>]

where CW<topic> is the optional name of a topic. CWvcp help without a CW<topicCW> prints out a list of topics, and CWvcp help vcp emits this page.

All help documents are also available as Unix CWman pages and using the CWperldoc command, although the names are slightly different:

   with vcp               via perldoc        
   ================       ===========
   vcp help vcp           perldoc vcp
   vcp help source::cvs   perldoc VCP::Source::cvs
   vcp help source::cvs   perldoc VCP::Dest::p4

CWvcp help is case insensitive, CWperldoc and CWman may or may not be depending on your filesystem. The CWman commands look just like the example CWperldoc commands except for the command name. Both have the advantage that they use your system's configured pager if possible.

The environment is often used to set context for the source and destination by way of variables like P4USER, P4CLIENT, CVSROOT, etc.

VCPDEBUG

The VCPDEBUG variable acts just like CW-d=$VCPDEBUG was present on the command line:

   VCPDEBUG=1

(see --debug, -d for more info). This is useful when VCP is embedded in another application, like a makefile or a test suite.

VCP::Process, VCP::Newlines, VCP::Source::p4, VCP::Dest::p4, VCP::Source::cvs, VCP::Dest::cvs, VCP::Source::revml, VCP::Dest::revml, VCP::Newlines. All are also available using CWvcp help.

Barrie Slaymaker <barries@slaysys.com>

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

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