Mergely

!mergely logo

https://mergely.com

Mergely is a JavaScript component for differencing and merging files interactively in a browser (diff/merge). It provides a rich API that enables you to easily integrate Mergely into your existing web application. It is suitable for comparing text files online, such as .txt, .html, .xml, .c, .cpp, .java, .js, etc.

Mergely has a JavaScript implementation of the Longest Common Subsequence (LCS) diff algorithm, and a customizable markup engine. It computes the diff within the browser.

This is the latest version 5. The previous version 4 can be found here.

Usage

$3

The easiest and recommended way to use Mergely is with the mergely-react component.

``bash
npm install mergely-react
`

$3

There is an Angular component for Mergely mergely-angular, but it is out of date. I will accept MR for anyone willing to do the work.

$3

The source repository mergely-webpack contains an example of how to get started with a new project that uses mergely and webpack.

`
git clone --depth 1 https://github.com/wickedest/mergely-webpack.git my-project
cd my-project
rm -rf .git
`

$3

Add the following to the of your target HTML source file. Note that codemirror is bundled.

`html


`

$3

If the editor contents are retrieved asynchronously (recommended), then retrieve the editor contents and set them:

`html





`

$3

Mergely will emit an updated event when the editor is first initialized, and each time one of the editors changes. You can listen for one event to perform one-time initialization.

`html





`

$3

Mergely does not support any CodeMirror highlighting for different languages (xml, html, javascript etc.) out of the box.
You can compile your own Mergely-Version with support for the desired modes by adding them to diff-view.js. For example:
`
require('codemirror/mode/go/go.js');
require('codemirror/mode/javascript/javascript.js');
require('codemirror/mode/htmlmixed/htmlmixed.js');
require('codemirror/mode/markdown/markdown.js');
require('codemirror/mode/python/python.js');
`

Options

|Option|Type|Default value|Description|
|------|----|-------------|-----------|
|autoupdate|boolean|true|Controls whether or not the changed event will trigger a diff.|
|bgcolor|string|#eeeeee|The background color for the left-hand and right-hand margins.|
|change_timeout|number|150|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.|
|ignorews|boolean|false|Ignores white-space.|
|ignorecase|boolean|false|Ignores case.|
|ignoreaccents|boolean|false|Ignores accented characters.|
|lcs|boolean|true|Enables/disables LCS computation for paragraphs (char-by-char changes). Disabling can give a performance gain for large documents.|
|lhs|boolean,function handler(setValue)|null|Sets the value of the editor on the left-hand side.|
|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|boolean,function handler(setValue)|null|Sets the value of the editor on the right-hand side.|
|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.|

Constructor

$3

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|selector|string|A CSS selector used to uniquely identify the DOM element that should be used to bind the instance of Mergely.|
|options|object|Configuration options for the instance.|

#### Example

`js
new Mergely('#editor', { ignorews: true });
`

Methods

$3

Clears the editor contents for the specified side.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|side|string|The editor side, either lhs or rhs.|

#### Example

`js
doc.clear('lhs');
`

$3

Gets the CodeMirror editor for the specified side.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|side|string|The editor side, either lhs or rhs.|

#### Example

`js
doc.cm('lhs');
`

$3

Calculates and returns the current .diff file.

#### Parameters

None.

#### Example

`js
doc.diff();
`

$3

Gets the text editor contents for the specified side.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|side|string|The editor side, either lhs or rhs.|

#### Example

`js
doc.get('lhs');
`

$3

Sets the value of the left-hand editor.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|value|string|The editor text.|

#### Example
`js
doc.lhs('This is text');
`

$3

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

`js
doc.merge('lhs');
`

$3

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

`js
doc.mergeCurrentChange('lhs');
`

$3

Sets up a function to be called when the specified event is emitted. The event handler will be automatically deregistered on unbind.

#### Parameters

None.

#### Example

`js
doc.on('updated', () => console.log('updated!'));
`

$3

Sets up a function to be called when the specified event is emitted. The event handler will be automatically deregistered after the handler is called.

#### Parameters

None.

#### Example

`js
doc.unbind();
`

$3

Gets or sets the editor Options. With no arguments, the function will return the currenty configured options. When supplied options to change, the editor will automatically update with the new settings.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|options|object|The options to set.|

#### Example

`js
const currentOptions = doc.options();
doc.options({ line_numbers: true });
`

$3

Resizes the editor. It must be called explicitly if autoresize is disabled.

#### Parameters

None.

#### Example

`js
doc.resize();
`

$3

Sets the value of the right-hand editor.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|value|string|The editor text.|

#### Example

`js
doc.rhs('This is text');
`

$3

Scrolls the editor side to line number specified by lineNum.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|side|string|The editor side, either lhs or rhs.|
|lineNum|number|The line number.|

#### Example

`js
doc.scrollTo('lhs', 100);
`

$3

Scrolls to the next change specified by direction.

#### Parameters

|Name|Type|Description|
|----|----|-----------|
|direction|string|The direction to scroll, either prev or next.|

#### Example

`js
doc.scrollToDiff('next');
`

$3

Search the editor for needle, 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.|
|needle|string|The text for which to search.|
|direction|string|The direction to search, either prev or next.|

#### Example

`js
doc.search('lhs', 'banana');
`

$3

Gets a summary of the editors. Returns an object with summarized properties:

|Name|Description|
|----|-----------|
|a|The number of added lines.|
|c|The number of changed lines.|
|d|The number of deleted lines.|
|lhsLength|The number of characters in the lhs text.|
|rhsLength|The number of characters in the rhs text.|
|numChanges|The total number of changed lines.|

#### Parameters

None.

#### Example

`js
console.log(doc.summary());
// { a: 0, c: 1, d: 0, lhsLength: 44, rhsLength: 45, numChanges: 1 }
`

$3

Swaps the content of the left and right editors. The content cannot be swapped if either editor is read-only.

#### Parameters

None.

#### Example

`js
doc.swap();
`

$3

Clears the editor markup.

#### Parameters

None.

#### Example

`js
doc.unmarkup();
`

$3

Unbinds and destroys the editor DOM.

#### Parameters

None.

#### Example

`js
doc.unbind();
`

Events

Event handlers are automatically unregistered when unbind is called.

$3

Triggered when one of the editors change, e.g. text was altered. The change_timeout controls how much time should pass after the changed event (e.g. keypress) before the updated event is triggered.

#### Example

`js
mergely.once('changed', () => { console.log('changed!'); }

mergely.on('changed', () => { console.log('changed!'); }
`

$3

Triggered after the editor is resized.

#### Example

`js
mergely.once('resized', () => { console.log('resized!'); }

mergely.on('resized', () => { console.log('resized!'); }
`

$3

Triggered after the editor finishes rendering. For example, text updates, options, or scroll events may trigger renders. This event is useful for handling a once-off initialization that should occur after the editor's first render.

#### Example

`js
mergely.once('updated', () => { console.log('updated!'); }

mergely.on('updated', () => { console.log('updated!'); }
``