merge

Merges versions of a text-file element or a directory

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

  • VersionVault on UNIX and Linux:
    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 | -qnt/rivial ]

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

  • VersionVault 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 | -qnt/rivial ]

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

  • VersionVault Remote Client:
    merge { -out output-pname | -to contrib-&-result-pname }
    { [ -g/raphical | [ -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 | -qnt/rivial ]

    [ -opt/ions pass-through-options ]

    { -ver/sion contrib-version-selector ... | contrib-pname ... }

Description

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.

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 and Linux)
  • Member of the VersionVault administrators group (VersionVault 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
Specifies a view-private 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.
-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:
  1. 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.
  2. Stores the merged output 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

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

    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.

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.

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 and Linux 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 all contributors are not 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. When you specify this option, no merge arrow is drawn.

Specifying special merges

Default
A standard merge is performed: all the differences between the base contributor and each nonbase 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 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.
-q/uery
Prompts you for a choice on 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.
-qnt/rivial
Turns off automated merging and prompts you to determine whether you want to proceed except in the case where a trivial merge (branch copy) would be done.

Specifying a comment for the merge arrow

Default
Attaches a comment to each merge arrow (hyperlink of type Merge) with commenting controlled by your .versionvault_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 (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 valid options, 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 -version /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 do not use -to, you must specify at least two contrib-pname arguments.

These two commands are equivalent:

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

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might 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 might 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 system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Merge the version of file util.c in the current view 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

  • 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