merge
Merges versions of a text-file
element or a directory
SYNOPSIS
- 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 ... }
- 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 ... }
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)
- Member
of the ClearCase administrators 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
- 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:
- 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 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.
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
- 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
(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:
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:
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.
- 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.
- 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.
- Merge
the version of file util.c to version 3 on the main branch,
placing the merged output in a temporary file.
- Subtractive
merge: remove the changes made in version 3 from file util.c.