"Cherry Picking" Integrations

Merging a single changelist from a range of unintegrated changelists

SUMMARY

By default, the p4 integrate command attempts to integrate (merge) all previously unintegrated changelists between two given source and target codelines (streams). However, it is possible to select and integrate a single changelist from within a range of unintegrated changelists. Integrating a single changelist from a range of unintegrated changelists is often referred to as "cherry picking". Below is a simple example of a "cherry picked" integration and a discussion of its repercussions.

DETAILS

Cherry picking integration is a method to precisely propagate content from one codeline or stream to another. By specifying a single changelist from a range of candidate changelists, the p4 integrate command operates on a smaller, more easily understandable content change (delta).

When you cherry pick integrations, you explicitly avoid merging other unintegrated changelists. What should happen with those other unintegrated changelists? By default, those unintegrated changelists keep showing up as candidates for integration until they are dealt with in some manner ("resolved" in Perforce parlance). If you perform cherry picking integrations, you should also likely perform "bookkeeping" integrations. See below for details on bookkeeping integrations.

Cherry picking integrations can also affect how the "base" file is chosen for future integrations. When you perform a "cherry pick", the base file chosen is often different than the base file that would normally be chosen if you integrated the full default range of unintegrated revisions.

Cherry picking integrations can also affect integration reporting. Specifically, the output of p4 interchanges can under-report changes where cherry picked integrations are involved. This is one of the reasons that the p4 interchanges command remains unsupported as of the current release.

Below is a screenshot from the P4V Revision Graph tool showing a cherry picked integration of a single revision:

To repeat this example on your own, run the following commands:

echo Change A > foo
p4 add foo
p4 submit -d "Add foo" foo

p4 integ foo bar
p4 submit -d "Branch foo" bar

p4 edit foo
echo Change B >> foo
p4 submit -d "Update foo" foo

p4 edit foo
echo Change C >> foo
p4 submit -d "Update foo again" foo

p4 integ foo#3,#3 bar
p4 resolve -o

Running the merge tool at this point will show you the results of the automatic merge, in which "Change C" is preserved and "Change B" is not:

This behavior is produced by the last integration command: p4 integ foo#3,#3 bar. By specifying only a single revision as the source revision range (#3,#3), only the "Change C" delta in foo#3 is applied to bar#2. Without specifying a single revision, the default behavior of the integrate command is to merge both "Change B" (foo#2) and "Change C" (foo#3).

The source revision that is not integrated (foo#2) remains a candidate for future integrations. If you do not need the unintegrated content delta from foo#2 in bar, then it is appropriate to do a so-called "bookkeeping" integration. A bookkeeping integration entails integrating changes that you do not want -- and then resolving them with p4 resolve and selecting "accept yours" to ignore the content of the source revision. For example:

p4 integ foo#2,#2 bar
p4 resolve -ay
p4 submit -d "Explicitly ignoring foo#2,#2" bar