Introduce Unified Diff display mode to Compare editor

[tobiasmelcher]

Add Unified Diff Display in Text Editor as Alternative to Classic 2-Way Compare

Implements eclipse-platform/eclipse.platform.ui#3771

Summary

This contribution introduces a new Unified Diff viewing mode for org.eclipse.compare that displays differences in a single editor pane, similar to git diff or GitHub's pull request view. When enabled, it replaces the traditional side-by-side 2-way compare editor for read-only comparisons, providing a more compact and familiar diff experience.

This is a draft implementation to gather early feedback from the Eclipse community on:

• API design and public interface shape
• Integration approach with existing compare infrastructure
• User experience and workflow expectations
• Performance and edge case handling

---

What's Included

1. New Public API (org.eclipse.compare.unifieddiff)

Added a new public package with the UnifiedDiff class as the main entry point for programmatically opening unified diffs in text editors.

Supported Modes:

• REPLACE_MODE: Diffs are directly applied to the editor content. Users can keep or undo individual changes.
• OVERLAY_MODE: Source content remains unmodified. Diffs are shown via code mining annotations, and users can selectively apply or cancel individual changes.
• OVERLAY_READ_ONLY_MODE: Source content remains unmodified and read-only. Diffs are shown via code mining annotations for viewing only.

API Example:

UnifiedDiff.create(editor, sourceContent, UnifiedDiffMode.OVERLAY_READ_ONLY_MODE)
    .ignoreWhiteSpace(true)
    .open();

2. Preference Page Integration

Added a new checkbox in Preferences > General > Compare/Patch:

• "Use Unified Diff instead of 2-way compare when possible"

When enabled, eligible compare operations automatically use the unified diff viewer instead of the traditional side-by-side editor.

3. Automatic Compare Editor Integration

Modified CompareUIPlugin#openCompareEditor() to detect when unified diff should be used:

• Only applies to 2-way comparisons (left vs. right, no ancestor)
• Only applies to read-only comparisons (no editing capabilities needed)
• Automatically extracts content and opens in unified diff mode when preference is enabled

---

How to Test

Prerequisites

• Eclipse workspace with a Java project tracked in a Git repository

Steps

1. Open Window > Preferences > General > Compare/Patch
2. Enable the checkbox: "Use Unified Diff instead of 2-way compare when possible"
3. In the Package Explorer, right-click a Java file
4. Select Team > Show in History
5. In the History view, select two different commits
6. Right-click and choose Compare with Each Other

Expected Result:

• Instead of the traditional side-by-side compare editor, a single editor opens showing the unified diff
• Added lines appear with green background highlighting
• Deleted lines appear as code mining annotations with red background
• Character-level changes within modified lines are highlighted with darker shades

Next Steps

• Remove reflection calls - Enhance the code mining APIs so that the current reflection calls can be removed
• Code cleanup - Polish implementation
• Bug fixes - Address issues reported by the Eclipse community
• UI/UX improvements - Enhance user experience based on the community feedback

[github-actions]

Test Results

0 files   -     54  0 suites   - 54   0s ⏱️ - 35m 53s
0 tests  -  4 556  0 ✅  -  4 533  0 💤  -  23  0 ❌ ±0 
0 runs   - 12 264  0 ✅  - 12 105  0 💤  - 159  0 ❌ ±0 

Results for commit af1f8ef. ± Comparison against base commit 9c3aad6.

♻️ This comment has been updated with latest results.

[tobiasmelcher]

[vogella]

Looks amazing

[HeikoKlare]

I very much like that feature. I would be in favor of integrating a usable state as early as possible and incrementally improve it, so that it becomes easy to test and so that you get feedback soon.

You currently seem to introduce new API with the org.eclipse.compare.unifieddiff package. Is it necessary to export that package at all or can it stay internal (for now)? If the feature can be added as configurable opt-in/opt-out without adding any new API, it could even be integrated in a rather experimental state, as it can be disabled and also incrementally improved or, in case of problems, even removed again without having to consider any effects on existing consumers.

[vogella]

@tobias-melcher can you finish this one? Would be awesome to have this as option (hopefully the default 1-2 releases later).

[laeubi]

that displays differences in a single editor pane, similar to git diff or GitHub's pull request view.

For me github shows by default a split view (what often is a bit better than the eclipse one but that's a different story) and one has to explicitly select "unified" - so I don't think one is the "default" over the other but its just two options one can switch between and depends on preference of the user.

[tobiasmelcher]

@tobias-melcher can you finish this one? Would be awesome to have this as option (hopefully the default 1-2 releases later).

Sure, I will do my best. I think the most important topic is that we get rid of the reflection calls. I will concentrate on this topic in the next weeks. I understand the request to make this feature available as early as possible and mark it as experimental. I will do this.

[tobiasmelcher]

I very much like that feature. I would be in favor of integrating a usable state as early as possible and incrementally improve it, so that it becomes easy to test and so that you get feedback soon.

You currently seem to introduce new API with the org.eclipse.compare.unifieddiff package. Is it necessary to export that package at all or can it stay internal (for now)? If the feature can be added as configurable opt-in/opt-out without adding any new API, it could even be integrated in a rather experimental state, as it can be disabled and also incrementally improved or, in case of problems, even removed again without having to consider any effects on existing consumers.

@HeikoKlare I marked the package as "provisional API" and added "EXPERIMENTAL" to the preference label with [900a124]. Would you prefer to add "internal" to package "org.eclipse.compare.unifieddiff" or is x-internal sufficient?

[danthe1st]

Since this is API, I think using an enum here means that adding enum constants is a backwards incompatible change? Should this be updated to allow for adding new values without breaking compatibility?

[tobiasmelcher]

thanks a lot for the feedback @danthe1st . I have replaced the enum with a type-safe constant class [af1f8ef]. Do you have any further feedback?
I’d also like to better understand the compatibility concern: is adding an additional enum value really considered binary incompatible? If so, could you please point me to the relevant documentation that explains why enums are not allowed in Eclipse APIs?