Documentation

Support

Unity Version Control

DevOps

On-prem

Gluon

Editor plug-in

Open Unity Dashboard

Unity Version Control

Migrating from Perforce

Migrate projects from Perforce to Unity Version Control.
Read time 5 minutesLast updated 21 days ago
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. For more information, refer to the 
cm log
reference page.

CLI Usage

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

Options

Option / Argument

Description

repspec
The UVCS repository you want to syncronize with P4 data.
p4server
The P4 server address. It should also include the P4 server port.
--tmpwkpath
Location for the temporal p4 workspace.
--skipplasticbranches
Path to a file containing a list of branches you want to avoid pushing to P4. The file format is one UVCS branch per line. The branch prefix (
br:
) can be omitted.
Example:
/main/Fix-5.4/SCM4767

/semanticmain/ReleaseSMT-0.9.40.0
--skipp4branches
Path to a file containing a list of P4 branches you want to avoid pulling. The file format is one P4 branch (absolute depot path) per line.
Example:
//depot/Fix-5.4

//depot/SCM1002
--skipp4paths
Path to a file containing a list of P4 files/folders to skip during the pull. The file format is one P4 path (relative path, it applies to all branches) per line. Example:
/lcc/alpha/bin

/legal/COPYING.txt
--caseinsensitive
P4 arbitrarily uses different cases for the same path in its history, so you might have log history entries for 
/Assets
and 
/assets
being it the same item. Without this parameter, both paths are different items inside UVCS as the UVCS server is case-sensitive.
--excluded
You can use the 
--excluded=excludeFilePath
parameter to target a configuration file containing P4 depot path rules to ignore during the migration. For example, if you want to sync the 
//depot/stream
P4 depot path but you don't want to migrate the 
//depot/stream/subdirtoexclude
subdirectory, then the config file must have 
/subdirtoexclude
written to ignore it, as you can see it's a relative path to the root sync path.
--continueonp4error
Don't stop the process if the P4 commands are failing.
--first
Specify the first P4 changelist to import.
--last
Specify the last P4 changelist you want to import.
--bypassmetadatatocomment
You can push changesets from UVCS to Perforce with a Perforce user without 
admin
or 
super
privileges. It will make the impersonation fail. Use this option to write the owner and the date of the UVCS changeset into the Perforce changelist comment, instead of the 
Owner
and 
Date
properties of the Perforce change object.
--traceinfo
It adds UVCS changeset information to the P4 changeslist created while pushing into P4.
--commentseparator
Use this option to customize a separator for the comments added automatically by UVCS (e.g.: when 
--traceinfo
option is set). If 
--commentseparator
is not specified the default separator P4Sync uses a couple of new lines.
--p4threads
Number of threads used to download data from the P4 server.

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.