The Merge operation combines two versions of an element, producing a new version. (That is, a successful merge operation always ends with a Keep. This is a software configuration management best practice.) AccuRev can process both content changes and namespace changes in performing a merge. By default, the merging of text-file contents is performed by AccuRev's own Merge tool, which uses a 3-way merge algorithm (see Versions in a 3-Way Merge).
What about elements that aren't text files?
The Merge command can also handle any other kind of version-controlled element: binary file, directory, or link.
Configuring the GUI to use another text-file-merge tool
A user preference enables you to configure a third-party tool for merging the contents of text files.
Why Do I Need to Merge?
Perhaps the most common usage pattern in AccuRev is:
Using Keep to create one or more versions of a text file in your workspace.
Using Promote to propagate the most recently kept version to the backing stream.
Occasionally, someone else "gets there first". That is, both you and a colleague are working on the same file concurrently, each of you using a copy of the file in your own workspace. And the colleague promotes his changes to the common backing stream before you do.
Before you can promote your own changes to the backing stream, you must first merge (that is, combine) the changes from your colleague's version with your changes. Merging ensures that no one's work is inadvertently lost or overwritten in a concurrent development environment. Files that require a merge prior to promotion have a status of (overlap) — that is, the work of one or more of your colleagues has overlapped your own work.
The File Browser makes it easy to tell which files require a merge prior to promotion: files with an (overlap) status, as well as other files that require special attention before they can be promoted, are displayed in the File Browser’s Conflicts mode (). In addition, files with (overlap) status are highlighted in yellow in all File Browser modes.
Although the above scenario is by far the most common one, AccuRev's flexibility allows for other merge scenarios, too:
- You can modify the file in your workspace by "pulling in" the changes from any version of the file, not just the backing stream's version.
- You can merge the versions of the file located in any two dynamic streams or snapshots. This involves using the Change Palette.
In all cases, however, you use the Merge tool in the same way, to combine the contents of two versions of the same file element.
No matter which tool you've configured to merge versions, you invoke the Merge operation in the same way: select one or more files with (overlap) status, then click the Merge toolbar button. Alternatively, choose Merge or Merge From on the selection's context menu. For example:
You can merge versions in the following contexts:
- In the File Browser (when invoked from a workspace), to merge from the version in the parent stream.
- In the Version Browser (when invoked from a workspace), to merge from an arbitrary version.
- In the History Browser (when invoked from a workspace), to merge from the version in a particular transaction.
- In the Change Palette, to merge versions in higher-level streams. (You must choose a workspace to use for the merge process.)
AccuRev processes the files you specify one-by-one. For each file, it does one or both of the following
- Prompts you to resolve namespace-level conflicts between the file in your workspace and the other specified version. This involves making choices in one or more dialogs.
- Invokes AccuRev's Merge tool or the other tool you've configured, in order to merge the contents of the two versions. AccuRev's Merge tool opens in a separate tab within the AccuRev GUI window; any other tool opens in its own window.
Invoking the Merge command on multiple files
If you select multiple files, you can choose to have the Merge tool process as many of them automatically as possible.
An automatic merge is possible if there are no conflicting changes between the two versions being merged. For files in which there are conflicting changes, the Merge tool always opens an interactive Merge tab.
File vs. Version
In all cases, one of the contributors to a merge operation is the file in your workspace. If you've just saved the file with the Keep command, the file in your workspace is identical to the most recent version in your workspace stream. But if you invoke Merge on a file that you've edited but not yet saved with Keep, AccuRev uses the file, not the latest workspace-stream version. Keeping before Merging is an AccuRev best practice.