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