Merging files

If development is being done in parallel, it is sometimes the case that two files must be merged into a single file. An example of this is Mike has a file checked out implementing a new feature, a bug is identified in the same file and needs to be resolved quickly. Al branches the source file to fix the bug while the Mike continues his implementation. When Mike's new feature has been completed, the bug fix needs to be rolled back in and the branch terminated (assuming Al finished his bug fix before Mike finished his implementation :).

Merge compares¹ three files (the two input files and the common ancestor), and displays the comparison in a series of panes: one for each difference and common section. Each section, either common or difference, can be independently included or excluded from the merge output. Wherever one current version agrees with the ancestor, merge presumes that the other current version is a deliberate change which should be kept in the merged version.

NOTE: Merge uses a common ancestor approach to control the merge selection algorithm. If a common ancestor is not available, as in the case of merging a file outside of Razor, File2 will be used as the common ancestor. The ancestor is very helpful in providing context for differences and for conflict resolution.

File selection

To merge files, highlight a file from the main display of the versions program and select the Merge option from the Utilities menu.² A dialog similar to the one below will appear.




While strictly speaking the order of the files does not matter, the merge algorithm will be better served if the Merge file (we will refer to as File1) is thought to be merged into the `Merge with' file (referred to as File2), just as the file selection pull-down menus suggest.

The Check-in as Latest Trunk check box is enabled if the file is not currently checked out for edit, and File 2 is selected from Razor. The Terminate Branch check box will be enabled if File 1 is selected from Razor, the Check-in as Latest Trunk check box is selected, File 1 is a current branch (that is, not a previously terminated branch), and the File 1 branch is not currently checked out for edit.³

Difference display

The main merge window is divided into three major areas: the ancestor area, the difference area, and the merge result area. Each of these areas can be resized. Below is a sample display with the major areas identified...




The ancestor area includes the browse buttons (for the original files and the ancestor file), a compare button (to re-execute the compare if merging a file outside of Razor), and the merge button. The ancestor file becomes the reference point for differences as well as resolving potential conflicts between files. The ancestor file is the lowest common version between the two merge files or File2 if one or both of the merge files is outside of Razor.

Differences are displayed in the Difference area in a series of panes - one for each difference between the two files and optionally the common text between the two.⁴ The difference area is where most of your attention will be concentrated. The important components are....




In the difference area, a difference is visibly cued by its position, being left-oriented (change from File1), right-oriented (change from File2), side-by-side (change from both File1 and File2) or the full pane (text common to all three files). Each difference has one of these states (the state can be displayed by selecting on the Ancestor button to display the message in the status area):

• Text common to all files.⁵
• Text has been modified or added to both files.
• Text has been added to File1 or File2.
• Text has been deleted from File1 or File2.
• Text in all three files is different (referred to as a conflict).⁶

Interactive merging, a walk-through

After the comparison is done and the differences displayed, the interactive merging starts. The first thing you will notice is the merge display is completed and a message is written to the status line with the number of conflicts. In the simplest case, that is - no conflicts, you could probably select the Merge button to copy the results to the merge output area, and then save the results either to a file, or check the merge back in to Razor.

Let's walk through an example of merging the efforts of our two programmers mentioned earlier. In a perfect world, the programmers did not modify the same sections of code and you want all of the changes from both. In that case, go buy a lottery ticket because you've beaten the odds.

Now for the real world, while the objective of the two programmers was different, they editorialized and managed to change the same section of code in different ways. This is called a conflict. The most challenging task in merging files is to resolve conflicts (much as it is in life.) You select which panes get included in the merge result by selecting the Include/exclude toggle button. By default, merge will pick what it thinks is the best choice for the merge result. Say merge notices that text was added to File2 and the text did not exist in File1 or the ancestor, then it will decide to include the new text in the merge result. If there is no clear "winner," such as when the text is different in all three files, merge will punt and choose File2.

NOTE: Merge will generally produce reasonable output if you pick two files that came from a reasonable ancestor. It really helps if both files are managed by Razor, as you might expect. But however good the algorithm is, merge is not a mind reader. Care must be taken to understand the differences and how they should be merged to produce the final product. Don't just "merge and go!"

So how will various differences be displayed? Consider the following code snippet for the ancestor...

/* Extended regular expression matching and search library,
   version 0.12.
   (Implements POSIX draft P10003.2/D11.2, except for
   internationalization features.)

   Copyright (C) 1993 Free Software Foundation, Inc.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */

#include <string.h>
#ifndef bcmp
#define bcmp(s1, s2, n)	memcmp ((s1), (s2), (n))
#endif
#ifndef bcopy
#define bcopy(s, d, n)	memcpy ((d), (s), (n))
#endif
#ifndef bzero
#define bzero(s, n)	memset ((s), 0, (n))
#endif

#define REGEX_MALLOC

/* AIX requires this to be the first thing in the file. */
//#if defined (_AIX) && !defined (REGEX_MALLOC)
//jeb  #pragma alloca
//#endif

#define _GNU_SOURCE

Here is a sample of some merge outputs and a short explanation. With each of these examples, the difference pane and the highlighted ancestor section will be shown.

Unchanged text




Text added to one file




Text modified or added to both files




Text is different in all three files

The above case highlights a conflict. Read on...

Resolving conflicts

I'm sure you've turned to this section looking for really inspiring words of wisdom on how to resolve conflicts. Sorry. We can only tell you the mechanics within the merge interface to make the changes. You have to do the hard part.

Interactive selection/edit of the merge result for each pane is controlled by the three edit control buttons and one of two include pane toggle buttons shown below:


.

The pencil button enables editing of the difference pane, and changes the background color to show that it has been enabled. Normally difference panes are not editable. Text can be entered or pasted from another source once editing is enabled. If you really blew it, you can undo edits with the Undo button. This gives you the ability to make little tweaks, or to completely change the text that will be merged.

The Ancestor area highlights the related difference section in the ancestor. If there is no line in the ancestor file, the single line prior to the difference section will be highlighted.

The square and diamond toggle buttons⁷ enable or disable the difference pane's inclusion into the merged output. By default, merge will always select a section for inclusion, even if conflicts exist. In the case of conflicts, merge picks File2 but can certainly be overruled by toggling the button, or either pane can be edited and selected. To make editing changes, select the square/diamond button to enable it, then edit the pane. Once a change has been made, the background color will change to show that it has been edited.⁸

Saving merged output

When you've got something you're happy with, select Merge and your merge selections will be copied to the merge result area. Once you have something in the merge result, you have the option of saving the output. Merge results can be written to a file, or checked directly back into Razor.

TIP: To have the merged result checked back into Razor, the Check-In as Latest Trunk check box must have been checked when the files were selected. Also, File2 must be a Razor file - because that is the file you are merging into, and cannot be checked out.

Controlling the merge view

If the amount of information is oppressive, you have several display options that effect how and how much information is presented. These options are all controlled under the View menu.

• Each difference pane can be resized and subsequently reset with the Restore Diff Pane Height (^R) option.
• You can hide/show the common sections of both files by selecting the Hide Common Data (^D) option from the View menu. Select Show Common Data (^D) to show all data, common or differences.
• Since resolving conflicts is a key aspect of merging files, just conflicts can be displayed with the Show Conflicts Only (^S) option. All differences can be displayed by then selecting the Show Differences/All (^S) option.

¹ See the section "Seeing how versions/files differ" on page 111 about displaying differences between files.
² The Merge option is not enabled for branched versions or binary files.
³ Are you confused yet?
⁴ For more information on this and other display options, see "Controlling the merge view" on page 105.
⁵ Display of common data can be controlled with the Hide common data option under View.
⁶ Display can be limited to just conflicts with the Show conflicts option under View.
⁷ On the PC these buttons are shown as an option button and an option checked button, respectively.
⁸ The background color and other X resource settings for merge can be found on page 286.