Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wickedest/Mergely

Merge and diff documents online
https://github.com/wickedest/Mergely

diff hacktoberfest

Last synced: 3 days ago
JSON representation

Merge and diff documents online

Awesome Lists containing this project

README 

        
# Mergely



![mergely logo](https://www.mergely.com/images/mergely.png)



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](https://github.com/wickedest/Mergely/tree/v4.3.9#mergely).



## Usage



### Usage via React



The easiest and recommended way to use Mergely is with the [mergely-react](https://npmjs.com/package/mergely-react) component.



```bash

npm install mergely-react

```



### Usage via Angular



There is an Angular component for Mergely [mergely-angular](https://github.com/wickedest/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](https://github.com/wickedest/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 `` of your target HTML source file. Note that `codemirror` is bundled.



```html



```



### Synchronous initialization



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



```html



  



  

    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'

    });

  



```



### 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.



```html



  



  

    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');

      });

    });

  



```



### Visualization modes



Mergely supports the following CodeMirror visualizations for [mode](codemirror.net/5/doc/manual.html#option_mode):



* go

* javascript

* htmlmixed

* markdown

* python



## Options



|Option|Type|Default value|Description|

|------|----|-------------|-----------|

|autoupdate|boolean|true|Controls whether or not the [`changed`](#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](https://codemirror.net)) 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](https://codemirror.net)) 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](https://codemirror.net)) 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



```js

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



```js

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



```js

doc.cm('lhs');

```



### diff()



Calculates and returns the current .diff file.



#### Parameters



None.



#### Example



```js

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



```js

doc.get('lhs');

```



### lhs(value: string)



Sets the value of the left-hand editor.



#### Parameters



|Name|Type|Description|

|----|----|-----------|

|value|string|The editor text.|



#### Example

```js

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



```js

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



```js

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



```js

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



```js

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



```js

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



```js

doc.resize();

```



### rhs(value: string)



Sets the value of the right-hand editor.



#### Parameters



|Name|Type|Description|

|----|----|-----------|

|value|string|The editor text.|



#### Example



```js

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



```js

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



```js

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



```js

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



```js

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



```js

doc.swap();

```



### unmarkup()



Clears the editor markup.



#### Parameters



None.



#### Example



```js

doc.unmarkup();

```



### unbind()



Unbinds and destroys the editor DOM.



#### Parameters



None.



#### Example



```js

doc.unbind();

```



## Events



Event handlers are automatically unregistered when [unbind](#unbind) is called.



### changed



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



#### Example



```js

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



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

```



### resized



Triggered after the editor is resized.



#### Example



```js

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



```js

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



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

```