The Merge Branches command allows you to merge changes from any folder in Vault Professional to any another folder within the same repository. Usually, these are folders that have been branched from each other and modifications have been continuing in one or both of them. At some point, you may want to resolve all differences between the branches, or move all the changes from one folder to another.
The folder from which changes are to be migrated is called the origin folder, and the folder which changes are to be applied to is called the target folder. The Merge Branches Wizard will merge file modifications, file and folder adds, renames, moves, and shares.
You can choose to create a Merge Marker upon completion of the Merge Branches Wizard. The next time the Merge Branches Wizard is run, you can see what changesets have already been merged.
Vault does not look at the contents of folders in a folder merge; it looks at transaction history. The Merge Branches merges changesets or transactions. When you merge branches, you select a range of changesets to merge into the target folder.
To begin the merge, go to the Tools menu and click Merge Branches. A wizard will come up to lead you through the steps. The screens in the Merge Branches wizard are:
The Welcome Screen of the wizard explains the steps in the Merge Branches process. There are two check-boxes at the lower left of the Welcome Screen.
If you click the Auto Advance No-Op Steps checkbox, the wizard will automatically skip steps where no action is required. For example, if you did not rename any files or folders, the wizard will skip the step for renames.
If you want to skip the Welcome Screen the next time you start the Merge Branches Wizard, click the checkbox for Skip this step except when shift key is down. This setting will take effect after a completed merge. The Welcome screen can be re-enabled by holding down the SHIFT key while launching the Merge Branches Wizard.
Select the origin folder, the folder which contains changes to be merged into a target folder. If you hold down CTRL and double-click the folder, the Wizard will advance to the next step.
Select the target folder, which will be modified by changes from the Origin Folder. If you hold down CTRL and double-click the folder, the Wizard will advance to the next step
This screen presents a list of all revisions of the Origin Folder. You can filter the list by choosing one of the Version Retrieval Options. Double-click a row to see the details of what was changed in that transaction. Select the changesets you would like to apply to the target folder. Select one or more changesets in the list, and the differences in those versions in the origin folder will be applied to the target folder. Note that non-contiguous changes are allowed only if the paths are not part of any omitted changeset. For example, if you added a file in Changeset 5 and modified it in Changeset 6, you cannot merge the modification without the creation of the file, so you must choose to merge both changesets 5 and 6.
Select the versions by using CTRL and the left mouse button to select versions to be merged.
The earliest version you choose essentially becomes the baseline version between the origin and target folders. If the target file is different from the baseline version you’ve chosen, then a file merge takes place between the source and target files to resolve the differences, so that both sets of differences will be reflected in the merged target version.
Version Retrieval Options
Since your last merge marker -- Retrieve history since the last merge marker (if any) for the currently logged on Vault user.
Include past X day(s) -- Retrieve history for the specified number of days.
All Historical Versions -- Retrieve all history of the Origin Folder.
Retrieve Versions -- Click the Retrieve Versions button to list the versions specified in the Version Retrieval Options. The Retrieve Versions Command can also be used to refresh the change set list.
Retrieve Labels for History Items -- If checked, the history query will retrieve folder label names for the returned version history. The Labels column will display the 20 most recent labels found for that particular folder version. Labels which were directly applied or inherited will be listed, but not recursive labels. No label data will be retrieved if the box is unchecked.
Merge Markers
Show Merge Markers for all users -- A merge marker is a visual cue of what versions were previously merged. Merge Markers "bookend" the range of history versions in that Merge Branches operation. The Merge Marker is a begin and end pair, similar to a bracket. Merge Markers are named to to indicate the user who created the Merge Marker and the date.
By default, Merge Markers for the logged in user will be shown. To show merge markers from all users, click the Show Merge Markers for all users checkbox.
Create a New Merge Marker upon Finish. -- You can choose to create a Merge Marker upon finish of the Merge Branches Wizard. The next time the Merge Branches Wizard is run, you can see what changesets have already been merged. A Merge Marker is tied uniquely to both the source and destination folders' object IDs, and also contains information such as a self-generated name, user who created the marker, date it was created as well as an array of the changeset transactions participating in the merged branch.
This step will retrieve the historical data for selected changeset data from the server, and analyze the results.
Click step by step through the wizard, which will show items to be merged.
Items which cannot proceed are shown with a red background. For example, if a file was modified in the branch but has been deleted in the trunk, the merge could not proceed. Double-click on an item with a red background for more information.
Items which appear to have no issues are shown with a white background and they are checked by default.
Items which can proceed but may be undesirable are shown with a yellow background.
Items which do not need to proceed are shown red. When you click on an item, the line becomes blue and suggests an alternative. These are cases where the trunk is in exactly the state it would be in if the merge were to occur anyway. For example, if a file has been renamed in the branch and has been renamed the same way in the trunk, then nothing needs to be done.
The Moves and Shares page lists all the move and share operations to be performed as part of the merge. Only moves and shares taking place wholly within the Origin folder and its subfolders will be listed here. Moves and Shares from outside the Origin Folder will be treated as Adds.
Choose the items that are to be included in the merge by selecting the checkbox next to each item. Note: If Auto-commit is enabled in the Vault Professional, the move operations will be performed and committed to the repository immediately, as the wizard proceeds.
The Rename page lists all the rename operations in the same manner as the Move/Share list. Choose the items that are to be included in the merge by selecting the checkbox next to each item. The rename operations will be performed and committed to the repository immediately, as the wizard proceeds.
If a file was renamed in the branch and has also been renamed in the trunk (to something else), then this operation will not be checked and will have a red background. Double-Click on the item to bring up the Choose Alternate File dialog. This will allow you to locate the file which was renamed in the trunk and apply the rename from the branch to the trunk.
The Wizard checks for edited files in the working folder of the Target Folder so that these are not overwritten during the merge. If edited files exist, a warning message is displayed.
In order to do the merge branches operation, files are retrieved from the server, so Vault Professional can compute the differences between the versions. The Retrieve Files from Server page shows you the status of the file downloads as they are being downloaded from the server.
The Adds, Deletes, Edits page lists all adds, deletes and edits in the same manner as the Move list. Choose the items that are to be included in the merge by selecting the checkbox next to each item. These operations will be added to the Pending Change Set for your review and can be committed once you’ve reviewed the changes. Any files in a Needs Merge status after the Merge Branches will need to have their conflicts resolved before the changes can be committed. Items shown in red indicated errors. Double-click those items for more information.
This screen allows you to enter the following settings:
Attempt Automatic Merge on Individual Files. If checked, Merge Branches will attempt to automatically resolve conflicts in files that have been changed in both the origin and the target folders. If unchecked, any file that needs merged will be added to the Pending Change Set with “Needs Merge” status, and you will need to manually resolve each merge.
Review the changeset comments generated by Merge Branches. By default, the Merge Branches Wizard creates a comment that begins with "Merge Branches: Origin=" and the path of the Origin folder, plus the list of versions which will be merged. The Vault Admin can create comment templates in the Vault Admin Web Client under Server Settings -> Merge Branches Comments. You can modify the comments created by the template or add to the content of the changeset comments for the changes that result from the Merge Branches operation.
The Modify Files page shows you the progress of the merge and when it is completed.
The Summary page will show you all the operations that were performed and the ones which remain pending. The merge operation is not complete until these changes are committed to the repository.
Close the dialog to finish the Merge Branches Wizard. Finally, complete the merge by committing the changes from the Vault Professional GUI Client Pending Change Set.
The Merge Branches Wizard supports the following operations:
File modifications
File and folder Renames, Moves, Adds and Deletions
File and folder Shares. Shares created within the origin are created in the target folder, but are not shared between the origin and the target.
Shares going into or out of the origin from folders outside the origin folder are not shared in the target. Files and folders in the origin that are shared outside the origin will be ignored in the target, but a warning message will be put in the summary page indicating this. Files and folders shared into the origin will be treated as adds.
File and folder Share Branch
File and folder Copy Branch and Folder Snapshot. These are treated as adds in the target, and not as branches or Snapshots.
The following operations are completely ignored when merging a folder. The changes in the origin will not be applied in the target, and they will not show up in the wizard list:
Cloak
File Property Change
Pin Status
File and Folder Label
Folder security changes
File/folder undelete. Since branches don’t create deleted items in the branch, you can’t undelete a file or folder in the branch that existed in the trunk. You can delete and then undelete a file in the branch, but this won’t have any effect in the trunk unless the file was modified in some other way.
The Move and Rename operations are automatically committed to the repository as the wizard progresses. The other changes are not committed but are put in the Pending Change Set for your review.
Merge operations cannot be done on binary files. However, a binary file can have a status of Needs Merged if it was modified locally and then checked out after another user checked in a change to the file. You can overwrite the version in the repository and change the status to Edited by selecting Merge. A warning dialog will appear.
Click Yes and the status of the file becomes Edited and the working file is not touched.
Click on No to cancel the operation. The file will retain the Needs Merged status.