Perforce Integration FAQ

Commonly aksed questions about Perforce terminology and usage details.

Windows
MacOS
Linux

This document provides an understanding of many of the common uses of Perforce with Unreal Engine 4, as well as related terminology.

To help simplify the merge process, an auto-merge tool has been created that can be integrated into P4V and P4Win. It automates several of the tedious steps and best practices described in this doc. For more information, see the Perforce AutoMerge page for more information.

Frequently Asked Questions

What does integrate, merge, and branch mean in Perforce?

They all mean the same thing and are accomplished using the Integrate command. A Branch is usually referred to as an integration that creates a new file in a new location. A Merge is an integrate between two previously-branched files.

Why do all these complicated steps when I can just copy the file over and change it?

Perforce keeps a searchable, graphable database of all changes and integrations that have ever taken place. Merging "by hand" severs the database tracking records, makes it impossible to track code history, makes the branches harder to maintain, and makes it more difficult for you and Perforce when an integrate is done correctly. Symptoms could be anything from Perforce refusing to integrate files to ridiculously difficult resolves for simple changes.

How do I integrate a single changelist?

It is highly recommended to use P4V when integrating, as there have been many improvements to the UI to visualize the process. Everything ultimately resolves to the same underlying P4API calls, so both P4V and P4Win support the same feature set.

To integrate a single change in P4V:

  • Make sure your active workspace contains the branch you are integrating to. * There is no need to include the source branch in your workspace.

  • Right-click on the changelist you want to integrate and select Integrate using submitted changelist 'change#'.... You should see a dialog similar to this:

P4VIntegrate.jpg

  • Under Choose integration method, select Use branch specification and select the branch you want to use.

  • If you deleted or re-added a file: Click on Advanced options... and section by clicking on the triangle icon. Under Enable integrations around deleted revisions, select the appropriate options. Generally you want Delete target file when source is deleted. Do not select any other options unless you are sure of what you are doing!

P4IntegrateAdvancedOptions.JPG

  • Always use the preview button to check for errors. You cannot complete the integration if there are errors. P4V now supports visual inspection of integration errors. You will see a treeview of all files integrated, with files that cannot be integrated highlighted in red. You can use the red arrows to iterate through the errors. The Description field will explain exactly why each file cannot be integrated. You can also switch between a classic flat view or the newer tree view. * If you cannot figure out the errors, get someone to help you.

P4VPreview.JPG

  • Select New changelist to ensure you do not mix existing changes with this merge.

  • click Finish to create the new changelist.

  • Resolve the integrated files by following the instructions below .

  • Test everything thoroughly before submitting.

  • Remember to use the changelist description guidelines mentioned later in this guide.

To integrate a single change in P4Win:

  • Open Revision History and Right-click on the changelist you want to merge, then select Integrate Using|Branchspec...

  • Select the branchspec from the list.

  • If you deleted or re-added a file: Select Options...|Permit deletes/re-adds. Select deletes only, re-adds only or both radio button as appropriate. * Do not select any other options unless you are sure of what you are doing!

  • P4Win does not have a visualization tool for previewing, so you will have to read the text in the output window. * If you are having trouble with this, get someone to help you.

  • Select New changelist to ensure you do not mix existing changes with this merge

  • Click Finish to create the new changelist.

  • Resolve the integrated files by following the instructions below .

  • Test everything thoroughly before submitting.

  • Remember to use the changelist description guidelines mentioned later in this guide.

What is the safest way to resolve files quickly?

Each file integrated must be resolved before checking in. Difficult conflicts will sometimes require help from the original submitter. To ease the process, Perforce has a few options for auto-resolving simple merges to pare the list down. P4V and P4Win both provide access to these options. The safest way to proceed is in the following order: 1. Safe automatic resolve - auto-resolve changes if the file has only changed in one branch since the last merge. This is always safe because it can just copy the changed file over. 1. Automatic resolve - resolves changes if the file has changed in both branches but no conflicts exist. 1. Interactive resolve - any files left will be the hard ones where changes in both branches conflicted.

* To deal with these, you will use a merge tool such as:
    * [Araxis Merge](http://www.araxis.com/), or 
    * P4WinMerge.

P4VResolve.jpg

Notes:

  • Safe Automatic resolve will often take care of most files automatically.

  • Be very careful when merging files interactively; ask for help if you need to!

What is left will be files that were changed in both branches.

P4V will display a summary count of the changes and conflicts found, and give you a set of tools to assist (open, diff, history, time lapse).

P4VResolveIndividual.jpg

When you are ready, click Run Merge Tool to run your registered merge tool to perform the actual merge. P4V's built-in merge tool is recommended because it gives a 4-way pane that always displays the source, base, target, and merged result, color coded for the source of each change. Many other merge tools (like Araxis) only display 3 panes, so the base version is overwritten as you perform the merge. For more details on the color/icon scheme that P4Merge uses, see the P4Merge Help Viewer (press F1 while merging).

P4VMerge.jpg

When all files are resolved, you can submit your change.

What should I put in my checkin comments when I have finished an integration?

While technically Perforce is tracking the integration in its internal database, indicating your intentions in the comments will help others understand that this change originated from a different branch.

When you check in:

  • Include a sentence that indicates your integrating code, and what changelist range it came from. Ideally you are only integrating a single changelist for each submission. Tangling integrated changelists together in a single submission can make it difficult to fix merge problems later on.

  • To make everyone's life easier, re-summarize the changes and any modifications you had to make. Just copy and paste them from the original changelists, if nothing else!

I have several changes that need to be integrated. Can I integrate them all at once?

Please do not. It is better if you use a separate submission for each integrated changelist. While it is possible to integrate multiple changelists at one time, it is not recommended. It can make the merge process extraordinarily difficult, especially if there are overlapping changes to the same file. Also, if you integrate one file more than once without checking in, you cannot undo a single integration if there are problems.

I have a merge that is so difficult that resolving is impossible. Should I just do it by hand?

You should still perform the integration to inform the Perforce database that the change has been integrated. You should perform the integration as normal, but during the resolve phase, you should "accept yours". This will not change the local files, but will tell Perforce that those files have been integrated.

Then, before checking in, you should reopen for edit the appropriate files and make the required changes in the new code. That way you create a single changelist that represents the integration of that change into your codeline.

There have been many changes to a file in either the source or destination branch since the changelist that I am interested in was submitted. Is it OK to merge this change?

Generally yes, this should work fine. Even if the file has been changed significantly (or deleted!) since the change was made in the source branch, by following the above instructions, Perforce will integrate only the precise changes that you are interested in. Of course, the older a changelist is, the more likely there will be merge conflicts to deal with in the destination branch.

Should I ever integrate a file (or set of files) instead of a changelist?

It is not recommended that you do this, unless you have a really good reason to. You should always perform integrations by selecting an individual changelist, integrating it over, testing it, and submitting it. If you integrating files directly, you will be merging any and all unintegrated changes to that file in the source branch! This means you may introduce unwanted changes to the target branch, or changes that have dependencies on non-existent code. Avoid this by merging only the precise changelists that are needed.

Should I revert files that I am not changing when I am done?

  1. You should always check in all files that you integrated from a changelist. Even if the file is not changing, checking it in will update the Perforce database with the integration information.

Perforce stores integration history on a per-file basis, not a per-changelist basis. If you integrate a changelist but then revert some files, it makes analyzing the database more difficult because some changelists will be listed as only having been partially integrated.

I have decided that a changelist should not be integrated. Should I do anything?

This is known as a NULL Merge. If you are absolutely sure that a change you submit will never be needed in the other branch, it is often helpful to go ahead and perform a NULL merge anyway. To perform a NULL merge, integrate the files and resolve them by selecting "accept yours." This will create an official record that that particular change has already been examined by someone and nothing was done. This simplifies the process for those maintaining the branch because that change will not be included in the list of pending changes to integrate in that branch.

Whether this is necessary depends on the policy of the codeline and how integrations are being managed, so you should check with the curator of that codeline to see if this should be done for your changes.

When performing a NULL merge, you should mention the changelist number in your checkin description and the fact that it was a NULL integration so there is no confusion when the integration records are analyzed later.

I want to integrate in the opposite direction than how the branch is set up. How do I do this?

Branchspecs should be set up so the normal flow of change is the default direction. Generally this is done when it is time to merge the branch and deprecate it.

Perforce supports "reversing" a branchspec during integration:

  • In P4V, you can simply click on the green arrow in the Select branch specification section. See the screenshot in the integration item . * There is even text there in case you forget.

  • P4Win seems to automatically detect reverse requests. * Just integrate the changelist using the same branchspec and it will automatically determine that it should reverse the mapping.

I am trying to integrate a change with files that should not exist in the target branch. What should I do?

The branchspec should be updated to exclude these files from integrations. Talk to the owner of the branchspec and have them unmap those files.

Typically when this happens, Perforce will do either one of two things: 1. Provide a warning that it cannot perform the integration without the -d or -dt flags. 1. It will perform the integration and try to branch the new files.

* While you can add -d to force the integration and revert those files before checking in, it is strongly discouraged for two reasons:
    1. It is error-prone. Fixing the branchspec when the problem is found will make sure you or anyone after you will not accidentally (re)add those files. 
    1. It does not play nice with the Perforce integration database because Perforce will always think that there are still files in that changelist that need to be integrated.

For example, The Delta-To-Main branch (Gears PC) had a WarGame folder that only Delta needed, and WarGame was removed from Main. When trying to integrate a change that included a file in WarGame, Perforce would complain that it required the -d or -dt option to integrate "around deleted revisions." To fix this, WarGame was removed from the Delta-To-Main branchspec so Perforce would no longer try to integrate those files.

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback