Managing branch mapping

In Helix Core server, a codelineA set of files that evolve collectively. One codeline can be branched from another, allowing each set of files to evolve separately. is a set of related files — for example, all the source code required to build your software product. Copying an edit from one file set to the other is called merging or copying. Copying a set of files to create a new codeline (or equivalent) is called making a branch or branching. Branching is performed using the Merge/Integrate feature. You can perform simple branches using a file mappingA single line in a view, consisting of a left side and a right side that specify the correspondences between files in the depot and files in a client, label, or branch. See also workspace view, branch view, and label view..

To ensure that complex branching is done in a controlled manner (for example, to prevent typographical errors when entering target directories or to make sure that complicated branches are performed correctly), you can create a branch mappingSpecifies how a branch is to be created or integrated by defining the location, the files, and the exclusions of the original codeline and the target codeline. The branch mapping is used by the integration process to create and update branches., which specifies the relationship between two codelines. When you branch, you can use the branch mapping instead of a file mapping. Branch mappings are displayed in the right pane on the Branch Mapping tab.

Work with branch mapping

To create a branch mapping, choose File > New > Branch Mapping​ and enter the required information. To prevent the mapping from being changed by other users, check locked. To confine integration to closely related files, choose direct; to enable integration between distantly related files, choose indirect.

Use the View field to reflect the relationship between source and target codelines. For example, to create release 2 of Jam from the code in your main codeline, you might use the following view:

//depot/jam_proj/... //depot/jam_r2.0/...

To view a branch mapping, go to View > Branch Mappings. Use the Filter pane at the top of the Branch Mappings tab to search for mappings by owner and branch mapping name (or part of the name). Double-click a branch mapping to view it.

To change a branch mapping, double-click it in the Branch Mappings tab to open the Branch Mapping dialog. Click Edit to enter your changes.

To delete a branch mapping, click the mapping you want to delete, then select Edit > Delete Branch <branchname>.

To integrate using a branch mapping:

1. Right click the files you want to integrate and choose Merge/Integrate​.

   The Merge/Integrate dialog is displayed.

2. Select Use branch mapping as your Merge method.

3. Browse for the branch mapping you want to use. Select the branch mapping and click OK.

   The dialog refreshes to show a table with Source and Target columns and an arrow icon in between. By default, the arrow indicates the direction of the merge from source to target. You can use the option buttons labeled source and target at the bottom of the Filter tab to reverse the direction of the merge. If source is selected, files are merged from source to target. If target is selected, files are merged from target to source. Changing this selection also switches the direction of the arrow icon as well as the Source and Target columns.

   Important

   If you perform a merge/integrate operation from a file directory that is located at a higher level than what is specified in the branch mapping view, you see a bi-directional arrow icon instead of a directional arrow icon. This indicates that you are about to perform an advanced two-way integration: first from source to target and then from target to source. Clicking Merge brings up a warning that prompts you for confirmation. If you want to go back to a one-directional merge, remove the path you are filtering with from the Merge only the following files/folders field in the Filter tab. Removing the path turns the bi-directional arrow icon into a directional arrow icon. Alternatively, you can cancel the merge and select a lower-level folder for the integration.

4. To make changes to the mapping, click Edit View.

   The target must be a path that contains some or all of the paths identified in the branch mapping. In other words, the target can be a subset of the path specified by the branch mapping.

5. On the Advanced tab, specify other options as needed:

   • Do not copy newly branched target files to workspace (-v): Create a branch in the depot without retrieving the corresponding files from the depot to your workspace.
   • Schedule 'branch resolves' instead of branching new target files (-Rb): Schedules a branch resolve, instead of branching new target files automatically.
   • Schedule 'delete resolves' instead of deleting target files (-Rd): Schedules a delete resolve, instead of deleting target files automatically.
   Warning

   The following integration flags can have unexpected or undesired results. Do not select them if you are not certain you want these actions to be applied.

   • Try to integrate changes when source deleted and re-added (-Di): If the target file has been deleted and the source file has been changed, this option re-branches the source file on top of the target file. If the source file has been deleted and the target file has changed, this option deletes the target file. By default, outstanding edits cannot be integrated with a deleted file.
   • Force integration on all revisions, disregarding integration history (-f): Integrate all revisions of source and target files, including revisions that have already been integrated. Typically used with a specified revision range.
   • Do not get latest revision of selected files (-h): Use the workspace revision of the target file. By default, the head revision of the target file is automatically retrieved into the workspace before integrating.
   • Disregard indirect integration history (-1): Restrict selection of the base file revision to direct (parent-to-child or child-to-parent) integration history.
   • Propagate source filetypes to target files (-t): Assign the target file the same file type as the source file (when integrating to existing target files).
   • Skip previously merged 'cherry-picked' revisions to improve merge results (-Rs): Skips cherry-picked revisions that have already been integrated. This option can improve merge results, but can also require multiple resolves per file.
   • Check for opened files and warn prior to merging (might affect server performance): Checks for files currently open and displays a warning before the merge.
6. To preview the results of the operation, click Preview.
7. To integrate the files using the selected branch mapping, click Merge.