RADE |
Source Code Manager |
The Graphic MergerUser interface description |
| Quick Reference | ||
AbstractThe graphic Merger is a tool used for solving merges on file contents. This article helps to understand its interface and how to use it.
|
The Merger manages at least four files as parameters:
Information about these files are given by the adl_solve_merge command when launching the graphic tool. Here is an example showing four parts corresponding respectively to the common ancestor, the current version, the conflicting version and a previous file:
--------------------------------------------------------------- VisualStudio\CATVBTDevMkmk.m\src\CATVBTCMkmkAddin.cpp: Change of content Common ancestor: 0 - Type: Text file, created the Fri Mar 10 11:44:37 2000 Created by "gde" into the workspace "XAA_gde" the Fri Mar 10 11:44:37 2000. Changes to merge: 1 - Type: Text file, created the Tue Apr 25 13:11:51 2000 Seen as the current one in the workspace. Created by "bsfr" into the workspace "MergeToolsSDF" the Tue Apr 25 13:11:51 2000. 2 - Type: Text file, created the Tue May 23 18:08:42 2000 Created by "lfh" into the workspace "XAACXR4_lfh" the Tue May 23 18:08:42 2000 Previous change(s) of both the conflicting change (2) and the current change (1): P1 - Created by feb with adl_ci on Wed Feb 26, 2003 10:57:07 AM in the workspace Ws1T0Fe b, tree T0Feb. |
<- common ancestor <- current version <- conflicting version <- common previous |
When it is possible, SCM extracts a particular file called
previous file. This file is a common previous change of the two changes to
merge, and is nearest than the common ancestor in the graph of modifications.
In some cases, the common ancestor can be the nearest common previous.
In the example below :
- 1.WSV5R10 is the common ancestor,
- 3.WSV5R10 and 3.WSV5R11 are the two versions to merge
(notice that 3.WSV5R11 is already the result of a former merge)
- and 2.WSV5R10 is the previous version (this file is
particular and computed by SCM)
[Top]
When the merger is launched, all the merging modes are computed even if the user always choose the same mode. It allows to know how many differences are to be solve in each mode.
By default, a panel is shown to let the user make his choice.
All merge modes stay available and can be accessed by opening this panel from
the menu or the toolbar(
).
The user can choose the most appropriated mode. He can either:
- Integrate conflicting version in the current version.
Changes made between the conflicting version and the previous version are highlighted and can be integrated in the current version.
- Integrate current version in the conflicting version.
Changes made between the current version and the previous version are highlighted and can be integrated in the conflicting version.
- merge with recommendations.
This mode is based on an ancestor version which is common to the two conflicting versions.
The differences coming from each version are highlighted according to the content present in the common ancestor.- merge with a simple diff2 comparison.
This mode shows the basic differences between the current version and the conflicting one.
A line at the bottom of this panel reminds the selected options for
differences compute. If one of these options does not match what the user wants,
he can easily change it by clicking on the settings button (
)
at the end of the line. If one of these options is changed, the differences
compute is update.
It depends on the evolution of the content of the file.
The two modes by integration should be the best modes when there are many
reports because it only shows the changes that had been made in one of the
versions since the last report.
The mode with recommendations can be very effective because it allows to solve automatically changes that are not conflicting. Nevertheless, when the common ancestor is far from the two conflicting versions (in the case of a change import, for instance) the number of differences grows, so that the merge becomes very complex. In this case, the mode by integrating the current version in the conflicting version or the mode by integrating the conflicting version in the current version are more suitable.
The diff2 mode can be high-return in the case where the two files are very near in term of content, but have live a long time without synchronization, or intermediate reports (for example, in case of the check-out of the two files and a manual report between the two files - instead of a report by adl_import).
Remember that no mode is the best. Look at the number of differences and choose the easier way to solve the merge. In all cases, several modes can be opened at the same time. But, only one result will be taken in count at the end of the merge.
[Top]
The aim of this example is to show the main difference between the mode by integration and the mode with recommendations.
The example simulates a real development process with two different release levels and modifications made in each level at the same time. The actions are made in the order of the numbers staying in the headers.
| V5R11 | V5R12 |
| 1. Starting file (created in V5R11)
|
|
|
2. Modifications number 1 made in V5R11
|
3. Modification made in V5R12
|
|
5. Modification number 2 made in V5R11
|
4. Import V5R11 to V5R12 => Merge to solve
After the merge the file is the following :
|
| 6. Import V5R11 to V5R12 => Merge to solve
Several modes of resolution are available in the
|
|
| With the mode with recommendations, there are two
differences to solve. As the common ancestor is still the starting file,
the user has to make choices on all the differences that had appeared
since the common ancestor, although he had already make choices in his
previous merges.
|
|
| With the mode "Integrate the conflicting version in the
current version", there is only one difference to solve. In this mode, the user has just to make choices on the modifications that had appeared since the last previous version (here file number 2).
|
|
|
In this case, the difference between the two mode is very little, but
it can be very important. The advantage of the mode by integration is that it reduces the scope of differences to treat.
|
|
[Top]
The tool is composed of a main frame containing
Each window (one window per mode) is split in three frames, called editors, whose contents depend on the current merging mode. In all cases, only one editor out of the three displays the result of the merge and is editable (its background has a different color according to the settings). The version of each editor is mentioned in the header of the column. When the cursor stays a while on the cell, a tool tip appears to give more information about the version of this editor.
The icons of the toolbar and of the menus are active or not, depending on the current merging mode, the active difference and the context of the cursor.
The differences between versions are highlighted using different colors. Each editor has his own color (visible in the header of each column). In the result version, the colors reflect the action made. In the example below, we can see that for the first difference, the user has chosen to take the content of the left editor, and for the second, the content of the right editor.
When a difference is selected, the colors of each editor change according to the settings to highlight the active difference from the others.
A special mark ( 
or 
or 
)
is drawn in the margin of each difference to indicate whether the merge is
solved or not.
means that
the content which is in the result editor has been validated by the user and is
solved,
means, that
the difference is solved in all editors except the result editor,
means the
differences has not been resolved yet.
When scrolling vertically in one editor, the two others editors follow the move so that all corresponding parts are seen together at the same time. This co-relation is brought to the fore by a colored polygon (the color is set according to the user settings).
For specific purposes, the automatic link between the editors can be disabled
by clicking on the button 
present in the upper right corner of the editor.
Using this feature, when another editor will scroll, this one will not move any
more and when this editor scrolls, the other will not move.
, means that the editor
is linked with the others : when the other editors scroll, this one will scroll
too.
, means that the
editor is not linked with the others : when the other editors scroll, this one
will scroll too.
When lines in the editors are very long, the user can change the size of one of the editors by dragging the divider bar between two editors.
The status of the merge is indicated at the bottom of the main frame. The
user can find the following information :
- the index of the current difference => here, 1
- the total number of differences found by the merger and which are to solve at
the beginning of the merge (3),
- and the number of difference left to solve (2).
The title of each window reminds the mode opened :
and indicates by a traffic light either if there are still differences to solve 
,
or if all the differences have been solved and the result can be saved 
.
A contextual menu, accessible by the right click allows to act directly on the differences. The set of proposed actions depends on the mode of the current window.
| In the mode with recommendations and diff2 | In the modes by integration |
 |
 |
The first set of commands is used in the mode with recommendations and in the
diff2 mode.
The second set of commands is used in the integration modes .
The last set of commands is the usual Copy-Paste tools. When the editor is in
read only mode, the cut, paste and clear options cannot be used.
The user can insert text anywhere in the result file, directly or by the
copy-paste mechanism:
- Each text insertion automatically leads to the validation
of the difference.
- The inserted text is highlighted to show that a manual
insertion has been done.
The copy - paste can be used to report text from one editor to the result
editor.
A specific menu allows to select the whole content of the area.
(the part selected in blue in the example above)
Information about the type of change in the version is accessible with a tool tip, when the cursor stays a while on a difference block.
[Top]
Text differences inside a block of text are highlight according to the
difference highlighter selector (
).
It allows to highlight differences between :
- left and middle editors,
- left and right editors,
- middle and right editors,
- no difference highlight.
The algorithm used to compute character differences between two blocks is the same that the one used for the lines, but with a character precision. This functionality is very interesting to quickly see which characters have changed between two similar conflicting lines.
Limitation : when one of the two blocks of text to compare is too large (more than 5000 characters), for performances reasons, the highlight is reduced at a block starting at the first different character compute from the beginning of the text, to the first different character compute from the end of the text.
The highlighter selector position ()
is saved in the settings for each merging mode.
By default :
- the two modes "integrate ..." show differences between left and
middle editors (
),
- the "merge with recommendations" mode shows differences between left
and right editors (
),
- the "diff2" mode shows differences between left and right editors ().
It is also possible to select not to highlight differences with the following
choice (
).
In the example below, you can see that the difference between left and right editors is the string " [/p6]".
[Top]
The merger provides a language parsing functionality to help the user to locate himself in the file structure.
Four languages are recognized :
- C/C++ language for files with .h, .c, .cpp extensions,
- java language for files with .java extension,
- shell language for files with .sh extension,
- sql language for files with .sql extension.
Files with other extensions are not treated.
example:
All the editors implement an undo/Redo mechanism. Using 
or
will work but
only for text insertion made manually.
After an action like Left, Right,..., integrate Before,..., the undo/redo memory
is cleared.
[Top]
A set of arrows, present in the toolbar and in the menus allows to move from a difference to another.
Next difference (
)
and previous difference (
)
allows to move the editors to the next and to the previous difference ignoring
if they are already solved. If the cursor stands either in a common part or on a
difference, the next difference command will activate the next difference
compute from this point.
Next unresolved difference (
)
and previous unresolved difference (
)
act in the same way but allow only to move between unresolved differences.
When using the center on the current difference command (
)
, the merger updates the three editors so that each one centers on the current
difference. If no difference is selected (for example when clicking on a common
part) the editors centers on the first unresolved difference found starting from
the beginning of the document.
When moving through differences with the arrow buttons or by
clicking on a particular area, the merger always try to make the difference be
visible in the three editors:
- if the difference is not visible before action, the editors scroll so that the
beginning of the difference stands at a quarter of the screen.
- if the difference is visible, the editor does not scroll.
[Top]
Remember that there is always an editor out of the three which stands for the reference. This reference is the last editor where the user has clicked. If no editor has been focused (at the beginning of the application for example) the result editor stands for the reference editor.
Why a reference editor ?
When clicking on a difference in a editor ( this one becomes the reference), the merger arranges the two other editors to put the difference in the three editors on the same line even if the difference was visible in the other editors.
As an example, when the user clicks on the difference in the middle editor,
the areas in the left and in the right editor scroll to stay on the same line.
Remark : if the difference in the reference editor is partially seen (you can't see the first lines of this difference), the other differences are aligned to the quarter of the screen (this point is materialized by a light blue segment in the dividers).
When scrolling, the merger acts in the same way : it always tries to make the three editors contents match. The reference editor is determined by the scrollbar which is moved.
Example : when scrolling the middle editor, the merger determines which difference is visible on the quarter of the screen.
then the other editors are scrolled to maintain the same part and the same ratio (a) in all editors.
[Top]
In this mode, the user can integrate in his version (the current version seen in his workspace) the differences that had appeared in the conflicting version since the last previous version.
The previous version is computed by SCM to be the nearest last predecessor of the two files.
The left, middle and right editors contain respectively the previous version, the conflicting version and the result (which is initialized with the current version).
The current version stands for the result. A simple diff2 comparison is made between the previous version and the conflicting version so that the user knows what changes has been made by the other developer.
There are three kinds of difference that can be shown between the previous version and the conflicting version : text addition, text removal, or text change.
The aim is to integrate or not this change in the current version.
Solving a merge in this mode:
The user has four possible actions which are enabled depending on the context :
example of proposed choices :
The first possibility is "integrate before":
This choice means that the content of the conflicting version
(in the example, the green area) will be inserted before the corresponding part
in the result.
The result part take the green color as background to show
that the green part has been inserted before the yellow part. When the user
checks the differences he has solved, he can easily know what action has been
made.
Notice that this choice is not available if the part in the
conflicting version or in the result version is empty (because it makes no sense
to integrate with nothing).
The second possibility is "integrate after":
This choice means that the content of the conflicting version
(in the example, the green area) will be inserted after the corresponding part
in the result.
The result part take the yellow color as background to show
that the yellow part stay before the green part.
When the user checks the differences he has solved, he can
easily know what action has been made.
Notice that this choice is not available if the part in the
conflicting version or in the result version is empty (because it makes no sense
to integrate with nothing).
The third possibility is particular to the context of the difference.
The choices can be :
- "replace with... " followed by the type of
the change between the previous version and the conflicting version (removal,
addition, change).
This choice is only proposed when the
relation between the conflicting part and the result part is one to one, that
means a part can replace another.
If the relation is n to n, this
choice is disabled.
in the example, the change between
the previous version and the conflicting version is an addition.
Choosing, "replace with the
addition" means that we take the content of the conflicting version for the
result.
- "integrate..." as the same behavior the "replace with" but is used when the part is the result version is empty.
- "remove..." as the same behavior
the "replace with" but is used when the part is the conflicting
version is empty.
The fourth possibility is "Validate result's editor content":
This choice means that we don't want to integrate the change and
so, we keep the content that is seen in the result editor.
The result part stays with the yellow color as background to
show that the content of the editor comes from this editor.
When the user checks the differences he has solved, he can
easily know what action has been made.
Note:
- when the user inserts or remove one character manually, the result is
automatically validated.
This functionality avoids to validate each part where the
user has made a change manually.
- at any time, the user can choose to cancel the action he made with the Reset
button or menu item 
.
The area in the result version is cleared and reinitialized
to be like at the start of the application.
- a specific menu allows to select the whole content of the area.
Warning:
One important particularity of the mode "Integrate conflicting version in
current version" is that more information are shown in the dividers.
You can see on the example below that the polygon that makes the link between
the editors are drawn in the divider but also in the middle editor. This
is particular to this mode where one difference can be linked with several in
the other editors.
Example 1:
The left divider materialize the differences computed by a simple diff2
comparison between the previous version and the conflicting version.
The right divider materialize the differences computed by a simple diff2
comparison between the conflicting version and the current version (the result).
In the example above, the left divider indicates that between the previous
version and the conflicting version, a block of text has been added between
lines 1325 and 1326 (see the black link in the divider).
This bloc appears in the conflicting version (lines 1326 to 1332).
But as you can remark, just three lines are different between conflicting version and the current version, so that's why only lines 1329 to 1331 are in the green block. The merger has simplified the field of the merge to perform, because there is no point in seeing differences that have already been included in the result.
Example 2:
In the example 2, you can see that lines 1326 to 1328 of the previous version
have been changed to lines 1337 to 1345 in the current version (see the black
link in the divider).
The merger has simplified the merge and only shows the least number of
differences between the current version and the result (conflicting version). So
there is two differences to solve but each of them is much easier.
When the user solves the first difference, the part in the previous version is not solved because it is still linked with an unsolved difference. (see below)
When the user solves the other difference, the part in the previous version is mark as solved because all the differences with which it is linked are solved. (see below)
[Top]
In this mode, the user can integrate in the conflicting version the differences he has made in the current version (the current version seen in his workspace) since the last previous version.
The previous version is compute by SCM to be the nearest last predecessor of the two files.
The left, middle and right editors contain respectively the previous version, the current version and the result (which is initialized with the conflicting version).
The conflicting version stands for the result. A simple diff2 comparison is made between the previous version and the current version so that the user knows what he has made and so, what he must integrate in the conflicting version.
The behavior of this mode is the same as "integrate conflicting conflicting version in current version".
[Top]
This mode is based on a three-way comparison between the two conflicting files and their common ancestor. This mode allows to see what has changed between the common ancestor and the two conflicting versions.
The left editor contains the current version seen in the current workspace.
The right editor contains the conflicting version.
The middle editor stands for the result file which is already initialized at the
opening :
- the parts which are common to both current version and
conflicting version (i-e same text in current version and conflicting version)
are copied as it.
- the parts where a choice must be made is filled with the
content of the common ancestor. It depends on your choice in the settings.
The fact that the result file can be initialized with the content of the common ancestor allows to guess what changes have been made in each version in relation to the ancestor.
To help the user, the merger displays a tool tip text (when staying a while on a difference) to show what has happened between the common ancestor and one of the version.
Solving a merge in this mode:
|
- use classic copy/paste/edit mechanism to create the content he wants to see in the result. Note:
|
 |
When the user has made his choice the part in the result file automatically takes the colors of the editor from which it comes from, so that when the user checks all the differences he has solved, he can quickly know the action he made.
The recommendations allows to save time for non conflicting differences. How does recommendations work :
When the merger is launched, it computes the 3 files (the common ancestor,
the current version and the conflicting version) to get two sets of differences
and compare them.
The first set of differences is computed by comparing the common ancestor and
the current version.
The second set of differences is computed by comparing the common ancestor and
the conflicting version.
If all the differences computed are not in conflict, the merge can be solve
automatically.
Here are main cases with the recommendation computed:.
| Ancestor | Current Version | Conflicting Version | Result | Recommendation |
|---|---|---|---|---|
| a block of lines | same block | same block | no change: same block | YES |
| a block of lines | same block | some lines modified | conflicting version is chosen | YES |
| a block of lines | same block | lines deleted | conflicting version is chosen | YES |
| a block of lines | some lines modified | some lines modified | a manual merge is needed | NO (*) |
| nothing | nothing | some lines added | conflicting version is chosen | YES |
| nothing | some lines added | some lines added | a manual merge is needed | NO (*) |
| a block of lines | some lines modified | lines deleted | a manual merge is needed | NO |
| a block of lines | lines deleted | lines deleted | lines are deleted in the result file | YES |
Note (*): there can be a recommendation if the lines added or modified are the same in the two files.
Remember:
- the result is in the middle editor.
- a great care must be taken with the recommendations, because the same text
insertion in the two files but at two different places could be taken in account
and lead to a program bug.
Example 1:
In this example, a text has been added in the conflicting version. The user
choose to take in count this addition and use the "Right" action.
The content of the right editor is put in the corresponding area in the
result editor as follows :
[Top]
This mode simply makes a two-ways comparison between the current version and the conflicting version. The way to solve the merge is the same as in the mode with recommendations but without the recommendations.
The left, middle and right editors contain respectively the current version, the result version and the conflicting version.
As there is no more common ancestor, the result file is initialized with only the common parts computed from the current version and the conflicting version. A line stands to indicate where the text contents will be inserted. As in the mode with recommendations, the set of possible actions is Left, Right, Middle, Left + Right, Right + Left, and reset to cancel a action made.
Remember:
- the result is in the middle editor.
- the recommendation item is never enabled.
[Top]
A settings panel allows to customize some parameters. All the settings are saved on disk, so that the user can always use the merger with his preferred settings.
The user can choose :
- how to compute differences. The user can choose to ignore whites spaces or
tabulation when the merger is computing differences. This functionality is
useful when the differences between two files mainly consist in white spaces or
tabulations. It allows to focus on real content changes.
Note:
- changing this setting implies to close all opened modes to let the merger
compute again all the differences in all the modes. So when changing this
setting, the merger automatically tries to close the opened windows. Since one
window is still opened, for example if the user cancel a window closing, the
merger does not accept to take the choice into account.
- at the next launch of the merger, this choice will still be available.
These choices are displayed in the panel "Open a resolution mode" to remind with which options, the merger has computed the differences.
- View menu allows to set:
- if you want to show the syntax of the document (see Language
Parsing)
- if you want to see line numbers in the editor margin,
- if the content of the common ancestor should be seen in the
unresolved parts of the result
- which external tool should be used as text editor to edit
the files,
- the size he wants for the tabulations (this choice will
only be available at the next document opening).
- the color menu allows to redefine the main colors of the application.
Remember:
- when the user choose to ignore white spaces or tabulations, the reference
editor take for the initialization of the common parts is the current version
seen in workspace.
- the changes made in the settings are available as soon as the settings panel
is closed, and at the next launch of the merger. So if you choose to ignore
white spaces or tabulations, remember that this choice will be available in the
next launch of the tool.
[Top]
|
Item
|
Icon
|
Purpose
|
| Open a resolution mode | |
Displays a panel where the user can choose the resolution modes he wants to open. |
| Save and quit |  |
Save the content of the current opened merge mode as the result of the merge (all differences must be solved) |
| Quit | No Icon | Quit the application. |
[Top]
|
Item
|
Icon
|
Purpose
|
| Undo | |
Undo the last text action in the result editor. |
| Redo | |
Redo the last text action in the result editor. |
| Cut |  |
Cut the actual selection to the clipboard. |
| Copy |  |
Copy the actual selection to the clipboard. |
| Paste |  |
Paste the content of the clipboard to the location of the cursor. |
| Clear |  |
Clear the actual selection. |
| Find |  |
Find a string in the active editor |
| Replace | No Icon | Find and replace a string in the active editor |
| Go to line | No Icon | Move the cursor to a specific line |
| Settings | |
Open the settings panel. |
[Top]
|
Item
|
Icon
|
Purpose
|
| Go To | Open a submenu to shift between differences. The items of this menu are described below. | |
| Previous difference | |
Scroll the three editors to make visible the previous merge (solved or not). |
| Next difference | |
Scroll the three editors to make visible the next merge (solved or not). |
| Center on current difference | |
Center the three editors on the current difference. |
| Previous unresolved difference | |
Scroll the three editors to make visible the previous unresolved merge. |
| Next unresolved difference | |
Scroll the three editors to make visible the next unresolved merge. |
| Open a file with the external tool | No icon | Open the selected file in the external text editor specified in the settings. |
|
Item
|
Icon
|
Purpose
|
| Open a file with the external tool | No icon | Open the selected file in the external text editor specified in the settings. |
[Top]
|
Item
|
Icon |
Purpose
|
| Left |
|
Selection of the left part, which means, selection of the text from the current version |
| Right |  |
Selection of the right part, which means, selection of the text from the conflicting version |
| Left + Right |  |
Selection of the left part, AND the right part, which means, selection of the text from the current version AND the text from the conflicting version |
| Right + Left |
|
Selection of the right part, AND the left part, which means, selection of the text from the conflicting version AND the text from the current version |
| Validate result's editor contents | |
Validate the result's editor content, which means, selection of the text from the result version which could have been changed manually by the user |
| Reset |
|
The reset puts back the difference in the result editor as it was before the selection. In the mode with recommendations, if the option is selected, the result editor redisplays the text that was in the common ancestor. |
| Recommendation |
|
Selection of the recommendation found by the merger |
|
Item
|
Icon |
Purpose
|
| Integrate before |
|
Selection of integrating the change which has been made between the previous file and the version present in the middle editor before the content present in the result editor. |
| Integrate after |
|
Selection of integrating the change which has been made between the previous file and the version present in the middle editor after the content present in the result editor. |
| Integrate... |
|
Integrates the change in the result editor (see the details in integrate chapter). |
| Validate result's editor contents | |
Validate the result's editor content, which means, selection of the text from the result version which can have been change manually by the user |
| Reset |
|
The reset puts back the difference in the result editor as it was before the selection. |
[Top]
The commands are the same as the select commands but apply to the whole set of differences (other than those already solved). They are only accessible in the menu Select All.
[Top]
Each time a resolution mode is opened, it is linked to this window menu. This is a better way to navigate between opened modes.
[Top]
|
Item
|
Icon
|
Purpose
|
| The graphical Merger |  |
Opens this documentation in the default web navigator. |
| Solving merges | |
Opens the official documentation about how to solve a merge in the default web navigator. |
[Top]
The main items of the menu are accessible through the icon bar, where you can
find :
- the opening of the merge modes,
- the opening of the settings panel
- the selection actions buttons (indicating whether they are accessible or not),
(treat only one difference)
- the move action buttons to move from a difference to another,
- a difference selector, to highlight differences between two particular
editors.
These icons are enabled when they can be used and disabled in the other cases.
When all the differences have been solved in one merging mode, the user can
choose to save the result and quit the graphical merger.
If several merging mode have been opened, the merger reminds the user that other
modes are opened to avoid from loosing its work. Indeed, when the merge is not
easy to solve in one mode, the user can open another mode which can be easier to
solve. Even if the user has opened all the possible mode and starting to make
choices in each mode, the result will come out from one mode only.
[Top]
The merger can be launch manually by the user out of the 'adl_solve_merge' SCM command.
'ADL_MERGER' current_file conflicting_file [-anc
ancestor_file] [-prev previous_files...] -out result_file
{-batch -begcom begin_comment -endcom end_comment} {-info
info_file }
'ADL_MERGER' stands for the environment variable ADL_MERGER : type $ADL_MERGER on unix systems, or %ADL_MERGER% on windows systems.
| -h|-help|-? | Help of the command |
| current_version | Current version to merge |
| conflicting_version | Conflicting version to merge |
| -anc ancestor_version | Common ancestor version |
| -prev previous_version... | Previous common version |
| -out result_file | File to contain the result of the merge |
| -batch | Option used to solve the merge in batch mode |
| -begcom begin_comment | comment put at the beginning of a conflicting unresolved part |
| -endcom end_comment | comment put at the end of a conflicting unresolved part |
| -info info_file | File containing information about the different files (extract by SCM) |
The merger will be able to compute several modes depending on the given arguments. Some of these options are mandatory and others optional.
With only the two mandatory files (current_version and conflicting_version), the merger will only propose the diff2 merging mode.
'ADL_MERGER' current_file conflicting_file -out result_file
Giving an common ancestor version, the merger will be able to propose the four following modes :
'ADL_MERGER' current_file conflicting_file -anc ancestor_version -out result_file
Integrate conflicting version in current version, compute with the common ancestor version as previous version (the common ancestor is a particular previous version)
Integrate conflicting version in current version, compute with the common ancestor version as previous version,
Merge with recommendations, which need the common ancestor version,
Simple diff2 mode.
Giving a previous version, the merger will be able to propose the three following modes :
'ADL_MERGER' current_file conflicting_file -prev previous_version -out result_file
Integrate conflicting version in current version, compute with the previous version
Integrate conflicting version in current version, compute with the previous version,
Simple diff2 mode.
Giving an ancestor version and a previous version, the merger will be able to propose the four following modes :
'ADL_MERGER' current_file conflicting_file -anc ancestor_version -prev previous_version -out result_file
Integrate conflicting version in current version, compute with the previous version
Integrate conflicting version in current version, compute with the previous version,
Merge with recommendations, which need the common ancestor version,
Simple diff2 mode.
The batch mode is only available if a common ancestor version is given, because it uses the merge with recommendations mode.
It uses the recommendations to solve automatically the non conflicting differences:
when the merger meets a non conflicting change, it solves it using the recommendations,
when the merger meets a conflicting change, it take the content of the current version followed by the content of the conflicting version surrounded by the begin comment and the end comment given on the command line
Example:
 |
||
 |
 |
Without the batch mode, the user would have had to solve this merge :
With the -batch option, the merge automatically produces this result file:
'ADL_MERGER' -anc ancestor.txt currentversion.txt conflictingversion.txt -out result_file -batch -begcom "My_Begin_Comment" -endcom "My_End_Comment"
You can see the non conflicting changes (lines 2 and 4) have
been solved.
For the conflicting part, the content of the current part has been keep, and the
content of the conflicting part has been inserted with the user begin and end
comment.
Note that the merger systematically adds its own begin and end comment (you can see "---- Beginning of conflicting part." and "---- End of conflicting part.").
In this case the merger produces an error return code to indicate to the user that he must solve manually the conflicting parts left in the result file.
Top]
The merger tool that is described in the current article is completely
different from the one existing until now.
The purpose of this new merger is to provide user more flexibility and easiness
to solve merges.
Here are some main differences:
| Old Merger | New Merger |
| A single way of merging files, based on a common ancestor version from which the two conflicting versions have derived, then displaying the differences between each file and this common version and letting the user to decide which one to keep for the result. | Four ways of computing differences and merging
files:
The different modes can be opened simultaneously in different windows. |
| A single window displaying the two versions and splitting horizontally the window where are the differences. | Any of the four merging modes that are described above are available and can be used for any merge. The tool manages multiple merges that appear on the screen as different windows. Each window contains three sub-windows displaying either one of the two conflicting versions, or the result, or the previous version. |
| Impossible to see the content of the common ancestor version | In the mode with recommendations, each time a difference exists between the two conflicting versions, it is possible to display the content of the common ancestor version (by default, this option is set). |
| While solving the merge, the single window displays only what is chosen by the user as being the result of the merge. Once the merge finished, the user can see only the result file. | Each file has a dedicated window. The editors of the different versions are opened in read only mode. The result editor is opened in read write mode and can be saved by the user. It is also possible to run an external editor to see the content of any file involved in the merge (ancestor, conflicting version, previous version). |
| The window is split with different text editors | Only one editor is used for each file and colors are used to highlight the differences.. |
[Top]
[Top]
| Version: 2 [January 2004] | Document update : language parsing, text highlight, settings |
| Version: 1 [March 2003] | Document created |
| [Top] | |
Copyright © 2003, Dassault Systèmes. All rights reserved.
