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]
vcp
('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 cvs:
, p4:
, and revml:
.
The general syntax of the vcp command line is:
vcp [<vcp options>] <source> <dest>
The three portions of the command line are:
<vcp options>
vcp
command, like
-d
for debugging or -h
for help. There are very few global options,
these are covered below. Note that they must come before the
<source>
specification.
<source>
<dest>
The <source>
and <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 cvs:/home/cvs/root:module
or
p4:user:password@server:port://depot/dir
.
When using the long form to access a repository, <source>
and
<dest>
specification have several fields delimited by :
and @
, and may have trailing command line options. The full (rarely
used) syntax is:
scheme:user(view):password@repository:filespec [<options>]
where
scheme:
p4:
, cvs:
, revml:
).
user
, view
, and password
cvs
does not use view
. For p4
, view
is the client
setting (equibalent to setting P4CLIENT
or using p4
's -c
option).
repository
filespec
<options>
cvs
, p4
, etc).
Most of these fields are omitted in practice, only the scheme
field is
required, though (in most cases) the repository
field is also needed unless
you set the appropriate environment variables (CVSROOT
, P4PORT
, 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 vcp 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:
vcp
Options
All general options to vcp must precede the <source>
.
Scheme-specific options must be placed immediately after the
<source>
or <dest>
spec and before the next one.
--debug, -d
--help, -h, -?
vcp help
.
--output-config-file=$filename
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
--versions
--terse, -t
(See also Generating HTML Documentation, below).
There is a slightly different command line format for requesting help:
vcp help [<topic>]
where <topic>
is the optional name of a topic. vcp help
without
a <
topic>
prints out a list of topics, and vcp help vcp
emits this page.
All help documents are also available as Unix man
pages and using the
perldoc
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
vcp help
is case insensitive, perldoc
and man
may or may not be
depending on your filesystem. The man
commands look just like the example
perldoc
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
-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 vcp
help
.
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.