The AccuRev Merge Tool

This topic describes AccuRev's own 3-way merge tool. You can also configure the GUI to use another text-file-merge tool.

Merge Tab Layout

By default, the Merge tool displays the two contributors' contents in side-by-side panes with the contents of the contributors' closest common ancestor in a third pane between them.

Note: Using a toolbar button, you can arrange the contributors' panes vertically, or toggle the visibility of the pane containing the closest common ancestor.

The file in your workspace is always on the right. Above them, the Merge tool displays the merged version. The contributor panes and closest common ancestor pane are synchronized: scrolling any one of them causes the others to scroll, too.

Special cases:

•	HTML files

•	Binary files

Color-Coding of the Contributor Versions

Like the Diff tool, the Merge tool partitions the contributor versions' contents, displaying unchanged sections with a white background and change sections with colored backgrounds. The color-coding scheme is a bit different, because the Merge tool has the more complex job of distinguishing conflicting changes from non-conflicting ones. In addition, the color-coding scheme depends on which navigation mode you're working in.

•	For changes that are traversed in the current navigation mode, the Diff tool's color-coding scheme is used.

•	Changes that navigating in the current mode skips over are colored gray.

•	For a conflicting change, the blocks in all contributors are colored yellow, no matter what the navigation mode is.

Example 1: In My changes navigation mode, non-conflicting additions that come from your version are colored green; non-conflicting additions that come from the other contributor are colored gray. In Their changes navigation mode, the color-coding of non-conflicting additions would be reversed.

Example 2: In Conflicts navigation mode, all conflicting changes are colored yellow; all other change sections are colored gray.

Color-Coding of the Merged Version

The merged version is displayed with color-coding, too. Each colored block is a location where a change has been incorporated from one of the contributors into the merged version. When it starts, the Merge tool performs as much merging as it can automatically, applying all of the non-conflicting changes to the merged version. The text is always colored gray. Annotations in the left margin indicate the origin of the change:

•	left-hand (or upper) contributor:   annotation

•	right-hand (or lower) contributor: annotation

The Merge tool cannot resolve conflicts automatically, so the location of each conflict is initially indicated in the merged version by a blank yellow block. As you make selections to resolve the conflicts, the blank yellow blocks get filled in with the selected text and are annotated:

•	blocks that you select from the left-hand (or upper) contributor: annotation

•	blocks that you select from the right-hand (or lower) contributor: annotation

•	blocks that you select from the closest common ancestor: annotation

In all cases, the text of a resolved conflict is colored blue.

Resolving Conflicts

You can think of the Merge tool as a special-purpose text editor: it combines the contents of two files, producing a third file as the result. Like any text editor, the Merge tool provides you with a set of editing and navigation functions; you have a lot of flexibility in choosing which functions to use, and in which order.

But the Merge tool does enforce this requirement: you must resolve all the conflicting changes between the contributor versions before you can complete a merge operation. Thus, Merge tool usage follows this basic pattern:

•	Navigate to the various conflict sections.

•	Resolve each conflict by selecting a section from the left-hand (or upper) contributor, the right-hand (or lower) contributor, or the closest common ancestor. You can also resolve the conflict by selecting the sections from more than one of these sources -- even from all three -- in any order.

•	(optional) Add manual edits to the merged version.

•	Save the results.

These operations (except for manual editing) are controlled by Merge toolbar buttons, as described in the following sections.

Navigating the Display and the Change Sections

Some of the Merge tool's navigation facilities are the same as the Diff tool's:

•	The panes have scroll bars, which are automatically synchronized with each other.

•	The navigation buttons in the middle of the Merge toolbar work the same way as in the Diff tool, with a slight variation:

•	If the Their changes mode button is selected, the navigation buttons traverse just the change sections in which the left-hand (or upper) contributor differs from the closest common ancestor.

•	If the All the changes mode button is selected, the navigation buttons traverse all the change sections.

•	If the My changes mode button is selected, the navigation buttons traverse just the change sections in which the right-hand (or lower) contributor differs from the closest common ancestor.

•	If the Conflicts mode button is selected, the navigation buttons traverse just the sections with conflicting changes.

At any given time, one of the change sections is currently selected. The line numbers in both contributor panes are highlighted to indicate the selection.

Whenever you use one of these buttons (except for Search) to jump to a particular change section, the Merge tool remembers it as the current change. Selecting a particular change section by left-clicking it in either contributor pane makes it the current change.

The Change Section Counter

As you navigate among the change sections, a counter in the Merge toolbar tracks your location, taking into account which navigation mode is selected.

For example, "2 of 4" might mean "you are currently in My changes mode, and you are currently at the 2nd of 4 such changes".

The counter typically changes as you switch navigation modes.

In some cases, the first number may be "0". This occurs when:

•	You've just switched modes, and the current change section is not selected by the new mode.

•	In Conflicts mode, you've just resolved a conflict, by selecting a section from one contributor. The current change section is no longer a conflict, so it's no longer selected by your current navigation mode.

Searching for Text

In addition to navigating among the change/conflict sections, you can search for any text string in any pane, using the Search toolbar button (keyboard shortcut: Ctrl-S).

You can also invoke this command from the context menu that appears when you right-click anywhere in either contributor pane.

Selecting a Section from a Contributor (or Multiple Contributors)

Sometimes, the Merge tool can construct a merged version without any help from you. This occurs if all the change sections are non-conflicting. The Merge tool just applies all the changes to the merged version and announces that it's done. This section describes the more interesting case: the contributors have one or more conflicts, which you must resolve.

The Merge tool automatically jumps to the first conflict. That is, it scrolls to the first yellow-highlighted change section in the contributors, and the corresponding blank yellow block in the merged version. It's up to you to decide which of the changes is to be incorporated into the merged version. You indicate your decision using the conflict-resolution toolbar buttons.

•	Click the Take common ancestor change toolbar button to incorporate the original block from the closest common ancestor.

•	Click the Take my change toolbar button to incorporate the changed block from the right-hand (or lower) contributor (file in your workspace).

•	You can take two of the blocks or all three of them, in any order:

1.	Click the or or conflict-resolution button to select one block.

2.

Hold down the Ctrl key, and click another conflict-resolution button. The newly selected block is sent to the merged version, below the previously selected block. The conflict-resolution buttons are annotated with numbers, indicating the order you selected. (And the tooltip reminds you of this "multiselect" capability.)

3.	Optionally, repeat the preceding step to include the third block, as well.

You can undo a multiselect by clicking any of the conflict-resolution buttons without holding down the Ctrl key. Typically, you'll need to do some manual editing to "smooth out" the combined changes of a multiselect.

Note: You cannot undo a multiselect once you've performed a manual edit.

The following two conflict-resolution buttons make large-scale changes -- use them carefully! They both effectively override the Merge tool's automatic inclusion of non-conflicting changes into the merged version.

•	The Revert all of my changes button makes the merged version the same as the left-hand (or upper) contributor version.

•	The Use only my changes button makes the merged version the same as the right-hand (or lower) contributor version.

When you click one or more conflict-resolution buttons to resolve a conflict, the selected block(s) appear in the merged version and the highlight changes from yellow (unresolved) to blue (resolved). This also decrements the change section counter in the Merge toolbar.

Use the Next navigation button to scroll down to the next conflict. (It may take more than one click if your are not in Conflicts navigation mode.) Again, use one of the "take change" buttons to select the text from the left contributor or the right contributor (or both of them).

You don't have to resolve the conflicts in order. You can jump around as much as you want among the change sections, or scroll through unchanged sections to look up information the affects your merge decisions.

Changing Your Mind

You can change your merge decisions as much as you want. For example, you can navigate to a particular change section where you had selected Take their change, and then click the Take my change button. This swaps out their change and swaps in your change.

Warning: swaps of this kind also discard any manual edits that you have made in that section after initially selecting it.

If you want to discard all your merge work, close the Merge tab to abandon the merge session entirely.

A confirmation dialog box appears, making it less likely that you'll discard your merge work accidentally.

Manual Editing

At any time during a Merge tool session, you can manually edit the contents of the merged version. Just click anywhere in the pane containing the merged version, and type. The Delete and Backspace keys work as expected. Using context (right-click) menus or the GUI main menu, you can Cut, Copy, and Paste sections of text that you've highlighted with the mouse. You can also use the common keyboard shortcuts: Ctrl-C or Ctrl-Ins to copy, Ctrl-V or Shift-Ins to paste.

Warning: If you make changes manually within a conflict section that you've resolved with one of the conflict-resolution buttons, the manual changes will be overwritten if you return to that section and click any conflict-resolution button.

Joining Change Sections

Sometimes, there is a block of lines in a contributor version that you consider to be a single change section, but that the Merge tool decides are two separate sections. You can combine the two change sections:

1.	Right-click in the contributor section, and choose Join Sections from the context menu.

2.	The mouse pointer changes to . Click the adjacent section to be joined with the first section.

The Merge tool joins the sections, then readjusts its analysis of the contributors' change sections. Typically, this changes the number of conflict sections.

Saving the Merged Version

When you resolve the last remaining conflict by clicking one of the conflict-resolution buttons, the Conflicts counter goes to "0 of 0" and the Merge tool displays this message window:

•

Clicking Keep & Exit ends the merge session immediately, closing the Merge tab. AccuRev overwrites the file in your workspace with the merged version. Then, it a Keeps a new version in your workspace stream, to preserve the merge results. The overlap status of the file is removed, so that you can now Promote the new version to the backing stream.

•	Clicking Review continues the merge session. This enables you to review your work, change some of your merge decisions, and perform manual edits. At any time, you can click the Keep button in the Merge toolbar to complete the merge process.

You can also cancel the entire merge during a review pass by closing the Merge tab without performing a Keep.

Notes About Merge Behavior

As of AccuRev Release 4.9, the merge command is now smarter about simple (rebase) merges, resulting in simplified display of merge lines in the Version Browser, and simplified change packages. For example, assume two developers are working in parallel on the same element, with a common ancestor, and there are only regular versions (that is, no patches, merges, or reversions) between the current versions and the common ancestor. When these are merged, the resulting version of the merge is rebased to point to the merged version.

In these cases you will not see a red merge line in the Version Browser. Instead, the comment section of the merged file will contain an entry similar to: “merged, rebased to <version>”. In other words, if a merge results in a change that you would have received if you had simply done an update, it is not displayed as a merge. See the screenshots under Notes:.

Commands Available in a Merge Tab

Navigation Mode Radio Buttons

Their changes

When this radio button is selected, the navigation buttons take you to the change sections in which the left-hand (or upper) contributor differs from the closest common ancestor.

All the changes

When this radio button is selected, the navigation buttons take you to all the change sections.

My changes

When this radio button is selected, the navigation buttons take you to the change sections in which the right-hand (or lower) contributor differs from the closest common ancestor.

Conflicts

When this radio button is selected, the navigation buttons take you to all the sections that contain conflicting changes.

Navigation Buttons

First change/conflict

Go to, and select, the first change section (or unresolved conflict section)

Last change/conflict

Go to, and select, the last change section (or unresolved conflict section)

Center current change/conflict

Scroll the contributor panes (if necessary), to make the currently selected change section visible.

Previous change/conflict

Go to, and select, the preceding change section (or unresolved conflict section)

Next change/conflict

Go to, and select, the next change section (or unresolved conflict section)

Change section counter

Display only, not a button. See The Change Section Counter.

Search

Bring up a dialog to define a search in one of the panes for a specified text string.

Conflict Resolution Buttons

Invoking a "Take ... change" operation replaces a previously chosen change section at that location. It also wipes out any manual edits you may have performed in that change section.

Take their change

Copy the currently selected change section in the left (or upper) contributor pane to the results pane.

Take common ancestor

Copy the original block from the closest common ancestor to the results pane.

Take my change

Copy the currently selected change section in the right (or lower) contributor pane to the results pane.

Revert all my changes

Make the merged version the same as the left-hand (or upper) contributor version.

Use only my changes

Make the merged version the same as the right-hand (or lower) contributor version.

The "Keep merge results" Button

Keep results and close

Preserve the current contents of the merge results pane as a new version of the element, using the Keep command. (The Keep dialog box does not appear.) The Merge tab for this file then closes automatically.

Character Encoding Fields

The Merge view has two fields related to character encoding, Character Encoding and BOM:

•	Character Encoding: A drop-down list that lets you specify the character encoding of the file being merged. This field has two effects:

•	It renders the file using the encoding specified. For example, a file whose encoding is set to UTF-8 is rendered like this when the Character Encoding is set to System Default:

And it is rendered like this when the Character Encoding is set to Unicode (UTF-8):

•	It sets the encoding of the merged output. So, for example, if the Character Encoding is set to Unicode (UTF-8), the file is saved with UTF-8 encoding when the merge is complete.

•	BOM: A BOM (Byte Order Mark) is part of the Unicode standard used to indicate the endianness of a text file, and which Unicode encoding is in use (UTF-8, UTF-16, or UTF-32. for example). The BOM drop-down is displayed only when you are merging Unicode files, as shown here:

This can happen because the native encoding is Unicode, or if you use the Character Encoding field to explicitly set a Unicode encoding.

When the BOM field is set to Yes, the output file of the merge will be written with a leading BOM indicator from the Unicode standard. When the BOM field is set to No, the output file will be written without the leading BOM. If either contributor to the merge has a BOM in it, the BOM field defaults to Yes; otherwise it defaults to No.

In most cases, you should not write the Byte Order Mark to the output, unless you have a specific need for it (because the file is used externally by a tool that requires the BOM).

Pane Selection Buttons

Show results of edits

Toggle the visibility of the merged version pane. This enables you to see more data in the two contributor panes.

Show HTML result

(Appears for file with .htm or .html suffix only) Toggle switch: display the context of the merged version as plain text, or render the contents as HTML.

Show Ancestor Panel

Toggle switch: display/hide the closest common ancestor pane.

Horizontal Layout

(default) Places the "other" contributor pane to the left of the "workspace" contributor pane.

Vertical Layout

Places the "other" contributor pane above the "workspace" contributor pane.