Color-Coding of the Contributor Versions
Color-Coding of the Merged Version
Navigating the Display and the Change Sections
Selecting a Section from One Contributor (or Both)
Commands Available in a Merge Tab
This topic describes AccuRev's own 3-way merge The kind of algorithm that AccuRev uses to combine the contents of two versions (contributors) of a text-file element: it compares the two files line-by-line with a third version, the closest common ancestor of the contributors. tool. You can also configure the GUI to use another text-file-merge tool.
The Merge tool displays the two contributors' contents in side-by-side panes [note ], with the contents of the contributors' closest common ancestor (of two versions of an element) The most recent version that is an ancestor of two specified versions. Used in a merge operation to minimize the amount of work required to combine the contents of the two specified versions. See merge, version graph. in a third pane between them [note ]. 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:
Like the Diff tool, the Merge tool partitions the contributor Either of two versions of a file element, whose contents are to be combined in a merge operation. versions' contents, displaying unchanged sections with a white background and change sections In a text-file merge operation, a location where the two contributors being merged differ from each other. The Merge tool highlights and counts the change sections. It also tracks the conflicting changes (conflicts) — the subset of change sections in which both contributors differ from the closest common ancestor. Conflicts must be resolved by human intervention. See difference section. with colored backgrounds. The color-coding scheme is a bit different, because the Merge tool has the more complex job of distinguishing conflicting changes The situation in which both contributors to a merge operation differ from the closest common ancestor at the same text line (or set of lines). 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.
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.
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 these sections below:
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 (of two versions of an element) The most recent version that is an ancestor of two specified versions. Used in a merge operation to minimize the amount of work required to combine the contents of the two specified versions. See merge, version graph..
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 (of two versions of an element) The most recent version that is an ancestor of two specified versions. Used in a merge operation to minimize the amount of work required to combine the contents of the two specified versions. See merge, version graph..
If the Conflicts mode button is selected, the navigation buttons traverse just the sections with conflicting changes The situation in which both contributors to a merge operation differ from the closest common ancestor at the same text line (or set of lines). Also, the situation in which both contributors have pathnames that differ from the closest common ancestor, and from each other..
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 See current difference.. Selecting a particular change section by left-clicking it in either contributor pane makes it the current change.
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.
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.
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 their change toolbar button to incorporate the changed block from the left-hand (or upper)contributor.
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:
Click the
or
or
conflict-resolution button to select one block.
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.)
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 ]
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.
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.
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.
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:
Right-click in the contributor section, and choose Join Sections from the context menu.
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.
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 Version X, in a workspace or stream, has '(overlap)' status if the parent stream's current version of the element contains changes that are not reflected in version X. (That is, the parent stream's version is not an ancestor of version X.) Such a version cannot be promoted to the parent stream; the user must create a new version with a merge operation, combining version X with the parent stream's version. The new, merged version can then be promoted. Similarly, an overlap can exist between the versions in two dynamic streams. See deep 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.
Their changes
When this radio button is selected, the navigation buttons take you to the change sections In a text-file merge (or patch) operation, a location where the two contributors being merged differ from each other. The Merge tool highlights and counts the change sections. It also tracks the conflicting changes (conflicts) — the subset of change sections in which both contributors differ from the closest common ancestor. Conflicts must be resolved by human intervention. See difference section. in which the left-hand (or upper) contributor differs from the closest common ancestor (of two versions of an element) The most recent version that is an ancestor of two specified versions. Used in a merge operation to minimize the amount of work required to combine the contents of the two specified versions. See merge, version graph..
All the changes
When this radio button is selected, the navigation buttons take you to all the change sections In a text-file merge (or patch) operation, a location where the two contributors being merged differ from each other. The Merge tool highlights and counts the change sections. It also tracks the conflicting changes (conflicts) — the subset of change sections in which both contributors differ from the closest common ancestor. Conflicts must be resolved by human intervention. See difference section..
My changes
When this radio button is selected, the navigation buttons take you to the change sections In a text-file merge (or patch) operation, a location where the two contributors being merged differ from each other. The Merge tool highlights and counts the change sections. It also tracks the conflicting changes (conflicts) — the subset of change sections in which both contributors differ from the closest common ancestor. Conflicts must be resolved by human intervention. See difference section. in which the right-hand (or lower) contributor differs from the closest common ancestor (of two versions of an element) The most recent version that is an ancestor of two specified versions. Used in a merge operation to minimize the amount of work required to combine the contents of the two specified versions. See merge, version graph..
Conflicts
When this radio button is selected, the navigation buttons take you to all the sections that contain conflicting changes The situation in which both contributors to a merge operation differ from the closest common ancestor at the same text line (or set of lines). Also, the situation in which both contributors have pathnames that differ from the closest common ancestor, and from each other..
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. Click here for a description.
Search
Bring up a dialog to define a search in one of the panes for a specified text string.
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 contributor pane to the results pane.
Take my change
Copy the currently selected change section in the right contributor pane to the results pane.
Take their change then my change
Copy the currently selected change sections in both the left and right contributor panes, in that order, to the results pane.
Take my change then their change
Copy the currently selected change sections in both the right and left contributor panes, in that order, 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.
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.
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.
Toggle switch: display/hide the closest common ancestor pane.
(default) Places the "other" contributor pane to the left of the "workspace" contributor pane.
Places the "other" contributor pane above the "workspace" contributor pane.