» Support » Knowledge Base »  User Tasks » Codelines and Branching » Branching Codelines...

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 using the Perforce Command-Line Client (P4). For a demonstration of branching and merging using the Perforce Visual Client (P4V), please see our video tutorial.

Branching a new codeline

Suppose your main development codeline is stored in Perforce under //depot/main. You want to create a branch for your first release, rel1. You need to branch the main codeline into a rel1 codeline stored in //depot/rel1. This release codeline starts with exactly the same files as the mainline, but it will change as you stabilize the code for that release and future development continues in the mainline -- 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 rel1 into main, so the fixes you make in rel1 carry forward to future releases.

Perform the following steps to branch a new codeline:

1. Ensure that you are able to submit files to the new codeline
   
   Make sure you have a "mapping" for the new //depot/rel1 files in your client view. You do not necessarily need a mapping for the files you are branching from, but you do need a mapping for the files you are branching to, exactly as if you were adding new files to the depot. Your client spec should include a view mapping similar to the following:

   //depot/rel1/... //bruno_ws/rel1/...
   

   For example, a client spec that maps both codelines might look like:
   

   Client: bruno_ws
   Root:   c:\workspace
   View:
   
      //depot/main/... //bruno_ws/main/...
      //depot/rel1/... //bruno_ws/rel1/...
   

   Note that the default client view maps the entire depot, so if you have not modified your client view from that default, it is not necessary to add an additional line. In this case the workspace will look more like:
   

   Client: bruno_ws
   Root:   c:\workspace
   View:
   
      //depot/... //bruno_ws/...
   

   In either case, //depot/rel1 maps to c:\workspace\rel1.
   
   For more information on creating and updating client workspaces, refer to the P4 User's Guide.
   
   NOTE: You can only branch or add files into depot directories where you have write permissions or greater. If you need to branch files to directories where you do not currently have at least write access, update the protections table. For more information on adjusting protections, consult with your Perforce administrator, or see the Perforce System Administrator's Guide chapter on Protections.

2. Create a branch specification
   
   Create a branch spec to define the relationship between the mainline and the release branch. Branch specs are optional, but useful because they act as "shortcuts" for frequently used integration mappings. The branch spec for this example is called "rel1" and is created with the following command:

   p4 branch rel1
   

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

   Branch: rel1
   View:
      //depot/main/... //depot/rel1/...
   

   Once this branch spec has been created, it can be used as a pre-formed mapping for any p4 integrate command between these two codelines.

3. Integrate using the branch specification
   

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

   p4 integrate -b rel1

   p4 integrate copies all the files from //depot/main into your client workspace and opens them for branch into //depot/rel1. When you submit the opened files, the release branch files are created in the depot, and Perforce records the fact that the files in //depot/rel1 came from files at the now-current revisions in //depot/main. The output from p4 integrate looks like:

   //depot/rel1/a.c#1 - branch/sync from //depot/main/a.c#1
   //depot/rel1/b.c#1 - branch/sync from //depot/main/b.c#1

   If you skipped step 2 and did not create a branch spec, the equivalent command would be:
   

   p4 integrate //depot/main/... //depot/rel1/...
   

   The output and final result is the same in either case.

4. Submit your branch
   

   p4 submit
   

   This brings up a submit form in your text editor, exactly as when submitting any other change to the depot. Fill out the description, save the file, and exit the editor.
   
   The new //depot/rel1 codeline has now been submitted to the depot, synced to your workspace, and is ready to use.
   

At this point you can work with the rel1 directory exactly as you would work with any other; you can add new files to it, edit the existing files, delete some of them, and so on. Other users can also sync this directory and work with it, subject to the usual conditions of having appropriate permissions and client view mappings.

Merging changes between codelines

Perform the following steps to merge changes from the rel1 codeline into the main codeline:

1. Integrate using the branch specification
   
   If you created a branch spec earlier, you can re-use it for merges rather than specifying the paths to each codeline every time you merge. Since the branch spec in this example maps from main to rel1, integrating in the other direction requires using the -r flag:

   p4 integrate -b -r rel1
   

   In this example, suppose that the file a.c has been changed in both codelines. The integrate output looks like:

   //depot/main/a.c#2 - integrate from //depot/rel1/a.c#2

2. Resolve the differences between the two codelines
   
   Runing the p4 resolve command 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. If there are no conflicts, resolve suggests accepting either "your" file (in this case the mainline file that you are updating), "their" file (in this case the release branch file), or an automatically generated merge of the two. If there are conflicts, the action p4 resolve suggests is to edit:

   c:\workspace\main\a.c - merging //depot/rel1/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 edited file ("ae"):

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

   When you press ENTER, your edited, merged file is saved in your workspace. At this point you can diff the edited file against the head revision in the depot with p4 diff to see what changes you have made, and you can run tests on your merge results if appropriate.

3. Submit the merged file

   p4 submit
   

   This submit not only updates the mainline file in the depot, but records the fact that all changes in the release branch have now been integrated into the mainline.

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.