Tutorial 2: fully integrate Ellié Computing Merge with my VCS and work with an opensource project

 

 

What you will learn with this tutorial

• how to set up a integration with a VCS
• how to set up a comparison view with a VCS repository
• how to get check-out working
• how to import a patch 
• how to generate a patch

Prerequisites

• You need have an installed VCS, one of those listed in SCC Source Dialog Box for repository browsing (with command line tools installed) and/or one of Integration with Configuration Management Systems to get Ellié Computing Merge called as its diff/merge tool (if your tool is not listed, you may set up this rather easily as long as your tool actually supports third party comparison tools, see your tool documentation).

Step 1: Set up the integration as differentiation tool in your VCS

Most VCS / SCM tools widely available today have parameters to let you replace the built-in differentiation tool. Why do they? because a differentiation (or comparison) and merge tool is really a big piece of software and needs important efforts to develop efficient, complete and practical features.

Have a look to this page Integration with Configuration Management Systems, if you do not find your tool there, here are some steps to help configure your VCS:

• If your tool has a Configuration or Preference dialog box, search for something related to 'Diff / Merge' tools, if you have many options screens with sections, it is probably located somewhere in the Client configuration, what you search looks like 'Use external differ' or something similar. These options are sometimes parameterable 'per file extension', so it may be located under 'File types' sections as well.
• there you will find the command lines (either as unique field or separated into the executable path and the arguments) , one for differentiation and another one for merge:
  • Differentiation command line will probably look like this:
    guimerge.exe --mode=diff2 *FILE1* *FILE2* --title1=*TITLE1* --title2=*TITLE2*
  • Merge command line:
    guimerge.exe --sip --mode=merge3 *ANCESTOR* *FILE1* *FILE2* --title0=*TITLEANCESTOR* --title1=*TITLE1* --title2=*TITLE2*
  • *FILE1* *FILE2* *ANCESTOR* are place holder for path parameters coming from your VCS tool, sometimes they look like $1 or $2, sometimes they look like $left $right $ancestor, your VCS documentation will tell
  • *TITLE1* *TITLE2* and *TITLEANCESTOR* are the title for the various roles, some VCS provide titles, some don't, in this case you can omit the --title parameters or use constant telling which version is the last checked-in, your own version and the ancestor, depending on your usage of the *FILE?* parameters.

Now that you integrated Ellié Computing Merge as the differ of your VCS tool, you will be able to profit of quality comparison and merges whenever your working interface is that tool, but that's always the case.

Step 2: Set up a comparison view with a VCS repository

As Ellié Computing Merge contains a good script-enabled editor, you may want to edit, patch or merge your files directly from Ellié Computing Merge.
If you use a version control system to historize and protect your developments, you probably want to compare your local version to the last check-in version or have the check-out commands run automatically, prompting for comments as necessary.

In order to do that you have first to verify the setup of your tool:

• Open the Application options dialog box (Edit/Options... menu item, or Preferences on the Mac, or  toolbar icon).
• Go to the Source Code Controls section, it displays the Tools screen
  • if your preferred tool is not listed at all, contact us at info@elliecomputing.com, we will evaluate the opportunity of adding this tool (we can as well explain you how to do it by yourself; it is a rather touchy process but if you are a bit 'geek' it is far from impossible).
  • if your tool is there but no path is specified, try clicking the Auto-detect button. If there is no path still for your tool, you have to enter it with the "Modify" button, some tools cannot be automatically detected.
  • NB: remember that Ellié Computing Merge needs the command line tool for your SCC, not just the interface or the MSSCCI DLL, Ellié Computing Merge uses the command line tools because their interface is portable and the tools are generally provided for more than just Windows platform

Our workspace is rather well setup, let's open a folder comparison, pressing Ctrl+M (Ctrl+Shift+M on Mac) or :

• enter a local path in Left combo box, press Enter to validate it, for example: c:\temp\myproject or /home/name/mydir
• use the SCC Source dialog box to define a URL to your repository content (click Help in that box to get a precise description of the meaning of each field)
• now simply browse in the view and double-click on the files for which you would like to see the comparison

Step 3: Set up a mapping to get check-out feature

Previous steps got you with a running comparison, but when editing Ellié Computing Merge is not yet aware of SCC control on that files. You can configure Ellié Computing Merge this way:

• Now go to the section below: Source Code Control / Mappings.
  • Here you can add as many mappings as you want, it works by associating a SCC Source path with a local path
  • Let's click New and e.g. enter: c:\temp\myproject as the local path, and vss://server/share/path;type=db/path using the VSS choice in the Source Code Control Source dialog box or anything suiting your own tool.
  • Now Ellié Computing Merge will ask the tool to check-out read-only file whenever touching them
• In the view previously open, you can now check that check-out feature works by clicking View on a text file and starting to type, the Check-out dialog box should get displayed.

Step 4: Importing a patch

In the previously open folder comparison view, we are going to import a patch. Patching is technic which use a change descriptin file (a 'patch' or a 'diff') , an interpreter parses this file and updates a source file accordingly to build a target version. Ellié Computing Merge can do this in-place (overwriting the source when everything is OK) or out of place. Independently from the location of the produced target, Ellié Computing Merge let you preview the result of the application of the patch. Let's try this:

Here is a very simple patch, updating a file called "new text file.txt" which should be empty, and patch it with the standard Hello world message:

--- C:\temp\plouf2\New text file.txt 2007-10-16 16:29:17.000 +0200
+++ C:\temp\plouf5\New text file.txt 2007-10-16 16:29:41.000 +0200
@@ -0,0 +1,1 @@
+Hello world 

• Copy the above sample text to the clipboard, show the log view by clicking the menu item View/Show-Hide log view 
• Click the menu File/Import patch to display the Import options box
• Select Left as the source side as well as for the target side
• Check "Open in a preview", and click the "Import from clipboard" button
• Have a look to the various 'smart' options, they let you apply a patch with less context than what implies the patch, with displacement (i.e. of some lines which are not immediately in the context were removed and/or inserted) and so on, click Help in the dialog box for more information
• Now let's click the Test button:
  • it will probably dump in the log view various messages from which one will look like this:
    Warning: source of patch for item c:\temp\myproject\c:\temp\plouf2\New text file.txt should be present and is not
  • this message happens because the paths in the patch are not relative to the root folder of your comparison
  • to circumvant this, in the 'Folder specific" group, increase the value of 'Number of path steps to remove from source path start:' up to 3 (there are three steps in c:\temp\plouf2: "c:", "temp" and "plouf2"), which makes the path raltvie to the comparison root
  • click the Test button again, the warning should have changed into:
    Patch for item C:\temp\myproject\New text file.txt was applied successfully
• Now click Run
• A view opens, left view is your local folder, right view is temporary folder with the patched file only. It is pre-selected so that running the merge would validate the patch.
• You can double-click the file to view the modified file
• Run the merge either select all the items with Ctrl+A or Select All menu, then right clicking on the selection and selecting Merge Result/Write or clicking the Write to result folder(s)  button.
• NB: by selecting only a sub-part of the patch, or merging selectively the changes by hand, you would be able to partially and selectively apply the patch.

Now that you applied succesfully your first patch, you will be able to take patches from Internet and apply them selectively, for example, to get only parts of a published version in a public project (this is often useful to get the bug fixes released in a new version of the project, without all the other changes for which it is often difficult to be sure that they won't make regress your own project). 

Step 5: Generating a patch

We applied a simple patch with Ellié Computing Merge, it is now time to generate a simple patch.

• In the previously setup VCS / working directory comparison, select a few files, include the 'New text file.txt' file for example.
• Now select the menu item File/Export/Export patch
• The Export options dialog box opens, with Path export pre-selected
  • Select the scope that you wish to use, probably "Selection"
  • The "context, unified" type of patch is very frequently used. Note however that if you choose to ignore various things in the input files during comparison (such as leading or trailing spaces...), it is sometimes more interesting to use "context, both sides" which well be more precise and may give better result later. Finally choosing "normal" build a legacy patch, these patches are not very good if you are not sure that the source files will not change, and are not applicable for folders usage as they do not specify the files that they modify in a "machine-parsable" way.
  • Select the "clipboard" output type
  • Press run
• Now open a new editor, and paste the patch there
• Save the file with a .patch or .diff extension, the patch syntax will automatically highlight

You are now OK to work with most open source projects for which patch application is still the way to go when exchanging, integrating changes.

We hope that you found this tutorial useful and that you learnt several features. If you think that we could improve this tutorial, please contact us at info@elliecomputing.com or create a ticket on our website.