Migrating from Perforce#

Unity Version Control (UVCS) lets you migrate, and keep synchronized, a Perforce (P4) repository. The P4 Sync command can import metadata, data, and P4 branches in a bidirectional way.

Workflow#

The P4Sync command seeks new P4 changesets to import into UVCS, and vice versa. It scans the repositories for missing UVCS changesets to import into P4. When the search operation finds new changesets or changelists, the process synchronizes them.

You can use the same command to synchronize the data bidirectionally between the two version control systems, P4 and UVCS. You don't need to change the command syntax to pull from P4 or pull from UVCS; both operations take place simultaneously.

By default, when you run the sync command for the first time, all the P4 history for the given depot path syncs into the empty UVCS repository. The first P4 changelist is usually the most challenging, as many assets are typically added at the beginning of the P4 repository. Don't worry if you see the command stop at a changelist; it likely contains numerous changes, and the importer is processing it.

The sync command provides periodic updates on the ongoing process. You can enable the cm log file to view additional debug information. To learn how to do this, see https://www.plasticscm.com/documentation/technical-articles/kb-enabling-logging-for-plastic-scm-part-i

CLI Usage#

cm sync <repspec> p4multibranch <p4server> [--mainbranch=main_branch_folder] [--branchesfolder=branches_folder] --user=usr_name --pwd=password

Options#

Import example#

Given the P4 repository structure below, where //depot/project/dev is the main branch folder, then //depot/project/release-01 and //depot/project/release-02 branch folders.

//depot/project/dev
//depot/project/release-01
//depot/project/release-02

The command to synchronize the entire structure from the very beginning of the P4 history would be:

cm sync MyRepoName@catacroquer@cloud p4multibranch p4Server:1666 --mainbranch=//depot/project/dev --branchesfolder=//depot/project --user=p4_read_user --pwd=password

If you don't want to import the P4 branches, do not specify the --branchesfolder= parameter. The tool will import just the main branch.

Recommentations#

Moving a P4 repository involves a lot of data. The process might hit the overall machine performance by flooding the TMP directory. We recommend using the -tmpwkpath parameter and redefining the OS PATH variable for the import session. Stick to the P4 history you need to import. The --first parameter is handy to eliminate unneeded old history. Also, use the --excluded parameter to entirely skip P4 depot paths you won't need at the UVCS repository. cm sync p4multibranch uses the Perforce CLI tool (p4) to manage the P4 data and metadata. Ensure you have a p4 tool configured with the correct access to the depot at the OS Path env variable. P4 history can be a case sensitivity mess. You can find entries referring to the same item using different case. UVCS is case-sensitive, so to prevent issues and end up with duplicated entries, use the --caseinsensitive parameter.

Limitations#

The branches are always created in UVCS using the full content of the starting point. If only a subdirectory of //depot/project/main/...@24 is branched in P4, we will see the full content under //depot/project/main/... in UVCS. The P4 branches created from custom configurations don't keep this custom configuration in UVCS. A UVCS branch always starts from an existing and defined configuration (changeset). So, the importer will choose only one specified path@changelist configuration as the branch base. The net.parallel.max P4 setting must be set (to a value higher than 1) to enable parallel download of contents while syncing. However, in those scenarios where the user is not a super user, parallel processing won't be enabled by default as it requires to check a p4 variable and it will fail in this case. The workaround is asking a super user (usually a company admin) to set both variables: net.parallel.max and net.parallel.threads and these values will be used during the sync. You can also force the number of threads to download data from p4 by using the parameter --p4threads=X. You can only migrate one P4 path into a UVCS repository.

Known Issues - Pull#

The sync operation ignores the P4 changelists that contain changes of different branches (or what we consider different branch folders) in the same changelist. When the P4 changelist used to create the branch (populate/integrate commands) only contains delete operations, we don’t use it as the branch base. In this scenario, we use the closest parent changelist with any change different than a delete as the starting point. The CLI progress while pulling content from P4 might display inconsistent data. For example, if the P4 depot contains 500 changelists, the CLI will display 500 changelist to pull. But the import might affect only 200 changelist, and then the 500 count is inaccurate. This works this way to avoid requesting all the P4 changelists at once at the beginning because it can be slow and error-prone. The sync operation can display there are new P4 changelists to pull, although it later pulls nothing. This happens if these changeslist were pushed from UVCS before or if new changelists in the depot apply to paths unrelated to what's being synchronized. The sync operation can leave some empty directories in UVCS. This is because p4 is not capable of versioning directories, so when all the content of a directory is removed the directory is left empty.

Known Issues - Push#

The sync report might show some skipped changes for the following reason: The path couldn't be deleted. This report is harmless. It will just keep a file loaded in p4 that shouldn't be there (in the worst scenario). Perforce doesn't support reusing a path in the same changelist. Therefore we cannot export these changes from UVCS to Perforce. In these cases, we do our best to keep the same structure on the Perforce side. The push ignores changes on empty directories since p4 doesn't handle directories.