merge
Merges element versions, branch versions, or files.
Formats
merge {pathname_1 | element_name_1[version_specifier]}
-with {pathname_2 | element_name_2[version_specifier]}
-fetch -into pathname_3 [-r]
[-serial] [-width nn] [-tiny] [-qa] [-nq]
merge element_name[version_specifier] -with target_lod
-reserve [-into pathname_3] [-r]
[-serial] [-width nn] [-tiny] [-qa] [-nq]
merge element_name[version_specifier] -with target_lod
-reserve [-nq] -no_text
Description
You can use merge to
o Interleave the text of two element or branch versions, the text of a
version and another file, or the text of two files. The result is a
file. (merge -fetch)
o Interleave the text of an element version on one line of descent with
the most recent version on another line of descent of the same
element. The result is a reservation of the second line of descent
and a file containing the interleaved text (which can be replaced into
the reserved line of descent). The subsequent replacement of a merge
file created with this form of the merge command results in a record
of the merger being recorded in the library's database. (merge
-reserve)
First we'll present the differences between the two types of merge operations.
Later, we'll discuss the merger process.
merge -fetch
The first kind, merge -fetch, simply combines the text of the first version or
file with that of the second (-with). The result is a merge file. You define
the name and location of the merge file in the argument -into pathname_3, which
is required for this kind of merge. Add the -r option if pathname_3 already
exists and you want to overwrite its contents.
Because merge -fetch objects can be either element versions or files,
ambiguities may arise. For example, pathname_2 might refer both to a file in
the working directory and to an element in the current library. The DSEE
facility resolves conflicts of this kind by first searching for the file. If
the DSEE facility fails to find the file, it uses the most recent version on the
main line of descent of the element with that name.
Like the fetch command, merge -fetch doesn't cause the DSEE facility to modify
an element's history.
merge -reserve
The -reserve option produces a merge file in preparation for merging versions on
two lines of descent of an element. The version of the element identified by
the first argument to the command is known as the source version for the merge
operation. The line of descent identified by the argument to the -with option
is known as the target line of descent.
merge -reserve combines the source version with the most recent version on the
target line of descent. It also reserves the target line of descent. The DSEE
facility makes note in the history database that the reservation is associated
with a merger; subsequent show reservations, show status, and other similar
reporting commands report both the target line of descent's reservation and the
related merger.
merge -reserve notifies the current library's history database of the merger.
Later, when you replace the target line of descent, the DSEE facility includes a
notation of the merger in the database record of the replace operation. It also
supplements its record of the replace operation that created the source version
with a notation of the merger.
Because merge -reserve reserves the target line of descent, this line of descent
can't already be reserved when you issue the command.
The Merger Process
Whether you use merge -fetch or merge -reserve, the actions the DSEE facility
takes to produce the merge file are the same. The DSEE facility displays the
merge file in an edit pad at the top of the DSEE window. It builds the file
dynamically, asking you questions when it can't determine what text should go
into the merge file. You can edit the merge file in the edit pad during and
after the merger.
The DSEE facility creates the merge file by interleaving the text of the two
objects, comparing them section by section, and writing sections that are
identical in both texts to the merge file. When sections of the two objects'
texts differ, the DSEE facility does what it can to resolve the conflict. In
certain circumstances (explained below), the DSEE facility automatically
determines which text to incorporate in the merge file. Otherwise, the DSEE
facility asks you to resolve the conflict, presenting you with both renditions
of the differing text, and classifying each difference between the two
renditions as an insertion, a deletion, a change or a move.
Once you've told the DSEE facility how to resolve a conflict, it updates the
merge file. Then, the DSEE facility pauses in the merger process to allow you
to make further edits to the merge file. When you want the merger to continue,
press <RETURN> at the prompt.
When the DSEE facility completes the merge, type CTRL/Y to close the merge file
edit pad. (You may wish to edit further before typing CTRL/Y). Alternatively,
you can edit the merge file after closing the edit pad by pressing <EDIT>.
Note that if you are merging versions of one element, and that element is not in
the current library, the DSEE facility checks to see whether you have a current
system model setting. If you do, the DSEE facility searches the current model
for an Element of the given name. If it finds a single Element block with the
same name, the DSEE facility resets your current library setting to the library
containing that Element's primary dependency and then performs the merger.
Three-Way Merge
We use the term three-way merge to refer to the way that the DSEE facility
behaves when both of the objects that you are merging are versions of the same
element. This is always the case when you do a merge -reserve. If you issue
merge -fetch to merge two versions of an element on different lines of descent,
the DSEE facility also does a three-way merge.
The third object in such a merger is the youngest common ancestor of the other
two. If, for instance, you were merging a version on a branch that grew from
the main line of descent at the version named baselevel_2 into the main line of
descent, the common ancestor of both objects would be the version named
baselevel_2. This third party to the merger is known as the base version of the
element.
In a three-way merge, the DSEE facility uses the base version to help resolve
differences between the two objects you are merging. This reduces the number of
questions that the DSEE facility has to ask you during a merge operation.
Whenever the DSEE facility finds different renditions of sections of text in the
objects being merged, it consults the base version. If either one of the two
renditions appears in the base version, the DSEE facility uses the other
rendition in the merge file.
In cases when both renditions of the conflicting text differ from that of the
base version, the DSEE facility asks you to resolve the conflict in the manner
described in the previous section.
NOTE: The decisions that the DSEE facility makes during a three-way
merge are based on textual differences only. The DSEE facility
can't verify that the resultant file is correct; you must do
this yourself. It's important that you double-check a merge
file at the end of a merge operation to make sure that its
contents are accurate.
Replacing a Reserved Target Line of Descent
Once you've verified that a merge file produced by merge -reserve is accurate,
you can use the replace command to replace the target line of descent. The
merge file becomes the new most recent version on the target line of descent.
As mentioned above, the replace operation causes the DSEE facility to record the
merger in the history of the new most recent version on the main line of
descent. It also updates the history on the source version, adding a
notification that that version of the element was merged into the target line of
descent and identifying the new version that was created on the target line of
descent.
Obsoleting a Source Version's Line of Descent
Sometimes, you'll find that you want to end the line of descent on which the
source version resides after a merger. This might be the case, for instance,
when you are merging all of the bug fixes done to a version of an element used
in a major release of a product into the element's main line of descent in
preparation for another major release of the product. In such cases, use the
obsolete command to terminate the line of descent.
The -into Option
-into is optional only to merge -reserve; it is required when you issue merge
-fetch. With -into, you specify the name of the merge file. If you omit the
-into option when issuing merge -reserve, your merge file is a file in your
working directory with the same name as the element involved in the merger (as
would be the case if you reserved the element with the reserve command). Use
the -r option if you want the DSEE facility to overwrite the contents of an
existing file with the results of your merge operation.
The -serial, -width and -tiny options
These options allow you to control the way that the DSEE facility displays
conflicting lines. By default, the DSEE facility displays the conflicting lines
in two-column format, with the line from the first object (pathname_1 or
element_name_1[version_specifier]) on the right and the line from the second
object on the left.
The -width nn option changes the width of the display to nn characters. The
-serial option displays the conflicting lines in serial, rather than columnar,
format, with the text of the second object (the argument to the -with option)
appearing first. The -tiny option displays the text in a small font.
The -qa Option
This option is useful when you are doing a three-way merge (described above).
The -qa option instructs the DSEE facility to ask you to verify all conflicts,
even those it can resolve automatically by referring to the base version. When
you use -qa, the DSEE facility still consults the base version to resolve
differences when possible. However, the DSEE facility lets you know what
resolutions it comes to as a result of consulting the base version before
updating the merge file. The DSEE facility asks you whether it's all right for
it to take the action that it has deemed appropriate.
The -nq Option
Like all other commands that prompt you for information, the merge command takes
the -nq option. When you issue merge with the -nq option, the DSEE facility
doesn't query you to resolve any differences between the two objects being
merged. Instead, it attempts to create a merge file based entirely on decisions
it can make automatically (using three-way merge assumptions). If the DSEE
facility can't make a merge decision automatically, it aborts the merge
operation. No merge file is produced, and the target line of descent is
unreserved.
The -nq command is useful when you're redirecting input to the DSEE facility.
You can write a command file that includes a merge command. When you execute
the command file, the DSEE facility won't stop execution to prompt you for
input.
The -no_text Option
This option is useful when you don't want the DSEE facility to perform the
merger process, but you do want some record of a merge you're doing yourself
entered in the library history database. For example, if you know that the
differences between the two objects you're merging are so great that a DSEE
merge would be more lengthy and problematical than simply creating and editing a
new version on one of the object's line of descent, you could issue merge
-reserve with the -no_text option. As a result, the DSEE facility wouldn't
create a merge file. However, it would reserve the target line of descent for
you. When you replace the line of descent, the DSEE facility records a merger
in the history of both the new version and the source version.
Options:
-fetch Performs a merge -fetch operation.
-reserve Performs a merge -reserve operation.
-into pathname_3 [-r] (Optional for merge -reserve; required for
merge -fetch.) Specifies an alternate
pathname for the merge file. Otherwise,
the DSEE facility catalogues the merge file
in the working directory under
the name of the element (as with
the reserve command). The -r
option overwrites the existing contents
of pathname_3.
-serial Changes the display to serial, rather
than columnar format.
-width nn Changes the width of the display to
"nn" characters.
-tiny Displays the text in a small font.
-qa Instructs DSEE to ask you to verify all
its automatic decisions.
-nq Merges without asking you to resolve
conflicts.
-no_text Records merger in database without
creating a merge file.