Running P4Convert

Import Mode

Import Mode will pull in file revisions from a Subversion dump file or CVS repository, adding them to the Perforce Server specified by the connection details in the configuration options. To use this mode set: 

com.p4convert.p4.mode=IMPORT

Care should be taken when adding data to a pre-existing Perforce Server that the revision actions do not conflict with revisions already in the Perforce Server; typically, this can occur if the Server has been in-use since the previous migration.

To avoid such scenarios the import should either be to a unique depot, to avoid conflict, or the Perforce Server should be Read Only during subsequent migrations. After a conversion is complete, it is possible to merge the new data with an existing depot using tools like PerfMerge++.

The converter will check that your Perforce Server has no pending changes, and will abort a conversion if any are detected.

Configuration options specific to Import Mode

  1. Perforce server address and port (escape the ':' with '\:'): 

    com.p4convert.p4.port=localhost\:4444

  2. Default user and client for server connection: 

    com.p4convert.p4.client=p4-client
com.p4convert.p4.user=p4-user

  3. Client workspace root used to import files into Perforce: 

    com.p4convert.p4.clientRoot=/Users/bruno/ws/

  4. If Security is set to level 1 or greater, then the p4-user must have admin permissions in the Protection table and the password supplied as a string (the default is set to ws/ under your local directory): 

    com.p4convert.p4.passwd=PaSSwoRd

  5. Alternatively if the user is already logged in and there is a valid ticket, then leave the password field unset and set your environment for P4TICKETS (don't rely on the P4TICKETS unset default as p4-java will not find your ticket file).

Convert Mode

Convert Mode is more advanced and requires knowledge of the Perforce Journal replay and Archive file store. This mode can only be used for single shot conversions and cannot be used incrementally. The performance of Convert Mode is significantly better than Import Mode (x100 sometimes!).

After using Convert Mode the administrator will need to run several commands to rebuild the Perforce server and upgrade the metadata. Please refer to the Post Conversion [Conversion Mode] section for step-by-step instructions.

To use this mode set: 

com.p4convert.p4.mode=CONVERT

Configuration options specific to Conversion Mode

  1. Perforce server root address (path should end with a slash (/)), the default is set to p4_root/ under you local directory: 

    com.p4convert.p4.root=/full/path/to/p4_root/

  2. Change list offset from which to start conversion (handy for batched conversions): 

    com.p4convert.p4.offset=0

  3. Generated journal names (useful to increment the prefix when running batched conversions): 

    com.p4convert.p4.jnlIndex=0
com.p4convert.p4.jnlPrefix=jnl.

  4. Mimic the 2011.1 or greater credit behavior on rollbacks / downgrades (to enable set value to true): 

    com.p4convert.p4.downgrade=false

  5. Perforce normalises line-endings when storing the file on the server and restores them based on the client workspace options and platform type. However, in special cases it can be useful to store line-ending in the server and use the 'share' option in the client. To disable normal line-ending support set the following option to false: 

    com.p4convert.p4.lineEnding=true

  6. For non Unicode servers, or to simplify storage of hi-ASCII files, setting the following option to false will store the file as binary: 

    com.p4convert.p4.unicode=false

Post Conversion [Conversion Mode]

To finish a Convert Mode conversion you will need to install p4 and p4d and run a few Perforce commands.

  1. [Required] Change directory to P4ROOT, check there are no db.* files present and then replay the journal file(s): 

    $ cd p4_root
$ p4d -r . -jr jnl.0
Perforce db files in '.' will be created if missing...
Recovering from jnl.0...
Perforce server info:
	Server version 33 is replaying a version 0 journal/checkpoint.

    Note

    The Server version is set to 0 to remind the administrator that an upgrade is required, see step 3.

  2. or, for multiple journal files: 

    $ p4d -r . -jr jnl.0 jnl.1 ....

    and with nohup: 

    nohup p4d -r . -jr jnl.0 jnl.1 .... &

  3. [Required] Upgrade the database from 2004.2 schema. For simplicity the conversion generates a database using an old schema, allowing you to upgrade to a Perforce Server version of your choice. From the P4ROOT directory run the upgrade command: 

    $ p4d -r . -xu
Perforce db files in '.' will be created if missing...
2001.1: splitting db.integ into db.integed/db.resolve.
2001.1: splitting db.have into db.have and db.label.
2002.1: splitting pending db.change into db.changex.
2002.2: upgrading tempobj filetype in db.rev.
2002.2: upgrading tempobj filetype in db.working.
2003.1: initialize default depot.
2003.2: upgrading db.user.
2005.1: building db.revhx (headrev) table.
2005.1: building db.locks from db.working.
2005.2: building db.revdx (delrev) table.
2005.2: moving spec depot entries into db.revsx.
2007.3: (re)building haveMap from db.have/db.working.
2007.3: (re)building db.archmap (lazy-copy map) table.
2007.3: removing old db.archive.
2008.1: upgrading db.change.
2009.2: moving db.boddate/db.ixdate into db.bodtext/db.ixtext.
2009.2: removing db.boddate/db.ixdate.
2010.2: adding db.config.
2011.1: upgrading tiny.db.
...upgrades done

  4. [Optional] If the conversion was run in Unicode mode (where com.p4convert.p4.unicode=true) and users are going to continue to add Unicode content then you may wish to set the server to Unicode mode. To enable Unicode run the following command from the P4ROOT directory: 

    $ p4d -r . -xi

  5. [Alternative] If you are running your Perforce Server on Linux and your user base is predominantly Windows you may wish to force the server to run as case insensitive (only allowing one version of case for paths and files). The conversion option com.p4convert.adv.lowerCase=true will have been used with the case mode set to com.p4convert.adv.caseMode=FIRST. All p4d commands must be include the -C1 flag, this includes the earlier step 1 and step 2.

    For example: 

    $ cd p4_root
$ p4d -C1 -r . -jr jnl.0
$ p4d -C1 -r . -xu

  6. [Recommended] Some archive files may not have MD5 sum digests (typically where Subversion did not store the digest or the digest does not match due to the use of keyword expansion). To fill in the metadata for MD5 sum digests and archive file sizes use the verify command (this might be best split into depots and sub directories for large servers): 

    $ p4 verify -u //...