Perforce Public Knowledge Base - Determining Revisions to Integrate
× PRODUCTS SOLUTIONS CUSTOMERS LEARN SUPPORT
Downloads Company Partners Careers Contact Free Trials
Menu Search
Perforce
Reset Search
 

 

Article

Determining Revisions to Integrate

« Go Back

Information

 
Problem

This article describes how Perforce determines which source file revisions need integrating when you run the p4 integrate command, and what happens to the corresponding target file. For more information on integrations and branching, please see Chapter 6 of the Perforce User's Guide.


Solution

There are three ways you can run p4 integrate that affect how revisions are selected:

  • You give no starting or ending revisions. You only give the paths, and Perforce picks the starting and ending revisions to use when selecting source file revisions to integrate. For example:
    p4 integ source/... target/...
    
  • You supply an ending revision. For example, to integrate all source path changes, up to and including changelist 300, into the target path:
    p4 integ source/...@300 target/...
    
    In this case, Perforce picks the starting revision.

     

  • You supply both a starting and an ending revision. For example, to integrate changelists 300 through 350 from the source path to the target path:
    p4 integ source/...@300,@350 target/...
    

After receiving your p4 integrate command, Perforce pairs up source and target files. Then, for each file pair, it lists all candidate revisions, and subtracts previously integrated revisions. The remaining revision list is then used to determine if, and how, to open the target file, and whether to schedule a resolve.

Pairing up source and target files

Perforce uses either the named branch view you supply, or the source and target paths you supply, to generate lists of source and target files. These lists are joined to produce a list of source and target file pairs. For example, if you run:

p4 integrate source/... target/...

and one or both of the files "source/foo" and "target/foo" exist, the "source/foo target/foo" pair forms an entry in the list. Each pair in the list is examined separately.

Listing candidate source revisions

Perforce assumes all revisions of the source file are candidates for integration into the target. For example, if the head revision of source/foo is #30, the candidate list for integrating source/foo to target/foo is:

Starting revision: source/foo#1
Ending revision:   source/foo#30

However, if you supply a starting and/or ending revision, Perforce adjusts the candidate revisions accordingly. For example, say source/foo@300 is #2 and source/foo@350 is #10:

p4 integrate source@300 target          
Starting revision: source#1
Ending revision:   source#2

p4 integrate source@300,@350 target 
Starting revision: source#2
Ending revision:   source#10 

Another adjustment occurs if the source file has been deleted and re-added within the starting and ending range: the starting revision is raised to the most recent "add" revision. For instance, if source#3 is a "delete" and source#4 is an "add", the adjusted candidate range for the last example above is:

Starting revision: source#4
Ending revision:   source#10 

 

Subtracting previously integrated revisions

Perforce's integration history stores the revisions of the source file that have previously been integrated into the target file. If the target was branched from a revision of the source, all source revisions up to and including the branched revision are considered previously integrated.

Previously integrated revisions are subtracted from the list of candidate revisions. For example, if source#4, source#5, and source#9 have already been integrated, the final list of revisions to integrate in the example above will be #6, #7, #8, and #10:

source#6
source#7
source#8
source#10

This is the final list of revisions to integrate. It is also the list of revisions that are added to the integration history for this source-target pair when the target file is submitted.

For the rest of this article, the starting and ending revisions to be integrated will be referred to as "#start" and "#end", even though there are no such special revision identifiers in Perforce. ("#head" and "#have", on the other hand, are valid special identifiers that can be used in Perforce commands.) Note that "source#start" means the start of the list of revisions to be integrated, whereas "source#1" means the first revision of the source file, and "source#end" means the ending revision of those to be integrated, whereas "source#head" means the most recent revision of the source file in the depot.

What happens to the target file?

Once Perforce has determined the list of revisions to be integrated for a given source-target pair, it tests a number of factors to determine what should happen to the target file. One factor is the action associated with each revision -- you can use the p4 filelog command to show these. There are a number of possibilities:

  • If the target file does not exist, and source#start is a "branch" or an "add", Perforce branches source#end into the target file. The target file is opened for "branch", and no resolve is scheduled.

    Submitting this target file creates integration history in two directions: one entry showing that source#start through source#end have been integrated to the target, and one entry showing that target#1 has been integrated into the source.

  • Prior to 2010.1, if the target file does not exist, and source#start is not a "branch" or an "add", the target file is not opened.

    For these earlier server versions, you can compel Perforce into adding the new target file by using p4 integrate -d. With -d, the target is opened for branch; no resolve is scheduled. (Note that previous to Release 99.2, the default behavior was to open the target file for branch.)

    For 2010.1 and later versions, the pre-99.2 behavior has returned.

  • If both the source and target files exist, and target#head is a "delete", and source#start is not a "branch" or an "add", the target file is not opened.

    You can compel Perforce into re-adding the target file on top of a delete by using p4 integrate -d. With -d, the target is opened for branch; no resolve is scheduled. (Note that previous to release 99.2, the default behavior was to open the target file for add on top of a delete.)

  • If both the source and target files exist, and source#end is a "delete", and there are "edit" or "integrate" revisions of the target file that have not been integrated into the source file, the target file is not opened.

    To force Perforce into opening the target file for delete on top of an edit, use p4 integrate -d. With -d, the target is opened for delete, and no resolve is scheduled. (Note that previous to release 99.2, the default behavior was to open the target file for delete on top of an edit.)

  • If both the source and target files exist, and source#start is an "edit" or an "integrate", the target file is opened for integrate and a resolve is scheduled. When you do the resolve, Perforce does a 3-way merge using the starting revision's predecessor as the base. For example, if the starting revision is source#6 and the ending revision is source#10, the 3-way merge uses:

    • source#5 as the base
    • source#10 as "theirs"
    • target#have as "yours"
  • (2004.2 or later) If both the source and target files exist, source#start is an "add" or a "branch", and the source and target files have an established integration relationship via another file, Perforce does a 3-way merge, using the closest common ancestor revision as the base. If the -o option was provided to the p4 integ command, this base revision is displayed as part of the output.

  • If both the source and target files exist, and source#start is an "add" or a "branch", and either of the following is true:

    1. The server version is 2003.2 or earlier
    2. There is no prior integration relationship between the files

    the target file is not opened. Why not? Because there is no predecessor revision of the source file to use as a base for a 3-way merge. (Note that the ability to select common ancestor revisions from outside the source file was added in release 2004.2.)

    Failing this, the -i flag tells Perforce to use the original source#start itself as the base for a 3-way merge, enabling a merge that would otherwise be "baseless". The target is opened for integrate, and a resolve is scheduled. If, for example, starting revision source#6 were an "add", the 3-way merge done by the resolve would use:

    • source#6 as the base
    • source#10 as "theirs"
    • target#have as "yours"

    Note that prior to Release 99.2, Perforce opened the target for integrate, even if it could not find a merge base. When you did the resolve, Perforce would do a 2-way merge, because it had no predecessor to the starting revision to use as a base for a 3-way merge.


Getting Integration Detail


To get detail about a pending integration, such as the source, target, and base paths for the file that's been integrated, but not submitted, use this p4 fstat command:
p4 fstat -Ro -Or -e CHANGE# //...

and look for these fields:

... depotFile <target>
... resolveFromFile0 <source>
... resolveBaseFile0 <base>
 
Related Links

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255