Branching and Merging Perforce IPLM Lines
The pi integration command can be used to merge the files and resources of a source Line into the files and resources of a target Line of the same IP.
Merging Lines
Lines are often used to maintain long-running variants of an IP. For example, an IP that has specific changes for specific target projects would have a Line for each project. Lines can also be used for independent development activities. User A might create a Line of an IP to fix a bug while User B might create another Line to add a feature. Once the task on a Line is finished (or has moved along to some logical point), users can reflect their changes back onto the main Line of the IP, or share their changes with other users on different Lines without impacting the ongoing work on the target.
Examples of Line merge scenarios:
- Merging between Lines of the same the IP is common, for example have a mainline TRUNK, and a development DEV Line, or per-task Lines.
- Merge lib.ip1@HEAD.experiment to lib.ip2@HEAD.TRUNK as perhaps the changes are no longer an experiment, or are different enough that it needs a new IP.
- Another example would be where projects are derivatives of each other via a copy, and you want to promote changes from one project to another.
Implementation Details
The command 'pi integrate' can be used to merge the changes on a source Line into a target Line. The following section shows a basic example of merging two Lines. The source Line is drinks.ip1@1.apple, and the target Line is drinks.ip1@1.TRUNK:
$ pi ip tree drinks.ip1@1.TRUNK drinks.ip1@1.TRUNK ├─ drinks.resource1@HEAD.TRUNK [@0] ├─ drinks.resource2@HEAD.TRUNK [@0] └─ drinks.resource3@HEAD.TRUNK [@0] $ pi ip tree drinks.ip1@1.apple drinks.ip1@1.apple ├─ drinks.resource1@HEAD.apple [@0] --> resource1 moved to line 'apple' ├─ drinks.resource2@HEAD.TRUNK [@0] └─ drinks.resource3@HEAD.TRUNK [@0] $ pi ip load drinks.ip1@1.TRUNK -r; cd to this directory $ pi ip integrate drinks.ip1@1.apple $ pi ws st Workspace ID : ae1a094a-c4ed-41a7-a7e4-79b2b61be13d Directory : /tmp/drinks.ip1 IP : drinks.ip1@1.TRUNK Merged in : drinks.ip@1.apple, ... Resources : ┌──────────────────┬──────────────────┬─────────────────┬───────────┬───────────────┬───────────┐ │ NAME │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │ MODE │ ╞══════════════════╪══════════════════╪═════════════════╪═══════════╪═══════════════╪═══════════╡ │ drinks.ip1 │ 0.TRUNK │ 0.TRUNK │ Modified │ OK │ Container │ │ drinks.resource1 │ HEAD.TRUNK [@0] │ HEAD.apple [@0] │ OK │ OK │ Container │ └──────────────────┴──────────────────┴─────────────────┴───────────┴───────────────┴───────────┘
Merge Action
The basic 'merge' action does the following:
- Compares the list of immediate resources of the source IPV (the IPV I want to merge in) and target IPV (the IPV in my workspace)
- If the two lists don't match (i.e. if one or more resources exist in one list but not in the other), then the merge operation is aborted
- For each resource in the target IPV
- If the resource is at its expected Line and version and not in "Modified" state, update to the source IPV's corresponding resource.
- If the resource is not at its expected Line and version or in "Modified" state, and the same resource on the source list is on a different Line or version, ignore the resource
- Indicate that these resources are in conflict with a message at the end.
Users can run multiple merges into the same workspace.
Tracking Merges
Once a merge is finished, the workspace maintains a record of the merge. The merge(s) are shown as part of the workspace status output as an INFO message (as shown in the code block above).
If a user runs a "pi release" command in this workspace, then the merge record is attached to the release and cleared from the workspace. This allows users to do multiple merges into a workspace, and then release the resulting workspace. PI will now have a record or all the Lines that were merged in to create a release. It is quite possible that users will make additional modifications to IPVs and files in their workspace after doing a merge before releasing. That is expected, and is not tracked by PI.
Pre and Post-merge hooks
There are two client-side merge hooks
- a pre-merge hook called "pre_integrate"
- and a post-merge hook called "post_integrate"
The pre-merge hook is run before any merge steps are taken, and the post-merge hook is run after all the merge steps described above for all the resources are completed.
One use for the pre-merge hook is to do some clean-up or other activity before a merge is attempted. A use for the post-merge hook is to run file merge actions - for example, "p4 integrate" from source repo paths to target repo paths - for all the local IPs, or a subset of IPs in the workspace as they choose. Note that it is possible that this may cause merge conflicts, but that is considered normal and users should resolve these conflicts outside the hook as normal.
The hooks will print their output to STDOUT.
The hooks can be configured per IP, or per Library. If configured at the Library level (and not at the IP level), the IPs in the Library will inherit the hooks. This is the same as current client side hook behavior.
Please see Workspace Automation for more details on how to configure these hooks.