Mergely

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

Usage via React

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

npm install mergely-react

Usage via Angular

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.

Usage via webpack

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

Usage via CDN

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

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mergely/5.0.0/mergely.min.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/mergely/5.0.0/mergely.css" />

Synchronous initialization

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

<body>
  <div id="compare"></div>

  <script>
    const doc = new Mergely('#compare', {
      lhs: 'the quick red fox\njumped over the hairy dog',
      rhs: 'the quick brown fox\njumped over the lazy dog'
    });
  </script>
</body>

Asynchronous initialization

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.

<body>
  <div id="compare"></div>

  <script>
    const doc = new Mergely('#compare');
    doc.once('updated', () => {
      doc.lhs('the quick red fox\njumped over the hairy dog');
      doc.rhs('the quick brown fox\njumped over the lazy dog');
      // Scroll to first change on next update
      doc.once('updated', () => {
        doc.scrollToDiff('next');
      });
    });
  </script>
</body>

Visualization modes

Mergely supports the following CodeMirror visualizations for mode:

  • go
  • javascript
  • htmlmixed
  • markdown
  • python

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

constructor(selector: string, options?: object)

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

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

Methods

clear(side: string)

Clears the editor contents for the specified side.

Parameters

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

Example

doc.clear('lhs');

cm(side: string)

Gets the CodeMirror editor for the specified side.

Parameters

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

Example

doc.cm('lhs');

diff()

Calculates and returns the current .diff file.

Parameters

None.

Example

doc.diff();

get(side: string)

Gets the text editor contents for the specified side.

Parameters

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

Example

doc.get('lhs');

lhs(value: string)

Sets the value of the left-hand editor.

Parameters

Name Type Description
value string The editor text.

Example

doc.lhs('This is text');

merge(side: string)

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

doc.merge('lhs');

mergeCurrentChange(side: string)

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

doc.mergeCurrentChange('lhs');

on(event: string, handler: function)

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

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

once(event: string, handler: function)

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

doc.unbind();

options(options?: object)

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

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

resize()

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

Parameters

None.

Example

doc.resize();

rhs(value: string)

Sets the value of the right-hand editor.

Parameters

Name Type Description
value string The editor text.

Example

doc.rhs('This is text');

scrollTo(side: string, lineNum: integer)

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

doc.scrollTo('lhs', 100);

scrollToDiff(direction: string)

Scrolls to the next change specified by direction.

Parameters

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

Example

doc.scrollToDiff('next');

search(side: string, needle: string, direction: string = ‘next’)

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

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

summary()

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

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

swap()

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

Parameters

None.

Example

doc.swap();

unmarkup()

Clears the editor markup.

Parameters

None.

Example

doc.unmarkup();

unbind()

Unbinds and destroys the editor DOM.

Parameters

None.

Example

doc.unbind();

Events

Event handlers are automatically unregistered when unbind is called.

changed

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

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

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

resized

Triggered after the editor is resized.

Example

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

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

updated

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

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

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