Diff
diff
Compares entity revisions field by field and displays visual differences between them.
Overview
The Diff module provides a sophisticated revision comparison system for Drupal content entities. It replaces the standard Revisions tab with an enhanced interface that allows users to select and compare any two revisions of a content entity.
The module offers multiple display layouts for revision comparison: Split Fields (side-by-side view), Unified Fields (line-by-line view), and Visual Inline (rendered HTML comparison using the entity's view mode). Each layout provides different perspectives on how content has changed between revisions.
Diff uses a flexible plugin system to handle different field types. Field diff builder plugins transform field values into comparable strings, while layout plugins determine how the comparison is displayed. This architecture makes the module extensible and customizable for various content types and use cases.
The module integrates with Content Moderation to display workflow state changes in revision descriptions, and provides Views field plugins for building custom revision comparison interfaces.
Install
composer require 'drupal/diff:8.x-1.9'
composer require 'drupal/diff:8.x-1.6'
Features
- Enhanced revision overview page with side-by-side revision selection using radio buttons
- Multiple comparison layout options: Split Fields (side-by-side), Unified Fields (line-by-line), and Visual Inline (rendered HTML diff)
- Field-by-field comparison with configurable field diff builder plugins for different field types
- Support for comparing text fields, entity references, images, files, links, list fields, and comment fields
- Navigation between revision changes with Previous/Next change links
- Filter options for viewing raw content or markdown-processed content
- Visual Inline layout using HtmlDiffAdvanced library for rendered entity comparison with configurable view modes
- Content Moderation integration displaying workflow states in revision descriptions
- Views integration with diff__from and diff__to field plugins for custom revision comparison views
- Extensible plugin architecture allowing custom field diff builders and layout plugins
- Configurable radio button behavior for revision selection (Simple exclusion or Linear restrictions)
- Per-field configuration for diff display including field title visibility and markdown callback options
- Automatic route generation for revisionable entity types with diff support
Use Cases
Editorial Workflow Review
Content editors can use Diff to review changes made by other team members before publishing. By comparing the current draft with the published version, editors can see exactly what text was added, removed, or modified, making the review process more efficient and accurate.
Content Audit and History Tracking
Administrators can track the evolution of important content over time. By comparing any two historical revisions, they can understand how content has changed, who made changes (via revision log messages), and verify that changes align with content strategy.
Translation Comparison
For multilingual sites, Diff helps translators understand what changed in the source content between translation updates. By comparing revisions of the source language, translators can focus on updating only the portions that changed.
Visual Content Preview
Using the Visual Inline layout, content creators can see how their changes affect the rendered appearance of content. This is particularly useful for complex content types with multiple fields and formatting options.
Custom Revision Views
Site builders can create custom Views displaying revision lists with comparison capabilities. Using the diff__from and diff__to field plugins, users can select any two revisions from a list and compare them directly.
Tips
- Enable only the layout plugins you need to simplify the user interface for content editors
- Use the 'Linear restrictions' radio behavior to guide users toward comparing adjacent revisions chronologically
- Configure the Visual Inline layout to use the 'Diff' view mode for a cleaner comparison focused on content changes
- For image fields, enable thumbnail display in the field diff plugin settings to visualize image changes
- Use markdown callbacks on text fields to strip HTML for cleaner text-only comparisons
- Set appropriate context lines (leading/trailing) based on your content length - fewer lines for short content, more for longer articles
Related Projects
Integrates with Content Moderation to display workflow state labels in revision descriptions. When a revision changes moderation state, the state label appears in parentheses after the revision log message.
Provides diff__from and diff__to Views field plugins that add radio buttons to Views for selecting revisions to compare. Enables building custom revision comparison interfaces.
Replaces the standard node version history page with an enhanced revision overview form featuring side-by-side revision selection and a Compare button.
Admin Pages
| Title | Path | Description |
|---|---|---|
| Diff General Settings | /admin/config/content/diff/general |
Configure global settings for the revision comparison functionality including layout plugins, radio button behavior, and context lines for field-based layouts. |
| Fields Settings | /admin/config/content/diff/fields |
Configure diff builder plugins for each field type in the system. Select which plugin handles the comparison for each field and configure field-specific settings. |
Hooks
| Hook | Description |
|---|---|
hook_field_diff_builder_info_alter |
Alters field diff builder plugin definitions. Allows modules to modify plugin labels, weights, or other properties. |
hook_diff_layout_builder_info_alter |
Alters diff layout builder plugin definitions. Allows modules to modify layout plugin labels, descriptions, or other properties. |
Troubleshooting
The Visual Inline layout requires the php-htmldiff-advanced library. Install it using Composer: composer require caxy/php-htmldiff. The layout will automatically become available once the library is installed.
Check the Fields Settings page at /admin/config/content/diff/fields. Ensure the field has a diff plugin selected (not "Don't compare"). Also verify the field is revisionable and has view display configured.
Ensure the revisions actually contain different values for the compared fields. Check that the field diff plugin is correctly configured. For entity reference fields, verify the comparison method (ID vs Label) matches your expectations.
Adjust the Radio behavior setting at /admin/config/content/diff/general. 'Simple exclusion' prevents selecting the same revision; 'Linear restrictions' enforces chronological selection order.