---
title: "Task diff"
source: https://dev.pageseeder.com/guide/publishing/ant_api/tasks/task_diff.html
description: "The Task diff adds DiffX comparison elements to PageSeeder PSML documents exported with version comparison, showing detailed changes between document versions using configurable granularity and whitespace handling options."
last_updated: 2026-08-11T16:09:37+10:00
tokens: ~1233
---

# Task diff

*This task was introduced in PageSeeder version 5.9605.*

When the [Task export](task_export.md) is used with the attribute `compareto="[version]"`, it generates PSML with a `<compare>` element for each fragment that has been edited since the `version` specified. The `<compare>` element has a `<content>` element which contains the content of the fragment at the time of the `version`.

This task adds a `<diff>` element under each `<compare>` element which is the [DiffX](https://www.pageseeder.org/projects/diffx.html) comparison between the version being exported and the `compareto` version. For example:

```xml

<diff>
  <fragment xmlns:dfx="http://www.topologi.com/2005/Diff-X"
            xmlns:del="http://www.topologi.com/2005/Diff-X/Delete"
            xmlns:ins="http://www.topologi.com/2005/Diff-X/Insert"
            id="2">
    <para>The <dfx:del>quick</dfx:del><dfx:ins>slow</dfx:ins></para>
    <para indent="1" ins:indent="true">brown</para>
    <para del:indent="1">fox</para>
    <para dfx:insert="true"><dfx:ins>jumps</dfx:ins></para>
  </fragment>
</diff>
```

> **Note:** - This task only works on PSML with `level="portable"`. - Only files with `<compare>` elements are output to the destination folder. - If the diff fails for some reason, then no `<diff>` element is added for that fragment.

## Definition

Minimal definition:

```xml
<ps:diff src="[source]" dest="[destination]"/>
```

 Full definition:

```xml
<ps:diff src="[source]"
         dest="[destination]"
         maxevents="[maximum diff events]"
         granularity="[character|word|space_word|text]"
         whitespace="[compare|preserve|ignore]">

  <files>
    <include name="[name]" />
    <exclude name="[name]" />
  </files>

</ps:diff>
```

## Attributes

| **Attribute** | Description | Required | Default |
| --- | --- | --- | --- |
| **src** | The source folder on the file system of the **universal portable format** input. For example: `c:\working\download` | Yes |  |
| **dest** | The destination folder on the file system for the output files. For example: `c:\working\diff` | Yes |  |
| **maxevents** | The maximum number of diff events allowed (see following note) | No | `4000000` |
| **granularity** | Defines the granularity of the text compare used by DiffX. Allowed values are: `character`: compare individual characters, for example, `fox jump<ins>ing</ins>`.`word`: compare individual words, for example, `fox <del>jump</del><ins>jumping</ins>`.`space_word`: compare individual words plus leading spaces, for example, `fox <del> jump</del><ins> jumping</ins>` (better and more efficient). *Requires PageSeeder v6.2 or higher.*`text`: compare all text between elements, for example, `<del>fox jump</del><ins>fox jumping</ins>`. | No | `space_word` |
| **whitespace** | Defines how the whitespaces are to be processed by Diff-X. Allowed values are: `compare`: compare whitespace.`preserve`: preserve but don’t compare whitespace.`ignore`: dont preserve or compare whitespace. | No | `preserve` |

> **Note:** Diff events are the number of elements/attributes/text in each fragment multiplied by each other. When `maxevents` is reached, the diff sets the coarsest granularity (`text`) and tries again. If events is still larger than `maxevents,` the `<diff>` element is not generated. For reasonable performance, a maximum of 4,000,000 is recommended. 

## Elements

### Element \<files\>

Used to only diff certain files in the `src` folder.

This element might contain multiple nested `<include name="" />` or `<exclude name="" />` elements as defined in the following sections.

#### Element \<include\>

A pattern matching documents/folders to include. If not present, then **all** documents/folders are included.

| Attribute | Description | Required |
| --- | --- | --- |
| **name** | The pattern with format is similar to the file selection in other Ant tasks. Examples: `*.psml` `archive` `folder1/*.psml` `**/*.psml`  ????/\*`` | Yes |

#### Element \<exclude\>

A pattern matching documents/folders to exclude. If not present, then **no** documents/folders are excluded.

| Attribute | Description | Required |
| --- | --- | --- |
| **name** | The pattern with format is similar to the file selection in other Ant tasks. Examples: `_local/**` `_external/**` | Yes |

## Examples

**Diff and prepare for processing**

The following example adds diff elements to exported documents and then copies them back to the original folder so they can be [processed](task_process.md).

```xml

<ps:diff src="c:\working\export" dest="c:\working\diff"/>

<copy todir="c:\working\export" overwrite="true">
  <fileset dir="c:\working\diff" />
</copy>
```

**Only diff certain folders**

The following example only diffs PSML files under the top level `articles` folder.

```xml

<ps:diff src="c:\working\export" dest="c:\working\diff">
  <files>
    <include name="articles/**" />
  </files>
</ps:diff>
```