caption: diff-text
created: 20180316162725329
modified: 20260102132650194
tags: Widgets
title: DiffTextWidget
type: text/vnd.tiddlywiki

! Introduction

<<.from-version "5.1.16">> The diff text widget analyses the differences between a pair of source and destination text strings and displays the results as highlighted insertions and deletions (similar to the "track changes" function of a word processor).

```
<$diff-text source="This is the original text" dest="This is the text to compare to" mode="words>
    These are the <<diff-count>> differences:
</$diff-text>
```



! Content and Attributes

The content of the <<.wid diff-text>> widget is displayed immediately before the differences. Within the content, the variable <<.var diff-count>> is available, containing the number of differences found. If the widget has no content then it automatically transcludes the tiddler [[$:/language/Diffs/CountMessage]].

<<.note """The algorithm counts changes as both insertion and deletion, and therefore the number of differences can be higher than expected.""">>

|!Attribute |!Description |
|<<.attr source>> |The source text |
|<<.attr dest>> |The destination text |
|<<.attr cleanup>> |Optional post-processing to improve readability (default is <<.value semantic>>) |
|<<.attr editcost>> |<<.from-version "5.4.0">> Threshold parameter for <<.value efficiency>> cleanup mode (default is <<.value 4>>) |
|<<.attr mode>> |<<.from-version "5.4.0">> Specifies the granularity at which differences are computed and displayed (default is <<.value chars>>) |


!! <<.attr cleanup>> / <<.attr editcost>>

The <<.attr cleanup>> attribute determines which optional post-processing should be applied to the diffs:

* <<.value none>>: No cleanup is performed
* <<.value semantic>> (default): Optimizes the differences for readability
* <<.value efficiency>>: Optimizes the differences to minimise the number of operations for subsequent processing
** When using <<.value efficiency>> mode, the <<.attr editcost>> parameter controls the cost threshold for the cleanup algorithm, determining how aggressively the diff algorithm merges nearby edits for better human readability (default value is 4).

<<.note """Note that in many cases the results will be the same regardless of the cleanup option. See the [[docs|https://github.com/google/diff-match-patch/wiki/API]] of the underlying library for more details""">>

!! <<.attr mode>>

The <<.attr mode>> attribute determines how differences are computed and displayed:

* <<.value chars>>: Compares differences at the //character level// for precise change detection
* <<.value words>>: Compares differences at the //word level// for more readable text comparisons
* <<.value lines>>: Compares differences at the //line level// for better visibility of structural changes

! Examples

A basic example:

<<.example n:1 e.g."""<$diff-text source="The quick brown fox jumps" dest="The slick brown fox leaps"/>""">>

In <<.value words>> mode, differences are computed at the words level:

<<.example n:2 e.g."""<$diff-text mode="words" source="The quick brown fox jumps" dest="The slick brown fox leaps"/>""">>


To see the effects of all parameters, use this example:

|tc-max-width tc-edit-max-width|k
|<$edit-text tiddler="SampleTiddlerFirst" rows="5"/>|<$edit-text tiddler="SampleTiddlerSecond" rows="5"/>|

<$diff-text source={{SampleTiddlerFirst}} dest={{SampleTiddlerSecond}} cleanup={{{ [{!!cleanup}!is[blank]else[efficiency]] }}} editcost={{{ [{!!editcost}!is[blank]else[4]] }}} mode={{{ [{!!mode}!is[blank]else[chars]] }}}/>

!! <<.attr mode>>
<$radio field="mode" value="chars" default="chars" class="tc-small-gap-right"> <<.value chars>></$radio>
<$radio field="mode" value="words" class="tc-small-gap-right"> <<.value words>></$radio>
<$radio field="mode" value="lines"> <<.value lines>></$radio>

!! <<.attr cleanup>>
<$radio field="cleanup" value="none" class="tc-small-gap-right"> <<.value none>></$radio>
<$radio field="cleanup" value="semantic" class="tc-small-gap-right"> <<.value semantic>></$radio>
<$radio field="cleanup" value="efficiency" default="efficiency"> <<.value efficiency>></$radio>

<% if [{!!cleanup}!match[none]!match[semantic]] %>

!! <<.attr editcost>>: <$transclude $variable=".value" _={{{ [{!!editcost}!is[blank]else[4]] }}} />
<$range field="editcost" min="1" max="200" default="4" class="tc-max-width" style.max-width="500px" />
<% endif %>