Log inRegister
You are here: System » DiffPlugin

DiffPlugin

Compare difference between topics and revisions

Description

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.

Examples

You type:

%DIFF{
   oldtopic="%SYSTEMWEB%.UserForm" 
   newtopic="%USERSWEB%.UserForm"
}%

You get:

diff screenshot

Syntax

DIFF

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
exclude list of parts to exclude from being diffed, e.g. parent, form, fields, attachments, preferences, listy  

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
  • =$exclude: parts that are excluded from diffing

  • $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

DIFFCONTROL

The %DIFFCONTROL lets you control a %DIFF happening on the same page. While you might specifiy all aspects of the diff directly in the %DIFF macro the %DIFFCONTROL lets you do so independently somewhere else on the page. I.e. it is not performing the diff operation itself. It rather displays control elements used to navigate between other diffs, like jumping to the previous or next diff following the current one. By default the appearance of diff controls are configured by the diff::control part of the diff.tmpl template file part of this extension. You might still decide to override those using the following parameters:

  • temlpate: the template to read controls from, defaults to diff::control
  • format: a format string to specify a diff control explicitly

Note that when format is given template is ignored. template basically is the name of a template to be used as a format. The format string then makes use of above variables.

Configuration

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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

NameVersionDescription
Algorithm::Diff>=0Required
Algorithm::Diff::XS>=0optional

Change History

19 Jan 2024 minor code improvements
28 Apr 2022 don't patch scripts from compare, rdiff to diff by default for performance reasons
20 Oct 2020 display dates and time of changes; added support for Foswiki:Extensions/RevCommentPlugin
27 Nov 2019 fixed js error in diff interface
12 Nov 2019 improve ui diffing revisions; added option to exclude certain parts; log diff event
25 Oct 2018 implement a separate DIFFCONTROL macro; separate diff.tmpl and diffview.tmpl
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