Question & Answer
Question
How do you reconfigure the default IBM Rational ClearCase XML type manager to use a third party application to address UTF8 and other issues when using ClearCase diff merge tools?
Cause
Note: There were enhancements in ClearCase 7.1 that introduced UTF support. Refer to the What's New section of the IBM Rational ClearCase Release Notes under the topic of Unicode Transformation Format (UTF) Support for further information.
Problem #1
When two different versions of an XML file have lines inserted into the same place, attempts to diff or merge to the base contributor results in an add-add conflict. This conflict in turn causes the xmldiffmrg tool to only allow the contributors from the base to be selected. A workaround is to use the text file diff merge (see Problem #2).
Example:
Note: Options 2 and 3 do not set the changes for those contributors. Only Option 1 reflects the selected change.
Note: A similar problem occurs for delete-delete and modify-modify conflicts as well.
Problem #2
The algorithm used by xmldiffmrg is different than the text diff merge (cleardiffmrg). Currently xmldiffmrg parses one file at a time. Parsing the file builds a tree and then uses a bottom-up approach to compare the tree to look for xml differences. The xmldiffmrg does not consider two different versions of the file with lines inserted into the same place (as seen in the example above) as a difference; however the text diff tool will.
Example: Contributor 2 and 3 were selected as the result of using cleardiffmrg.
This work-around is acceptable in most cases, however, problems arise when the XML file uses UTF8 or other unicode types in the file. (See Problem #3.)
Problem #3
Using the text diff/merge tool as a workaround may solve the contributor issue, however, the text diff/merge tool does not work correctly with UTF8 character sets. So if your XML projects/files are configured to use UTF8 (or any type of Uni-Code) the text diff merge tool will not handle these files properly.
With all of these issues, how can you configure ClearCase to successfully diff and merge XML files?
Answer
Change the type manager that is managing your XML file types to use a third party XML Diff and Merge solution. KDiff3 is the XML diff/merge of choice selected in this example.
Note: For additional information about creating and modifying a type manager refer to About the Rational ClearCase Type Manager white paper.
Configuring Native ClearCase to use KDiff3
Configuring the ClearCase Remote Client (CCRC) to use KDiff3
About KDiff3 (http://KDiff3.sourceforge.net/#news)
- KDiff3 compares and merges two or three text input files or directories
- KDiff3 shows the differences line by line and character by character
- KDiff3 provides an automatic merge-facility
- KDiff3 has an editor for comfortable solving of merge-conflicts
- KDiff3 supports Unicode, UTF-8 and other file encodings
- KDiff3 handles UTF8, windows-1251, windows-1252, ISO_8859-15, and some Japanese encodings.
- Encoding auto detection for Unicode files with byte order mark "BOM" at the file start
- KDiff3 prints differences
- KDiff3 provides excellent performance results on large files.
- KDiff3 is easy to install and easy to use.
- KDiff3 runs on various platforms
- GNU/Linux with KDE3,
- Any UNIX platform that supported by the Qt-libs from Qt.Digia,
- Microsoft Windows.
- KDiff3 Version 0.9.92 introduced a ClearCase Integration install option.
Configuring Native ClearCase to use KDiff3
Note: Implement these instructions on every client that needs to diff and or merge XML files using this method.
- Download and install KDiff3 from SourceForge
(http://sourceforge.net/project/showfiles.php?group_id=58666)
- Open the Type Manager map file with a text editor.
Note: The map file is in the ccase-home-dir/lib/mgrs directory.
Windows: C:\Program Files\Rational\ClearCase\lib\mgrs
Review the ClearCase Command Reference Guide on the topic of type_manager (cleartool man type_manager) for more information.
- For any type manager that uses xmldiffmrg, replace the xmldiffmrg executable with the path to KDiff3.
What needs to be changed in the map file?
merge/compare -- CLI merge/compare
xcompare/xmerge -- GUI compare/merge
Example:
_xml2 compare ..\..\..\..\KDiff3\KDiff3.exe
_xml2 xcompare ..\..\..\..\KDiff3\KDiff3.exe
_xml2 merge ..\..\..\..\KDiff3\KDiff3.exe
_xml2 xmerge ..\..\..\..\KDiff3\KDiff3.exe
Note: The mapfile uses a relative path from its current location to find the executable. In this example, KDiff3 was installed to the default directory on Windows (C:\Program Files\KDiff3) thus the relative path defined in the map file reflects as such.
- Stop and Restart ClearCase
KDiff3 Version 0.9.92 installation
KDiff3 version 0.9.92 introduced changes in it’s installer that provides an option to turn on ClearCase integration so as to set KDiff3 as the comparison and merge tool for ClearCase.
Here are the steps to select the ClearCase integration option:
- Install Kdiff3-0.9.92
- During the installation the following options are presented.
- Select the “Integrations” component and then ClearCase
The following ClearCase-related changes will be made automatically during the install:
- A backup of the ClearCase type manager map file is created in the ClearCase installation directory (by default: C:\Program Files\Rational\ClearCase\lib\mgrs) named map.preKDiff3Install
- The following lines in the map file are modified to reference the KDiff3 tool:
text_file_delta whole_copy whole_copy z_text_file_delta z_text_file_delta z_whole_copy z_whole_copy _xml _xml _xml2 _xml2 _rftdef _rftmap _rftvp _xtools | xcompare xmerge xcompare xmerge xcompare xmerge xcompare xmerge xcompare xmerge xcompare xmerge xcompare xcompare xcompare xcompare | C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe C:\Program Files\KDiff3\kdiff3.exe |
Note: For XML merge and compare options it is only necessary to update the xml lines in the map file. If you do not want to use the KDiff3 tool for all the type managers listed above, revert to the backup copy of the map file that was previously created and modify only the _xml2 lines as noted in the previous section. Always keep a backup copy of the original map file.
The changes to the map file explained above apply to the ClearCase Native clients only. Although the ClearCase Integration option can be selected during a KDiff3 version 0.9.92 install on a CCRC client, there is no local map file to update, thus you should follow the CCRC instructions listed below.
Configuring the ClearCase Remote Client (CCRC) to use KDiff3
- Change directories to the CCRC installation location > plugins > com.ibm.rational.clearcase.compare_merge.<os>_<ccrc ver>
Where <os> is the name of the operating system bits used and <ccrc ver> is the latest version of the CCRC update applied on the client.
On Windows
CCRC 7.1 Default: C:\Program Files\IBM\IMShared\plugins
CCRC 7.0 Default: C:\Program Files\IBM\Rational\ClearCase\CCRC\plugins\
Example:
com.ibm.rational.clearcase.compare_merge.win32x86_7.0.1.CU02
- Copy the KDiff3 executable from its installation path to the com.ibm.rational.clearcase.compare_merge.<os>_<ccrc ver> directory
- Rename the ccrc_xmldiffmrg.exe to ccrc_xmldiffmrg_orig.exe
- Rename KDiff3.exe to ccrc_xmldiffmrg.exe
- Close and reopen CCRC
Note: Replacing the CCRC diffmerge utility as explained above with KDiff3 version 0.9.92 may result in a KDiff3 usage error. Refer to the known issues section below.
Known Issues
Native ClearCase Issue:
When updating ClearCase (patch, iFix, FixPack), the map file will be overwritten with every client update. As a result, a copy of this file must be maintained outside of the ClearCase directory and replaced after each update.
CCRC Issue:
- When updating CCRC, the plug-in directory com.ibm.rational.clearcase.compare_merge.<os>_<ccrc ver> will change. The steps above will need to be run again in the new plug-in directory.
Note: You can control when the updates occur by preventing CCRC from looking for updates automatically. Click Window > Preferences > Install/Update > Automatic Updates and disable automatic updates.
Once this is done, you can control when to look for, download and install CCRC updates.
Note: To obtain updates, click Help > Software Updates > Find and Install.
- Review technote 1196280 for additional alternatives.
- Using KDiff3 version 0.9.92 as a CCRC diffmerge tool may cause the following usage error during a compare operation. Dismiss this error by clicking the "Ignore" button which will allow the compare to proceed.
KDiff3-Usage
i Unknown option: -xcompare
If KDiff3 should ignore this option, run KDiff3 normally and edit
the "Command line options to ignore" in the "Integration Settings".
KDiff3-Usage when starting via commandline:
- Comparing 2 files kdiff3 file 1 file2
- Merging 2 files kdiff3 file 1 file2 -o outputfile
....
If you start without arguments, then a dialog will appear
where you can select your files via a filebrowser.
- select Settings -> Configure Kdiff3
- Move to the integration tab
- Add ";-xcompare" to the "Command-line options to ignore" box. The page should look similar to the following:
To eliminate this issue in future merges:
DISCLAIMER:
All references made to third party applications in this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
After installing and configuring KDiff3 (or 3rd party application of your choice) to work as the type manager for XML files, attempts to diff or merge XML files from native ClearCase or CCRC will result in a clean diff and merge. Results will be as expected.
KDiff3 screen capture:
Related Information
Was this topic helpful?
Document Information
Modified date:
29 September 2018
UID
swg21256807