Advanced 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.
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:
ecmerge.exe --mode=diff2 *FILE1*
*FILE2* --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 (Customize /
Preferences... 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
Document / 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.
toolbar
icon).
:
button.