Branching Codelines and Merging Changes

TASK

How do I branch a codeline?
How do I merge changes between two codelines?

SOLUTION

Briefly, you need to use the p4 integrate command, specifying source and destination directories. Below is a step by step example.

Suppose your Project 1 codeline is stored in Perforce under //depot/project1. You want to embark on Project 2, which will be an offshoot of Project 1. You need to branch the Project 1 codeline into a Project 2 codeline stored in //depot/project2. This Project 2 codeline starts with exactly the same files as Project 1, but it will change -- different changes to the same files, different files being added or deleted and so on. And as you work, you want to merge changes from Project 2 into Project 1, and from Project 1 into Project 2. Perform the following steps to create a new codeline branch and merge any changes between the two codelines:

1. Create a client mapping
   
   Make sure you have a "mapping" for the new //depot/project2 files in your client view. You do not need a mapping for the files you are branching from, but you do need a mapping for the files you are branching to. Your client spec should include a view similar to the following:

   Client: lion
   Root:   c:\workspace
   View:
      //depot/project2/... //lion/project2/..

2. Create a branch specification
   
   Create a branch spec to define the relationship between Project 1 and Project 2. Branch specs are optional. They are not really needed in such simple cases, but one is used here for demonstration. Your branch spec is called "p1p2" and you create it with the following command:

   p4 branch p1p2
   

   The p4 branch command brings up a form to edit, similar to the p4 client command. In your text editor, you will make the "View" section show that the //depot/project1 files will be mapped to //depot/project2 files whenever this branch spec is used:

   Branch: p1p2
   View:
      //depot/project1/... //depot/project2/...
   

   To branch a new codeline, there are two steps: p4 integrate and p4 submit. You create the Project 2 codeline using this method if you want to preserve its relationship with the Project 1 codeline for future merges. (Note that branching is not the same thing as creating a directory for Project 2, copying the files from Project 1 into it, then adding the Project 2 files as new depot files. You could do this, but Perforce would have no integration history at hand to help you merge changes back and forth between the projects.)

3. Integrate using the branch specification
   

   Use the branch spec to tell the p4 integrate command what to do. For example:

   p4 integrate -b p1p2
   

   p4 integrate copies all the files from //depot/project1 into your client workspace and opens them for branching into //depot/project2. When you submit the opened files, the Project 2 files will be created in the depot, and Perforce will record the fact that the files in //depot/project2 came from files at specific revisions in //depot/project1. The output from p4 integrate looks like:

   //depot/project2/a.c#1 
        - branch from //depot/project1/a.c#1
   //depot/project2/b.c#1 
        - branch from //depot/project1/b.c#1
   

   NOTE: You can only branch files into depot directories where you have write permissions or greater. If you need to branch files to directories where you do not have at least write access, the protections table will need to be adjusted. For more information on adjusting protections, consult with your Perforce administrator, or see the Perforce System Administrator's Guide chapter on Protections.

4. Submit your integration
   

   p4 submit
   

   This brings up a submit form in your text editor. Fill out the description and save the file.

5. Make changes in codelines
   

   When your new branch has been created, you want to make changes to files in Project 2. To do this, you must have the //depot/project2 path in your client view. To work on Project 2 files, go to your client workspace directory that is mapped to the Project 2 files:

   cd c:\workspace\project2
   

   For this example, assume these are your changes:

   p4 edit a.c
       a.c was blank, add a new line "abc"
   p4 delete b.c
   p4 add c1.c
   

   When your changes are complete, you can submit your changelist:

   p4 submit
   

   If you want to make a change to a file in Project 1, you need to have the //depot/project1 files in your client workspace view. You need to use p4 client to edit your client spec and add a line like the following to the "View" field:

   //depot/project1/... //lion/project1/...
   

   For example, if you edit //depot/project1/a.c. (This way there will be a change that conflicts with the change you just made in Project 2.)

   cd c:\workspace\project1
   p4 edit a.c
        a.c was blank, add a new line "def"
   p4 submit

6. Merge changes from the Project 1 codeline to Project 2 codeline
   
   You attempt an integration. You know a.c has changed in both Project 1 and Project 2. You want to integrate Project 1's changes to Project 2. You do this in 3 steps: p4 integrate, p4 resolve, and p4 submit. The integrate step finds the files in Project 1 that have changed since the last integrate, and opens up their Project 2 counterparts:

   p4 integrate -b p1p2
   

   In this case, there is only one file that qualifies. The output you see is:

   //depot/project2/a.c#1 
        - integrate from //depot/project1/a.c#2
   

   Run the p4 resolve command, which tells Perforce how you want to merge changes from one file to another:

   p4 resolve
   

   The p4 resolve command gives you a prompt for each file that needs resolving, and a suggested action. Since there is going to be a conflict when you merge the changes to a.c, the action p4 resolve suggests is to edit:

   c:\workspace\project2\a.c - merging //depot/project1/a.c#2
   Diff chunks: 0 yours + 0 theirs + 0 both + 1 conflicting
   Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [e]: 
   

   When you press ENTER, you will find yourself editing the a.c file. Your job is to look for "conflict markers" and edit them and the adjacent text so that the resulting file is valid. The conflict markers are shown here in red:

   >>>> ORIGINAL VERSION
   ==== THEIR VERSION
   def  
   ==== YOUR VERSION 
   abc 
   <<<<
   

   When you are finished editing, p4 resolve gives you another suggestion, which is to accept the merged file ("am"):

   Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [am]: 
   

   You press ENTER and your edited, merged file is saved in your workspace.

   Submit the merged file:

   p4 submit
   

   This submit not only updates the Project 2 file in the depot, but records the fact that all changes in Project 1 have now been integrated into Project 2.

7. Merge changes from second codeline to first codeline
   

   But what about the reverse? There are changes that were made in Project 2 that have not yet been integrated back into Project 1. Integrating in the reverse direction is much the same, with one exception -- you use the "-r" flag on p4 integrate:

   p4 integrate -r -b p1p2
   

   The p4 integrate -r causes Perforce to check all the files in Project 2, and look for changes that have not yet been integrated to Project 1. If any file changes are found, the corresponding Project 1 file for the same change is opened. So, in this case, the file that was deleted in Project 2 is now opened for delete in Project 1, the file that was added in Project 2 is now opened for branch/add in Project 1, and the file that was edited in Project 2 is now opened for integrate in Project 1. The deleted and added files do not need resolving, but the edited file does, so you perform the following:

   p4 resolve
   

   and edit the merged file as described above. When the resolve is done, all that remains to do is:

   p4 submit
   

   At this point, the Project 1 and Project 2 codelines are completely integrated. If you try to run another p4 integrate command in either direction Perforce tells you "no file to integrate."

In summary, branching a codeline in Perforce is simple. You use the p4 branch command to create a reusable branch mapping, then populate your new codeline using p4 integrate and p4 submit. Merging changes between codelines is done using p4 integrate, p4 resolve, and p4 submit. Again, note that the target or destination directory of your integration must first be mapped in your client workspace View and you must have Perforce write access to that target file or directory.

For information on more complex integrations, see the Perforce User's Guide chapter on Codelines and Branching.