# P4Convert: User Guide (April 2015)

# Setup

## System Requirements

1. [SVN] an unzipped Subversion dump file of the repository to be converted (generated without the `--delta` flag).

2. [CVS] an unzipped CVSROOT directory containing the RCS files of the repository to be converted.

3. System must have Java SE Runtime 1.7.

4. System must have the Perforce Server binaries 2010.2 or greater.

5. [Import Mode] A running Perforce Server (typically empty) with no pending changes in the conversion area.

6. [Convert Mode] An empty Perforce Root directory for the generated archive and journal files.

### Resource Tips:

Running some conversions, particularly in Conversion Mode can be very memory intensive, as a mapping of revisions and integrations is kept in memory. For large conversions, or conversions with excessive branching, more memory will needed by the JVM.

The `--info` option will scan the Subversion dump file and report usage data to help estimate the required memory for Convert Mode. For example:

    java -jar p4convert.jar --type=SVN --repo=<path_to_svn_dumpfile> --info

Use the `-Xmx` flags to increase the memory allocated to the JVM. For example, to allocate 64GB (65536MB) use:

    java -Xmx65536M -jar p4convert.jar --config=myConfig.cfg

## Caveats

1. The following table lists the combinations of tested operating systems and Perforce Server versions.

   Operating System | 10.2 | 14.1
   --- | --- | ---
   Ubuntu 10.04 | supported | supported
   Darwin 11.4.0 | supported | supported
   Windows 7x64 | supported | supported
   SunOS 5.10 | supported | supported

   It is likely that other combinations will work, however it is not possible to test all combinations.

   Please contact Perforce if you have any OS or version queries.

2. [Import Mode] Symbolic links are not supported in Import Mode on Windows.

3. Perforce keyword expansions are different from the Subversion standard and may yield different results when synced. CVS keyword detection is not yet supported.

## Setup and Usage

Download the self-contained JAR from Perforce and check that Java SE runtime is installed with version 1.7 or greater.

For usage details, execute the jar with no options:

    usage: java -jar p4convert.jar
     -c,--config <arg>    Use configuration file
     -d,--default         Generate a configuration file
     -E,--end <arg>       End revision, for incremental (SVN)
     -e,--extract <arg>   Extract a revision
     -i,--info            Report on repository usage
     -r,--repo <arg>      Repository file/path
     -S,--start <arg>     Start revision, for incremental (SVN)
     -t,--type <arg>      SCM type (CVS | SVN)
        --tags <arg>      find tags to specified depth
        --tree <arg>      (with --info), display tree to specified depth
     -u,--users           List repository users
     -v,--version         Version string

    Example: standard usage.
       java -jar p4convert.jar --config=myFile.cfg

    Example: generate a CVS configuration file.
       java -jar p4convert.jar --type=CVS --default

    Example: report Subversion repository usage.
       java -jar p4convert.jar --type=SVN --repo=/path/to/repo.dump --info

To create a default configuration file using the `--default` option. You will need to specify the SCM type using `--type` (with a value of SVN or CVS). The generated file (default.cfg) will contain a set of default configuration options based on your platform. Rename the `default.cfg` to your own configuration. To run a conversion using your configuration file, execute the jar with the `--config` flag specifying you config file. For example:

    java -jar p4convert.jar --config=myFile.cfg

## Generating a Subversion Dump file

For Subversion conversions, both Import and Convert modes require a Subversion dumpfile as the historic data source. A dumpfile can be generated in several different ways, two of which are detailed below:

- Using the svnadmin command:

      svnadmin dump local_repo_path > dumpfile.dmp

  Replace `local_repo_path` with the path to the Subversion repo. Do not use the `--delta` flag option as the results cannot be parsed by the conversion tool.

- Using the remote dump command:

      rsvndump url > dumpfile.dmp

  Replacing `url` with the remote Subversion server. For example: `http://` or `file://` or `svn://`. Note that for large servers generating the dump file locally is significantly faster, so you might also consider creating a local copy of the subversion depot using svnsync, before generating the dump file.

## Selecting a CVS root

For CVS conversions, both Import and Convert modes require a path containining RCS files as the historic data source. CVSROOT can be filtered or imported on a per module basis. The converter will only import file revisions under the specified CVSROOT path.

Hide partial matches
Highlight matches
0 matching pages