You are here: System » DiffPlugin


Compare difference between topics and revisions


This plugin implements a way to display the difference between revisions of the same topic or between two distinct topics. This adds YADT (yet another diff tool) to those previously available, i.e. Foswiki's core rdiff as well as the CompareRevisionsAddOn's compare tools. In contrast to previous work, DiffPlugin tries to display differences in a way users really can see what the difference actually is. It takes particularly care of any kind of meta data stored in a topic and diff these individually. DiffPlugin implements a %DIFF macro so that you can use it in wiki applications easily.

It integrates well with AngularSkin/AngularPlugin so that browsing among differences using the "tape-recorder" navigation feels most natural while going forward and backwards between revisions.


You type:


You get:

diff screenshot


The %DIFF macro is mostly driven by defaults in the diff.tmpl template. Each parameter has got a named definition there being used as a fallback in case the parameter wasn't specified as part of the %DIFF macro.

Parameter Description Default
oldtopic name of the topic on the left handside current topic
newtopic name of the topic on the right handside oldtopic
oldrev revision of oldtopic to diff latest revision of oldtopic
newrev, rev revision of the newtopic to diff latest revision of newtopic
offset alternative way to specify the number of revisions to diff: either use oldrev and newrev, or use rev and specify an offset into the revision history to diff 1
context number of lines around a difference to display in addition to the difference itself 2
beforetext text to be displayed before any output diff::beforetext
aftertext text to be appended to the output diff::aftertext
header header of the diff table while iterating over all differences of a specific type diff::header
footer footer of a diff table diff::footer
format row of a diff table diff::format
meta_format format to be used to display meta data diff::meta_format
separator separator between rows of a diff table diff::separator
no_differences message to be displayed when no differences have been found diff::no_differences

The format strings can take a number of variables refering to the properties of the objects being processed:

  • $oldtopic: topic name (without the web name) of oldtopic
  • $oldweb: web name of oldtopic
  • $oldrev: revision number of oldtopic
  • $maxoldrev: maximum numbers of revision in oldtopic
  • $oldauthor: author of the revision of oldtopic being processed
  • $olddate: date when $oldauthor edited revision oldrev of oldtopic

  • $newtopic: topic name (without the web name) of newtopic
  • $newweb: web name of newtopic
  • $newrev: revision number of newtopic
  • $maxnewrev: maximum numbers of revision in newtopic
  • $newauthor: author of the revision of newtopic being processed
  • $newdate: date when $newauthor edited revision newrev of newtopic

  • $offset: offset between $oldrev and $newrev
  • $maxrev: alias for $maxnewrev
  • $prevrev: previous revision id
  • $nextrev: next revision id

  • $old: displays the difference of the current row being formatted in the column left column
  • $new: displays the difference of the current row being formatted in the column right column
  • $action: the kind of difference between $old and $new, can be "changed", "removed", "append" or "unchanged"
  • $index: row being diff'ed currently
  • $name: formfield filed name when diff'ing a DataForm or any other custom meta data with a "name" attribute
  • $type: type of data being proccessed, can be "TEXT","TOPICINFO" or "TOPICPARENT", "FORM", "FIELD", "FILEATTACHMENT", "PREFERENCES" or the registered identifier of custom meta data


DiffPlugin comes with two scripts that may be used in your web-server environment - diff and diffauth - that can be used similar to rdiff and rdiffauth. No additional provisions are required when using FastCGIEngineContrib or any other persistent-perl environment where Foswiki's {SwitchBoard} mechanism is used to schedule the diff action to this plugin.

To integrate DiffPlugin into the installed skin you may replace any call to rdiff with diff, or enable the {PatchDiffScript} to automatically replace any use of the rdiff or compare scripts with a call to diff.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See for more help.



Change History

11 Jun 2018 fix changes not displayed under certain conditions
09 Jan 2018 throw an access exception instead of showing an inline error diffing revisions
01 Jun 2016 initial release
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback