merge

Merges versions of a text-file element or a directory

APPLICABILITY

ClearCase (cleartool subcommand), Attache (command)

SYNOPSIS

• ClearCase:

  merge { -out output-pname | -to contrib-&-result-pname }

  
  

  [ -g·raphical [ -tin·y ] | [ -ser·ial_format | -dif·f_format | -col·umns n ] ]
  [ -bas·e pname | -ins·ert | -del·ete ] [ -nda·ta | -nar·rows ] [ -rep·lace ]
  [ -q·uery |-abo·rt | -qal·l ]
  [ -c·omment comment | -cfi·le comment-file-pname |-cq·uery | -cqe·ach | -nc·omment ]
  [ -opt·ions pass-through-options ]
  { -ver·sion contrib-version-selector ... | contrib-pname ... }

• Attache:

  merge { -out output-pname | -to contrib-&-result-pname }

  
  

  { -g·raphical [ -tin·y ] [ -nda·ta | -nar·rows ] [ -q·uery |-abo·rt | -qal·l ] |
  { -nda·ta | -abo·rt [ -nar·rows ] }
  [ -ser·ial_format | -dif·f_format | -col·umns n ] }
  [ -bas·e pname | -ins·ert | -del·ete ] [ -rep·lace ]
  [ -c·omment comment | -cfi·le comment-file-pname |-cq·uery | -cqe·ach | -nc·omment ]
  [ -opt·ions pass-through-options ]
  { -ver·sion contrib-version-selector ... | contrib-pname ... }

DESCRIPTION

ClearCase only

The merge command calls an element-type-specific program (the merge method) to merge the contents of two or more files, or two or more directories. Typically the files are versions of the same file element. A directory merge must involve versions of the same directory element.

When used to merge directory versions in a snapshot view, this command also updates the directory (and subdirectories, if necessary). (See update.)

You can also perform a subtractive merge, which removes from a version the changes made in one or more of its predecessors.

merge uses ClearCase's type manager mechanism to select a merge method. For details, see the type_manager reference page. merge methods are supplied only for certain element types.

Attache only

This command merges the contents of two or more files, or two or more directories. Typically the files are versions of the same file element. A directory merge must involve versions of the same directory element.

merge presumes that all files are text files, using the built-in textual diff and merge, and bypassing the ClearCase type manager mechanism. Any missing file contributors are downloaded temporarily to the workspace. For a directory merge, the text file encodings of the directories are downloaded. If the merge is successful and should have a merge hyperlink created, a remote merge -ndata command is issued to create the hyperlink. The merged result is not uploaded to the view until a checkin or put of the result occurs. Local directories are not updated after a directory merge; you must issue get commands to update merged directories.

You can also perform a subtractive merge, which removes from a version the changes made in one or more of its predecessors.

FILE MERGE ALGORITHM

A merge is a straightforward extension of a file comparison. Instead of displaying the differences, the merge method (ClearCase) or merge (Attache) analyzes them (sometimes with your help) and copies sections of text to the output file:

• Sections in which there are no differences among the contributors are copied to the output file.
• For differences in which exactly one contributor differs from the base contributor, the merge method (ClearCase) or merge (Attache) accepts the change and copies the contributor's modified section to the output file:

  ------------[changed 3-4]----|--------[changed to 3-4 file 2]--- now is the thyme                     | now is the time for all good men                     | for all good people                                     -|- *** Automatic: Applying CHANGE from file 2 [lines 3-4] ============

  (In ClearCase, the -qall option turns off automatic acceptance of this kind of change.)

• (ClearCase only) For differences in which two or more contributors differ from the base contributor, the merge method detects the conflict, and prompts you to resolve it. It displays all contributor differences, and allows you to accept or reject each one for inclusion in the output file.

  [changed 10]        |          [changed to 10 file 2]--- cent                               | sent                                   -|-                [changed 10]        |          [changed to 10 file 3]--- cent                               | scent                                    |- Do you want the CHANGE made in file 2? [yes] no Do you want the CHANGE made in file 3? [yes] yes Applying CHANGE from file 3 [line 10] ============

  Be sure to verify that the changes you accept produce consistent merged output. For example, after performing a merge involving file util.c, you can compare files util.c.contrib (which contains its previous contents) and the new util.c (which contains the merge output).

• (Attache only) Be sure to verify that the changes you accept produce consistent merged output. For example, if you perform a merge involving a file util.c immediately after you check out the file, you can use the diff command with the -pred option to compare the new util.c in the workspace (containing the merge output) with the original util.c in the view. However, if you've made changes to the file since you checked it out, you can make a copy of the modified local file in your workspace before performing the merge. After the merge, you can compare the new util.c with the premerge local copy.

Determination of the Base Contributor

If all the contributors are versions of the same element, merge determines the base contributor automatically. It examines the element's "merge-enhanced" version tree, which is the directed graph consisting of the actual version tree along with all the merge arrows created by previous merge operations. This examination reveals the relationships among versions from the standpoint of their contents (which versions contributed their data to me?), rather than from the standpoint of their creation order (which versions were created before me?). merge selects the closest common ancestor in this enhanced version tree as the base contributor.

If no merges have been performed in the element, the actual common ancestor (A) of the contributors (C) in the version tree is selected to be the base contributor. Figure 13 illustrates some common cases.

Figure 13 Determination of the Base Contributor for a Merge

If the contributors are not all versions of the same element, there is no base contributor. This means that you must resolve all discrepancies among the contributors. In ClearCase only, the -qall option is enabled automatically.

Recording of Merge Arrows

Under certain circumstances, cleartool or Attache records the merge by creating one or more merge arrows (hyperlinks of type Merge):

• All contributor files must be versions of the same file element.
• One of the contributors must be a checked-out version, and you must specify this version as the target to be overwritten with the merge output (-to option). (Alternatively, you can use the -ndata option to create merge arrows without performing a merge; in this case, you do not need to check out any of the contributors.)
• You must not use the -narrows option, which suppresses creation of merge arrows.
• You must not use any of these options: -insert, -delete, -base.

If all these conditions hold, cleartool or Attache draws an arrow from each contributor version (except the base contributor) to the target version.

In ClearCase, you can view merge arrows with the Version Tree Browser by clicking Versions ` Show version tree.

The find and lsvtree -merge commands can locate versions with Merge hyperlinks. The describe command lists all of a version's hyperlinks, including merge arrows:

cmd-context describe util.c@@\main\3
version "util.c@@\main\3"
  .
  .
  .
  Hyperlinks:
  Merge@278@\vob_3 \vob_3\src\util.c@@\main\rel2_bugfix\1
  -> \vob_3\src\util.c@@\main\3

DIRECTORY MERGE ALGORITHM

Each version of a ClearCase directory element contains the names of certain file elements, directory elements, and VOB symbolic links. merge can process two or more versions of the same directory element, producing a directory version that reflects the contents of all the contributors. The algorithm is similar to that for a file merge: merge compares a base contributor (common ancestor) version with each other contributor, producing a set of differences. It applies these differences to the base contributor as automatically as possible, prompting for user interaction only when two or more of the contributors are in conflict. (See the diff reference page for more on this algorithm.)

One of the directory versions-the merge target, specified with the -to option-must be checked out. (Typically, it is the version in your view.) merge updates the checked-out directory by adding, removing, and changing names of elements and/or links.

NOTE: In ClearCase, a directory merge does not leave behind a .contrib file, with the premerge contents of the target version.

We recommend that you use this procedure when merging directories:

1. Make sure that all contributor versions of the directory are checked in.
2. Check out the target version of the directory.
3. Perform the directory merge immediately, without making any other changes to the checked-out version.

This procedure makes it easy to determine exactly what the merge accomplished: enter a diff -predecessor command on the checked-out version, which has just been updated by merge.

Using ln and rmname to Implement a Merge

ClearCase and Attache implement directory merges using VOB hard links. You can use the ClearCase or Attache ln and rmname commands to perform full or partial merges manually. See the ln and rmname reference pages for details.

COMMON SCENARIOS

This section presents common scenarios for performing merges. See also EXAMPLES.

Case 1: Merging from a Branch

A common use of this command is to combine the changes made on a subbranch (for example, a bugfix branch) of a file element with changes made on the main branch. Figure 14 shows such a merge.

The target is C1, the checked-out version on the main branch, and the other contributor is C2, the latest version on a bugfix branch. cleartool or Attache determines that version B is the common ancestor, to be used as the base file. The merged result replaces the contents of the target, C1.

Figure 14 Merging from a Branch

Case 2: Merging to an Unreserved Checkout

Another common use of this command arises from the unreserved checkout capability: you perform an unreserved checkout and edit the file, but someone else checks in a successor version ahead of you. You can check in your work only if you first merge with the version that was already checked in.

Figure 15 shows a merge in which the target is C1, an unreserved, checked-out version. The other contributor is C2, the version that was checked before C1. cleartool or Attache determines that version B is the common ancestor, to be used as the base file. The result of the merge replaces the contents of the target, C1. cleartool or Attache allows C1 to be checked in when it sees the merge arrow from C2 to C1.

Figure 15 Merging into an Unreserved Checkout

SPECIAL MERGE SCENARIOS

merge has options that invoke special kinds of merges: selective and subtractive.

Selective Merges

By default, merge takes into account an entire, cumulative sequence of changes. For example, a merge from version\main\bugfix\4 to the main branch involves the changes made in version 3, and also the changes made in versions 2 and 1 on that branch. In some cases, however, you may want to incorporate only the changes made in one specific version (or a range of versions), disregarding the changes made in its predecessors. The -insert option implements a selective merge capability, as illustrated in Figure 16. In each merge, the shaded versions are the ones whose changes are merged to the main branch. (The commands in the following examples are wrapped to conserve space. Enter commands on a single line.)

Figure 16 Selective Merge

In a selective merge, no merge arrow is created; ClearCase uses merge arrows to indicate that all of a version's data has been merged.

Subtractive Merges

The -delete option invokes a subtractive merge, which is the opposite of a selective merge:

• A selective merge adds to the checked-out version the changes made in one or more other versions.
• A subtractive merge removes from the checked-out version the changes made in one or more of its predecessors.

For example, to undo the changes made in versions 5 - 9 of file foo.c, while retaining all the changes made before version 5 and after version 9, you can issue this command:

cmd-context merge -to foo.c -delete -ver \main\5 \main\9 (ClearCase only)

cmd-context merge -abort -to foo.c -delete -ver \main\5 \main\9 (Attache only)

PERMISSIONS AND LOCKS

Permissions Checking: Special permissions apply for creation of a merge arrow only. For each object processed, you must be one of the following: element group member, element owner, VOB owner, member of the ClearCase group. See the permissions reference page.

Locks: An error occurs if any of the following objects are locked: VOB, element type, element, branch type, branch, hyperlink type.

OPTIONS AND ARGUMENTS

DESTINATION OF MERGE OUTPUT.  Default: None.

-out output-pname

(File merge only) Specifies a view-private or workspace file or non-MVFS file to be the merge target. output-pname is not used as a contributor, and no merge arrows are created. Use this option to perform a merge that does not overwrite any of its contributors. An error occurs if output-pname already exists.

(Attache only) Note that output-pname is not uploaded to the vie. If it corresponds to a checked-out version, it remains in the workspace until it is checked in.

-to contrib-&-result-pname

Specifies a version of a file or directory element to be the merge target: one of the contributors to the merge, and also the location where the merged output is stored. merge proceeds as follows:

PERFORMING A GRAPHICAL MERGE. Default: Performs the merge in the command window and uses the default display font.

-g·raphical [ -tin·y ]

Performs the merge graphically. With -tiny, a smaller font is used to increase the amount of text displayed in each display pane.

INTERACTIVE MERGES NOT SUPPORTED IN ATTACHE. You must specify -ndata or -abort from below.

OUTPUT FORMAT.  Default: Displays output in the format described in the diff reference page.

-ser·ial_format

Reports differences with each line containing output from one contributor, instead of in a side-by-side format.

-dif·f_format

Displays output in the same style as the UNIX diff(1) utility.

-col·umns n

Establishes the overall width of side-by-side output. The default width is 80; only the first 40 or so characters of corresponding difference lines appear. If n does not exceed the default width, this option is ignored.

SPECIFYING THE BASE CONTRIBUTOR.  Default: Uses the procedure described in Determination of the Base Contributor.

-bas·e pname

Specifies pname as the base contributor for the merge. You cannot use the -version option to specify this argument; use a version-extended pathname.

SPECIFYING SPECIAL MERGES.  Default: A standard merge is performed: all the differences between the base contributor and each non-base contributor are taken into account.

-ins·ert

Invokes a selective merge of the changes made in one or more versions. See Selective Merges for a description. If you specify one contributor with -version or a pname argument, only that version's changes are merged. Specifying two contributors defines an inclusive range of versions; only the changes made in that range of versions are merged.

No merge arrow is created in a selective merge.

RESTRICTIONS: You must specify the target version with the -to option. No version specified with -version or a pname argument can be a predecessor of the target version.

-del·ete

Invokes a subtractive merge of the changes made in one or more versions. See Subtractive Merges for a description. If you specify one contributor with -version or a pname argument, only that version's changes are removed. Specifying two contributors defines an inclusive range of versions; only the changes made in that range of versions are removed.

No merge arrow is created in a subtractive merge.

RESTRICTIONS: You must specify the target version with the -to option. All versions specified with -version or a pname argument must be predecessors of the target version.

SUPPRESSING PARTS OF THE MERGE PROCESS.  Default: merge stores its results in the workspace location specified by -to or -out; with -to, it also creates merge arrows.

-nda·ta

(Use only with -to) Suppresses the merge, but creates the corresponding merge arrows. An error occurs if you use -ndata along with -out; together, the two options leave merge with no work to do.

-nar·rows

(For use with -to; invoked by -out) Performs the merge, but suppresses the creation of merge arrows.

REPLACING A PREVIOUS MERGE.  Default: An error occurs if a merge arrow is already attached to any version where merge would create one.

-rep·lace

Allows creation of new merge arrows to replace existing ones.

CONTROLLING USER INTERACTION. Default: Works as automatically as possible, prompting you to make a choice only when two or more non-base contributors differ from the base contributor.

NOTE: In Attache, the -query and -qall options are available only when performing a graphical merge (-graphical).

-q·uery

Turns off automatic merging for nontrivial merges and prompts you to proceed with every change in the from-versions. Changes in the to-version are automatically accepted unless a conflict exists. When you specify the -out option, cleartool uses the last pathname on the command line as the to-version.

-abo·rt

Cancels the command instead of engaging in a user interaction; a merge takes place only if it is completely automatic. If two or more nonbase contributors differ from the base contributor, a warning is issued and the command is canceled. This command is useful in shell scripts that batch many merges (for example, all file elements in a directory) into a single procedure.

-qal·l

Turns off automated merging. merge prompts you to make a choice every time a nonbase contributor differs from the base contributor. This option is turned on automatically if merge cannot determine a common ancestor (or other base contributor), and you do not use -base.

SPECIFYING A COMMENT FOR THE MERGE ARROW.  Default: Attaches a comment to each merge arrow (hyperlink of type Merge) with commenting controlled by your .clearcase_profile file (default: -nc). See CUSTOMIZING COMMENT HANDLING in the comments reference page. Comments can be edited with chevent.

-c·omment comment | -cfi·le comment-file-pname |-cq·uery | -cqe·ach | -nc·omment

Overrides the default with the option you specify. See the comments reference page.

PASSING THROUGH OPTIONS TO THE 'MERGE' METHOD.  Default: Does not pass any special options to the underlying merge method (in ClearCase, implemented by the cleardiff utility for all predefined element types).

-opt·ions pass-through-options

Allows you to specify merge options that are not directly supported on the merge command line.

If you are specifying more than one pass-through option, enclose them in quotes; merge must see them as a single command-line argument.

For descriptions of the options valid for ClearCase, see the cleardiff reference page.

For example, this cleartool command passes through the -quiet and -blank_ignore options:

cmd-context merge -options "-qui -b" -to util.c \main\bugfix\LATEST\main\3

Attache accepts the following pass-through options:

For example, this Attache command passes through the -quiet and -blank_ignore options:

cmd-context merge -ndata -options "-qui -b" -to util.c \main\bugfix\LATEST \main\3

SPECIFYING THE DATA TO BE MERGED.  Default: None.

-ver·sion contrib-version-selector ...

(For use only if all contributors are versions of the same element) If you use the -to option to specify one contributor, you can specify the others with -ver followed by one or more version selectors. (See the version_selector reference page.)

contrib-pname ...

One or more pathnames, indicating the objects to be merged: versions of file elements, versions of directory elements, or any other files. If you don't use -to, you must specify at least two contrib-pname arguments.

These two commands are equivalent:

(ClearCase only)

cmd-context merge -to foo.c -version \main\bugfix\LATEST \main\3

cmd-context merge -to foo.c foo.c@@\main\bugfix\LATEST foo.c@@\main\3

(Attache only)

cmd-context merge -nda -to foo.c -version \main\bugfix\LATEST \main\3

cmd-context merge -nda -to foo.c foo.c@@\main\bugfix\LATEST foo.c@@\main\3

EXAMPLES

Examples including wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the command interpreter prompt. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace prompt.

• Merge the version of file util.c in the current view or workspace with the most recent versions on the rel2_bugfix and test branches; suppress the creation of merge arrows.

cmd-context merge -to util.c -narrows -version \main\rel2_bugfix\LATEST ^
\main\test\LATEST (ClearCase only)

cmd-context merge -to util.c -abort -narrows -version \main\rel2_bugfix\LATEST \main\test\LATEST (Attache only/this command must be entered on a single line)

• Merge the version of file util.c, in view jk_fix, to version 3 on the main branch, placing the merged output in a temporary file.

cmd-context merge -out \tmp\proj.out util.c@@\main\3 \jk_fix\users_hw\src\util.c

• Merge the version of file util.c to version 3 on the main branch, placing the merged output in a temporary file.

cmd-context merge -abort -out /tmp/proj.out util.c@@\main\3 util.c

• Subtractive merge: remove the changes made in version 3 from file util.c.

cmd-context merge -to util.c -abort -delete -version util.c@@\main\3

• (Attache only) Use merge -graphical to merge the file util.c in the current workspace with the most recent version on the rel2_bugfix branch.

cmd-context merge -to util.c -graphical -version \main\rel2_bugfix\LATEST

SEE ALSO

describe, diff, find, findmerge, rmmerge, update