Command Reference, Release 2002.05.00, All Platforms

merge

Merges versions of a text-file element or a directory

APPLICABILITY


Product	Command Type
ClearCase	cleartool subcommand
ClearCase LT	cleartool subcommand
Attache	command


Platform
UNIX
Windows

SYNOPSIS

ClearCase and ClearCase LT on UNIX:

merge { -out output-pname | -to contrib-&-result-pname }: [ -g·raphical [ -tin·y ] |
[ -tin·y | -win·dow ] [ -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 ... }

ClearCase and ClearCase LT on Windows:

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 and ClearCase LT

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 the 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

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 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.

RESTRICTIONS

Identities: For all operations except creating a merge arrow, no special identity is required. To create a merge arrow, you must have one of the following identities:

Element owner

Element group member
VOB owner
root (UNIX)
Member of the ClearCase group (ClearCase on Windows)
Local administrator of the ClearCase LT server host (ClearCase LT on Windows)

Locks: An error occurs if one or more of these objects are locked: VOB, element type, element, branch type, branch, hyperlink type.

Mastership: (Replicated VOBs) No mastership restrictions.

OPTIONS AND ARGUMENTS

DESTINATION OF MERGE OUTPUT. Default: None.

-out output-pname: (File merge) 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) Note that output-pname is not uploaded to the view. 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.

NOTE: When merging files of type html, if the machine on which you execute merge -graphical is not the machine on which you run your HTML browser, your browser may not be able to find the pathname to the files being merged.

USING A SEPARATE WINDOW. Default: Sends output to the current window.

-tin·y: Same as -window, but uses a smaller font in a 165-character window.
-win·dow: Displays output in a separate window, formatted as with -columns 120. Type an operating system interrupt character (typically, CTRL+C in the window to close it. The merge command returns immediately, not waiting for the window to be closed.

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: If all contributors are versions of the same element, this command determines the base contributor. If contributors are not all versions of the same element, there is no base contributor and you must resolve discrepancies among the contributors.

-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. 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 on the same branch. 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 same-branch 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 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 and ClearCase LT, 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 and ClearCase LT, 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 and ClearCase LT)

: 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)
: 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

The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include 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 UNIX shell or Windows command interpreter prompt, followed by the cleartool command. 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 and ClearCase LT)

cmd-context merge -to util.c -abort -narrows -version /main/rel2_bugfix/LATEST /main/test/LATEST (Attache/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) 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

-hea·ders_only -qui·et (mutually exclusive)
	-headers_only lists only the header line of each difference. The difference lines themselves are omitted. -quiet suppresses the file summary from the beginning of the report.
-b·lank_ignore
	Ignores extra white space characters in text lines: leading and trailing white space is ignored; internal runs of white space are treated like a single SPACE character.
-vst·ack -hst·ack
	-vst·ack stacks the difference panes vertically, with the base contributor at the top. -hst·ack displays the difference panes horizontally, with the base contributor on the left (the default behavior).

	(ClearCase and ClearCase LT file merge) Preserves the target's current contents in view-private file `contrib-&-result-pname`.contrib. The file name may get a .n extension, to prevent a name collision.
	Stores the merged output in the workspace in `contrib-&-result-pname`. You can suppress these data-manipulation steps by using -ndata; you must do so to avoid an error if the file is not checked out: `cleartool: Error: ... Only a checked out version can be modified to have the data resulting from the merge.`
	Creates a merge arrow (hyperlink of type Merge) from all other contributors to the checked-out version. You can suppress this step by using the -narrows option. In ClearCase and ClearCase LT, if the merge target cannot be overwritten, merge saves its work in the view-private file `contrib-&-result-pname`.merge The file name may have a .`n` extension, to prevent a name collision. In Attache, if the merge target cannot be overwritten, merge saves its work in the workspace file `contrib-&-result-pname`.mrg, or if that extension exists, `.m00`, `.m01`, and so on.