Integrating Araxis Merge & ClearCase
Update: If you just want a solution, the scripts for 3-way merging from within ClearCase are here. It seems some people are too hasty and seriously overlook the fact that it’s there in section 4. (see the first comment for instance)
Here’s the deal:
Araxis is nice, ClearCase is nice, let’s double the niceness.
There’s some info on how to use Araxis Merge with ClearCase: [1] for comparing files. Nothing about merging in ClearCase, though… (Update: this very page is linked there, so the last sentence is not true anymore)
1. Wrapper
ClearCase has type managers defined here:
ClearCase-dir\lib\mgrs\map
See [2], there’s also a description of a less blunt way of using type managers. The contents of the map file are straightforward:
each line is:
type-manager clearcase-action called-application
eg.
text_file_delta xcompare ..\..\bin\cleardiffmrg.exe
text_file_delta xmerge ..\..\bin\cleardiffmrg.exe
calls cleardiffmrg.exe to do a visual merge/visual compare of a file of text_file_delta type. That’s the lines we’ll want to hack…
It would be handy to use perl to play around with different parameters, rather than parse them in c++. Since ClearCase seems to expect an exe file, we need to craft some exe wrapper. Here’s the VC++ source: wrapper.cpp it just calls the merge.pl script with the parameters that it got, and returns the value it gets from merge.pl script. Simple. (never thought that argv strips the quotes from quoted parameters…). Now we replace ..\..\bin\cleardiffmrg.exe with the path to wrapper.exe that we just crafted.
2. Basic script
I made the first version of script quite neutral:
`echo cleardiffmrg.exe @ARGV >> some_log_of_mine`
exit system("cleardiffmrg.exe @ARGV");
just to see what happens under the hood. The script isn’t so neutral BTW (never thought that argv strips the quotes from quoted parameters…)
3. And this happens under the hood:
Assuming we are merging a file called file :-)
in dynamic view* clearcase calls cleardiffmrg with these arguments**:
-base common-ancestor-version -out file.merge source-version file
when the merge is successful, cleardiffmrg creates the file.merge.
cleardiffmrg returns to clearcase.
The dialog that appears (saying that that the merge was successful or not) depends on the return value from cleardiffmrg. The merge arrows are drawn depending on the existence of the file.merge.
* snapshot view has basically the same set of arguments, but the arguments not available in the view, are paths in the vob database. since this is not quite readable, the -fname arguments provide the titles of the panes in merge window. This -fname thingy is not limited to only snapshot views, which makes it quite handy, one can for example do a diff between two views, and explicitly put proper information in the window pane titles like this:
cleartool diff -graph -options "-fname bla1 -fname bla2" file-in-view1 file-in-view2
** if file.merge exists, it uses file.merge.1, file.merge.2 and so on. Actually it is not important as long as the file is passed as a parameter.
4. Less basic script
Now that we know the parameters, we can call Araxis compare.exe. The script and wrapper are here, together with a setup script for XP. NOTE: If you happen to use the scripts and something breaks, that’s because you shouldn’t have used it in the first place ;-). Actually nobody has been complaining yet, and it’s got already almost 1500 downloads. So it seems fairly safe…
5. Reality check - ongoing
For now, reality sucks. I must be able to force the user to merge to the right version, and force him to resolve all the differences, before closing, and . Forget it, I have been too conditioned by using the ClearCase merge. That subsided quickly :-)compare.exe doesn’t do that. Maybe this could be solved playing with compare.exe examples, but I don’t have much time on my hands, and I am not even able to convert the sample vc++ 7 project to vc++ 6.
Update 2007-11-06: As Jamil Taylor mentioned, CC 7 has a misbehaving perl version. As a result, the checks I made for contents of $! were failing. $! was set to “Bad file descriptor” despite `reg …` being successful. So I made a cleaner version of the install script which now uses Win32::TieRegistry instead. The merge script itself hasn’t changed. Old version here.
Update 2007-2-22: There’s an Araxis Merge 2007 preview, which uses a different registry key. I added it to the setup script.
Update: People are complaining that things don’t work after installing the merge script. The script sets a system variable. So don’t expect that you will be able to install it when in merge manager/version tree/etc., as they were started in the old context, so no variable was set at the time.
[1] http://www.araxis.com/merge/scm_integration.html
[2] http://www.guiffy.com/GuiffyHelp/ClearCase.html
Based on the information on this page and the SCM integration page on Araxis.com, I’ve put together a simple application that will perform this integration seamlessly.
More information can be found at: http:/blog.genotrance.com/applications/clearaxis/
Thanks for your work as Clearaxis is based on it.
OK, frankly as I have seen your comment, I thought that you wrote a merge script, which kind of ticked me off, as then it would be violating my blog’s and my script’s (CC)-by-sa license (you have seen a link to the script in section 4., which comes with install/uninstall script didn’t you?). But as you are just doing compare, (that was on Araxis pages), and not a 3-way merge, which my script does, I’m fine with it.
But, as I am the first to have put a 3-way merge Araxis/Clearcase integration script online, if you add a 3-way merge to your script, I’d ask you for attribution (and a same type license, as that’s what Creative Commons sa is about)
Thanks for the script, Mikolaj. I had to tweak it a bit to get it to function correctly for ClearCase 7. The install script did not work correctly (the results of the reg command was not being interpreted). I also removed the /merge parameter from the parameters passed to compare.exe, which I may add back later after time… ccperl is a bit funky with Perl scripts, but my tweaked version works perfectly with Perl 5.8 822. This may have been why you had issues with getting if (-e “$options{’out’}”) to work. It works fine with Active Perl 5.8. Instead of using the wrapper.exe, I use Perl2Exe to allow ClearCase to execute it from the map file.
It works wonderfully now :-)
Glad you liked it! Looking at the server logs, people like it, they just don’t like to comment :-)
I have yet to upgrade to CC 7, but when it happens, I’ll definitely play around with the script.
The reason I didn’t use perl2exe was that it’s easier to experiment with a wrapper. For the last two years things just worked, so experimenting wasn’t really necessary.
My software project is considering using Araxis Merge in place of ClearCase’s default merge utility. The project involves two separate streams each with their own snapshot views. In one stream (stream A) files have been moved to different locations within the stream’s view (view A) without modifying their content. In the other stream (stream B) the files’ content has been modified but their location remains the same.
If our project used the merge utility included with ClearCase, when merging stream B to stream A, the merge utility would be aware of the new location in stream A for files common to both streams. It would merge modified files from stream B to their correct location in stream A.
My question is if we use Araxis Merge, will this same behavior occur? We don’t want to end up with duplicate files, where one file contains updated content at an old location for a file and the location where the file should have ended up being merged to contains old content.
I hope this is clear and that someone can clarify their experience in this matter.
Well, I am working on base cc, so cannot give you a definite answer. But I frankly doubt that the merge tool itself gets or uses “stream knowledge”. From what it looks like, cc is taking care of the whole “merge infrastructure”, ie. it decides which files & versions are being merged. The actual merge program is simply taking the input file versions, spits out the merged file, then the ball is again on cc side. It would be a strange design decision if it also contained additional logic. Well, you could just log the parameters that it’s getting for a while to see if anything like that happens.
Thanks for your prompt reply Mikolaj.
Does ClearCase ever pass entire folder versions to Merge, or does it always pass files?
Short: No, it tackles every dir and/or file separately.
Long: I too, was tempted to use araxis for directory merges instead of clearcase. Actually the merging of directories is handled by cleardiffmrg.exe, so it looked doable. But cleardiffmrg does some magic when merging dirs. Whereas for files you just get the actual versions as input, what’s happening with dirs is that clearcase creates temporary files in a special format and does comparisons of these files. Think about it - it needs to compare not only the names, but also the oids of the files (so that it handles cases like “a.c has been renamed to b.c, but these are still versions of the same file” or “the two c.h files are evil twins”). A lot of playing around would be needed to handle such cases correctly.