Mergely
Mergely is a JavaScript component for differencing and merging files interactively in a browser (diff/merge), providing rich API that enables you to easily integrate Mergely into your existing web application. It is suitable for comparing text files online, for example, .txt, .html, .xml, .c, .cpp, .java, etc.
Mergely has a JavaScript implementation of the Longest Common Subsequence (LCS) diff algorithm, and a customizable markup engine.
Installation
Installation via webpack
The recommended way to install mergely and its dependencies is to use a Node package manager (npm
or yarn
) and webpack.
It is highly recommended that you start by cloning mergely-webpack. The webpack has everything that you need to get started.
Angular 6.1.1
You can also use mergely within angular. You can start by cloning mergely-angular.
Installation via .tgz
Unpack mergely.tgz into a folder, for example, ./lib
, and add the following to the <head>
of your target HTML source file.
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.32.0/codemirror.min.js"></script>
<link rel="stylesheet" media="all" href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.32.0/codemirror.css" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.32.0/addon/search/searchcursor.min.js"></script>
<script src="lib/mergely/lib/mergely.js" type="text/javascript"></script>
<link rel="stylesheet" media="all" href="lib/mergely/lib/mergely.css" />
Create a div for the editor in <body>
.
This example uses a style that provides 8px padding (mergely-full-screen-8
):
<div class="mergely-full-screen-8">
<div class="mergely-resizer">
<div id="mergely"></div>
</div>
</div>
Then initialize mergely, setting options as required.
$(document).ready(function () {
$('#mergely').mergely();
});
Synchronous content initialization
The following example can be used to set the lhs
and rhs
editors synchronously (that is, when their contents are already known):
$(document).ready(function () {
// set editor content
$('#mergely').mergely({
lhs: function(setValue) {
setValue('the quick red fox\njumped over the hairy dog');
},
rhs: function(setValue) {
setValue('the quick brown fox\njumped over the lazy dog');
}
});
});
Asynchronous initialization
If the editor contents are retrieved asynchronously (recommended), then retrieve the editor contents and set them:
$(document).ready(function () {
// initialize mergely
$('#mergely').mergely();
// get async lhsResponse, then set lhs value
$('#mergely').mergely('lhs', lhsResponse);
// get async rhsResponse, then set rhs value
$('#mergely').mergely('rhs', rhsResponse);
});
Options
Option | Type | Default value | Description |
---|---|---|---|
autoresize | boolean | true |
Enables/disables the auto-resizing of the editor. |
autoupdate | boolean | true |
Enables/disables the auto-updating of the editor when changes are made. |
bgcolor | string | #eeeeee |
The background color that mergely fills the margin canvas with. |
change_timeout | number | 500 |
The timeout, after a text change, before Mergely calculates a diff. Only used when readonly is enabled. |
cmsettings | object | {mode: 'text/plain', readOnly: false} |
CodeMirror settings (see CodeMirror) that are combined with lhs_cmsettings and rhs_cmsettings . |
editor_width | string | 400px |
Starting width. |
editor_height | string | 400px |
Starting height. |
fadein | string | fast |
A jQuery fadein value to enable the editor to fade in. Set to empty string to disable. |
fgcolor | string|number|object | {a:'#4ba3fa', c:'#a3a3a3', d:'#ff7f7f', ca:'#4b73ff', cc:'#434343', cd:'#ff4f4f'} |
The foreground color that mergely marks changes with on the canvas. The value a is additions, c changes, d deletions, and the prefix c indicates current/active change (e.g. cd current delection). |
ignorews | boolean | false |
Ignores white-space. |
ignorecase | boolean | false |
Ignores case when differientiating. |
lcs | boolean | true |
Enables/disables LCS computation for paragraphs (word-by-word changes). Disabling can give a performance gain for large documents. |
license | string | lgpl |
The choice of license to use with Mergely. Valid values are: lgpl , gpl , mpl or lgpl-separate-notice , gpl-separate-notice , mpl-separate-notice (the license requirements are met in a separate notice file). |
line_numbers | boolean | true |
Enables/disables line numbers. Enabling line numbers will toggle the visibility of the line number margins. |
lhs_cmsettings | object | {} |
The CodeMirror settings (see CodeMirror) for the left-hand side editor. |
resize_timeout | number | 500 |
The timeout, after a resize, before Mergely auto-resizes. Only used when autoresize enabled. |
rhs_cmsettings | object | {} |
The CodeMirror settings (see CodeMirror) for the right-hand side editor. |
rhs_margin | string | right |
Location for the rhs markup margin. Possible values: right, left. |
sidebar | boolean | true |
Enables/disables sidebar markers. Disabling can give a performance gain for large documents. |
vpcolor | string | rgba(0, 0, 200, 0.5) |
The margin/viewport indicator color. |
viewport | boolean | false |
Enables/disables the viewport. Enabling the viewport can give a performance gain for large documents. |
wrap_lines | boolean | false |
Enables/disables line wrapping. Enabling wrapping will wrap text to fit the editors. |
Options - Callbacks
Methods
clear
Clears the editor contents for the specified side
.
Parameters
Name | Type | Description |
---|---|---|
side | string | The editor side, either lhs or rhs . |
Example
$('#mergely').mergely('clear', 'lhs');
cm
Gets the CodeMirror editor for the specified side
.
Parameters
Name | Type | Description |
---|---|---|
side | string | The editor side, either lhs or rhs . |
Example
$('#mergely').mergely('cm', 'lhs');
diff
Calculates and returns the current .diff file.
Parameters
None.
Example
$('#mergely').mergely('diff');
get
Gets the text editor contents for the specified side
.
Parameters
Name | Type | Description |
---|---|---|
side | string | The editor side, either lhs or rhs . |
Example
$('#mergely').mergely('get', 'lhs');
lhs
Sets the value of the left-hand editor.
Parameters
Name | Type | Description |
---|---|---|
value | string | The editor text. |
Example
$('#mergely').mergely('lhs', 'This is text');
merge
Merges whole file from the specified side
to the opposite side.
Parameters
Name | Type | Description |
---|---|---|
side | string | The editor side, either lhs or rhs . |
Example
$('#mergely').mergely('merge', 'lhs');
mergeCurrentChange
Merges the current change from the specified side
to the opposite side.
Parameters
Name | Type | Description |
---|---|---|
side | string | The editor side, either lhs or rhs . |
Example
$('#mergely').mergely('mergeCurrentChange', 'lhs');
options
Sets the editor options. Will automatically update with the new settings unless autoupdate
is disabled, in which case, you will need to explicitly call update
.
Parameters
Name | Type | Description |
---|---|---|
options | object | The options to set. |
Example
$('#mergely').mergely('options', { line_numbers: true });
options
Gets the editor options.
Parameters
None.
Example
$('#mergely').mergely('options');
resize
Resizes the editor. It must be called explicitly if autoresize
is disabled.
Parameters
None.
Example
$('#mergely').mergely('resize');
rhs
Sets the value of the right-hand editor.
Parameters
Name | Type | Description |
---|---|---|
value | string | The editor text. |
Example
$('#mergely').mergely('rhs', 'This is text');
scrollTo
Scrolls the side
to line number specified by num
.
Parameters
Name | Type | Description |
---|---|---|
side | string | The editor side, either lhs or rhs . |
num | number | The line number. |
Example
$('#mergely').mergely('scrollTo', 'lhs', 100);
scrollToDiff
Scrolls to the next change specified by direction
.
Parameters
Name | Type | Description |
---|---|---|
direction | string | The direction to scroll, either prev or next . |
Example
$('#mergely').mergely('scrollToDiff', 'next');
search
Search the editor for text
, scrolling to the next available match. Repeating the call will find the next available token.
Parameters
Name | Type | Description |
---|---|---|
side | string | The editor side, either lhs or rhs . |
text | string | The text to search. |
Example
$('#mergely').mergely('search', 'lhs', 'needle');
swap
Swaps the content of the left and right editors.
Parameters
None.
Example
$('#mergely').mergely('swap');
unmarkup
Clears the editor markup.
Parameters
None.
Example
$('#mergely').mergely('unmarkup');
update
Manually updates the editor by recalculating the diff and applying new settings.
Parameters
None.
Example
$('#mergely').mergely('update');