RibbonDiff — User Guide

RibbonDiff is a side-by-side, editable diff tool for macOS. You can type or paste text, or open files 👑 in two panes, edit either side, and RibbonDiff continuously updates a visual diff once both panes contain content. If either pane is blank, RibbonDiff hides diff highlights until both sides have text again. The editor also behaves much more like a native macOS code editor, with line indent/outdent shortcuts, auto-indent on Return, text-size shortcuts, per-pane Find fields with standard macOS shortcuts, and a subtle current-line highlight. The top toolbar row (Wrap, Swap, and Clear) can also be shown or hidden. A center "ribbon" links corresponding changed blocks, helping you follow what moved or changed as you scroll.

1. Put content in both panes

   • Paste text into Text 1 (left / Original) and Text 2 (right / Modified), or
   • Drag a file from Finder onto the left or right pane 👑.
   • Click inside a pane and choose File → Open… (⌘O) 👑.
   • From Terminal, open two files at once with open -a RibbonDiff old.txt new.txt 👑.

2. Edit freely

   • Both panes are fully editable. Diff highlighting appears once both panes have content and updates automatically as you type or paste.
   • Press Return to keep the current line's indentation automatically. Use Tab / Shift-Tab or ⌘] / ⌘[ to indent or outdent lines.
   • When both panes first have content, RibbonDiff automatically jumps to the first changed block (if any).

3. Use the ribbon to stay oriented

   • The middle ribbon visually connects matching change blocks between the left and right panes.

Toolbar (top controls row)

The top controls row acts as a lightweight toolbar for window-level actions. Choose View → Hide Toolbar / View → Show Toolbar or press ⌥⌘T to hide or reveal this row. RibbonDiff remembers this visibility setting across launches.

• Wrap: Toggles word wrap in this window. Also available from View → Word Wrap.
  Shortcut: ⌃⌘W
• Swap: Swaps the left/right texts (and any file association for each pane). Also available from View → Swap Panes.
  Shortcut: ⌃⌘S
• Clear: Clears both panes. If either pane has unsaved edits, the trash icon turns orange as a warning. Also available from Edit → Clear.
  Shortcut: ⌃⌘K

Change navigation

• Jump to the previous/next changed block (added/removed/modified). Use the up/down chevrons above the center ribbon, or Navigate → Previous Change / Navigate → Next Change in the menu bar.
  Shortcuts: ⌥⌘↑ (Previous Change), ⌥⌘↓ (Next Change)

Pane header (each side)

Each pane has a header row containing:

• Title: either the file name (if opened) or "Text 1" / "Text 2".
• Find field: each pane has its own Find field in the header row. Press ⌘F to focus the active pane's field; matches highlight as you type.
• Syntax badge: shows detected syntax (Auto) or your manual selection.
• Line endings badge (optional): shows LF/CRLF/CR and controls which line endings are written when saving (enable in Settings).
• Encoding badge (optional): shows the current text encoding (for example UTF-8, UTF-16LE, UTF-32) and controls which encoding is used when saving (enable in Settings).
• Reload (↻, file-backed panes only) 👑: re-reads the file from disk using a selected encoding. Use this if the file opens with the wrong encoding (garbled text). Reload discards unsaved changes in that pane.
• Clear control:
  • If the pane is backed by a file: an × button unbinds the file and clears the pane.
  • If it's not backed by a file: a trash button clears the pane.
  • These icons become orange when the pane has unsaved changes.
  • Clearing/unbinding either pane also clears diff highlights until both panes have content again.

Window / tab title: when either pane is opened from a file, the macOS window and tab title follows that file name. If both panes are file-backed, the left file name wins. If neither pane is file-backed, the title falls back to RibbonDiff. When a file is supplying the title, macOS also shows the standard proxy icon and path menu in the title bar.

The editors + ribbon

• Left editor: Treated as Original
• Right editor: Treated as Modified
• Middle ribbon: connectors between change blocks (shown once both panes have content), plus a progress spinner while the diff is computing.
• Current-line highlight: the active caret line is shown with a subtle band so it is easier to stay oriented while editing.
• Scrolling: editor scrolling follows standard macOS behavior, including rubber-band scrolling.

RibbonDiff highlights changes using configurable colors:

Note: Diff highlights (line background tints, change markers, and the center ribbon) appear once both panes have content. Clearing/unbinding either pane hides the diff until both sides have text again. When a comparison first becomes available (for example after opening files or pasting into the second pane), RibbonDiff automatically scrolls to the first changed block (if any).

• Added: content that exists only on the right side.
• Removed: content that exists only on the left side.
• Modified: changed regions (and in many cases, changed fragments within a line).
• Connector (ribbon): the middle links between changed blocks.

Navigate between changes (Next/Previous Change)

For large diffs, you can jump directly between changed blocks without manually scrolling.

How to use

• Click the chevron up / chevron down buttons above the middle ribbon.
• Or use the menu bar: Navigate → Previous Change / Navigate → Next Change.
• Keyboard shortcuts: ⌥⌘↑ (Previous Change), ⌥⌘↓ (Next Change).

What counts as a "change"

• Added, Removed, and Modified blocks.
• Unchanged regions are skipped.

Notes

• Tip: When a comparison first becomes available, RibbonDiff automatically scrolls to the first change (if any).
• Navigation follows the active pane (left or right). Click in a pane to make it active.
• If linked scrolling is enabled, RibbonDiff keeps the other pane aligned to the corresponding block.
• When you reach the end (or beginning), navigation wraps around.

Drag and drop (Finder → pane)

• Drop a file directly onto the left or right pane to open it there.
• RibbonDiff will use the file extension (for example .swift, .json, .md) to choose an initial syntax highlighting language.

Overwrite protection RibbonDiff avoids overwriting text accidentally:

• If the pane already contains text, you'll be prompted to clear it first.
• If the pane already has a file open with unsaved edits, RibbonDiff will refuse to replace it until you clear/unbind.

If a pane is file-backed and has no unsaved edits, RibbonDiff will offer a Replace confirmation.

Open from the menu (⌘O)

• Click inside the target pane first (left or right).
• Choose File → Open… (⌘O).

RibbonDiff applies the same overwrite rules as drag-and-drop.

Open from Finder (double-click / "Open With…")

• You can open files directly from Finder:
  • Set RibbonDiff as the default app for a file type and double-click, or
  • Right-click a file and choose Open With → RibbonDiff.
• RibbonDiff opens up to two files per tab:
  • 1 file: opens in the left pane.
  • 2 files: first file → left, second file → right.
  • 3+ files: opened in pairs across tabs by default: (1,2), (3,4), …

Open from Terminal (CLI)

You can open files from the command line using macOS's built-in open command:

open -a RibbonDiff /path/to/old.txt /path/to/new.txt

If your file paths contain spaces, quote them:

open -a "RibbonDiff" "Old File.txt" "New File.txt"

Tab/window behavior (overwrite protection)

• Default: RibbonDiff reuses the frontmost tab only when both panes are blank and not currently opened from a file (a fresh tab). Otherwise it opens the files in a new tab (or a new window if needed) so your current comparison isn't overwritten.

Advanced: reuse modes (CLI wrappers)

Some CLI wrappers can request a different reuse policy when opening files. RibbonDiff reads this policy from an optional control file included in the same open request.

• Automatic (default): reuse the current tab/window only when both panes are blank and not currently opened from a file (a fresh tab); otherwise open a new tab/window.
• Reuse: reuse the current tab/window when there are no unsaved edits; otherwise open a new tab/window.
• Force Reuse: always reuse the current tab/window (this can discard unsaved edits).

Note: When using Reuse or Force Reuse, opening 3+ files (multiple pairs) may reuse the same tab repeatedly. In that case, the last pair wins. Use Automatic if you want each pair to open in its own new tab/window.

Control file requirements

• Name: the file name must start with ribbondiff-cli- or .ribbondiff-cli- (for example ribbondiff-cli--control.json or .ribbondiff-cli--control.json). The extension can be anything, but .json is recommended.
• Contents: JSON with a mode field (case-insensitive): automatic (also accepts auto and default), reuse, or forceReuse. For Force Reuse, force-reuse, force_reuse, and force are also accepted.
• Validation: RibbonDiff treats the file as a control file only when the JSON decodes and the mode value is recognized. Otherwise, the file is treated as a normal file to open/diff.
• Multiple control files: if more than one valid control file is provided, the last valid one wins.
• Not opened as content: when recognized as a control file, it is used for configuration only - it does not populate a pane.

Example (create a control file, then open two files):

echo '{"mode":"reuse","version":1}' > /tmp/.ribbondiff-cli--control.json
open -a RibbonDiff /tmp/.ribbondiff-cli--control.json old.txt new.txt

RibbonDiff saves per pane (whichever pane is active).

Save (⌘S)

• If the pane was opened from a file, Save writes back to that same file.
• If the pane is not backed by a file yet, Save behaves like "create a new file" and will prompt you to pick a location.

Save As (⇧⌘S)

• Always prompts for a new destination and file name.
• If the pane is already file-backed, Save As will use the current file name as the default suggestion.

Line endings and encoding

RibbonDiff focuses the diff on text content, not file storage details. Line endings and character encodings are normalized internally, so two files can compare as identical even if they use different line-ending styles or different Unicode encodings.

Line endings

• What it is: a line ending is how a file separates lines: LF (\n), CRLF (\r\n), or CR (\r).
• How RibbonDiff diffs: line endings are normalized internally, so LF vs CRLF does not create a diff by itself.
• Pane badge: when enabled in RibbonDiff → Settings…, each editor pane shows an LF/CRLF/CR badge. Use it to choose which line endings are written on the next save.
• Opening files: RibbonDiff detects the file's dominant line-ending style when you open it and sets the badge accordingly.
• Saving files: RibbonDiff saves the file using the badge's current selection. Changing only the line-ending badge can rewrite the file without changing the visible text — this is expected.

Text encoding

• What it is: encoding is how characters are stored as bytes on disk. RibbonDiff works with Unicode text internally.
• How RibbonDiff diffs: files are decoded to Unicode text before diffing. If two files decode to the same text (for example, one is UTF-8 and the other is UTF-32), the diff will look identical.
• Pane badge: when enabled in RibbonDiff → Settings…, each editor pane shows an encoding badge. The badge controls which encoding is used on the next save. (Changing the badge does not re-decode the already-open text.)
• Opening files: RibbonDiff tries to auto-detect the file's text encoding when you open it. If auto-detection is ambiguous, RibbonDiff shows a Choose Encoding sheet — pick the correct encoding to open the file.
• Fixing garbled text: if the text looks wrong (mojibake), use the pane's Reload control (↻) to Reload with Encoding, choose a different encoding, and reload from disk. (Reload discards unsaved edits in that pane.)
• Saving files: RibbonDiff writes the file using the encoding shown in the badge. Choose UTF-8 (with BOM) if you need a BOM on save. Changing only the encoding badge can rewrite the file without changing the visible text — this is expected.

Supported encodings

These options appear in the per-pane Encoding badge menu:

Tip: When you're comparing clipboard text (not a file), the pane defaults are typically LF + UTF-8 for saving.

RibbonDiff tracks unsaved edits independently for each pane.

• The window shows the standard macOS "document edited" dot when either pane has unsaved edits.
• Unsaved changes include text edits and also changes to the per-pane Line endings and Encoding badges (when enabled in Settings).
• If you close a window/tab (⌘W) with unsaved edits, RibbonDiff shows an Unsaved Changes alert with:
  • Cancel
  • Close Without Saving

Note: The close prompt is intentionally "no-save" — save the relevant pane(s) first using ⌘S or ⇧⌘S 👑.

RibbonDiff uses per-pane Find fields in the header row, while still honoring the standard macOS Find shortcuts for the active pane.

Basic use

1. Click in the left or right editor to make that pane active.
2. Press ⌘F to focus that pane's Find field in the header. If text is selected in the editor, RibbonDiff uses that selection as the query. Otherwise, if that pane's Find field is empty, RibbonDiff can prefill it from the standard macOS shared Find string.
3. Type your query. Case-insensitive matches are highlighted as you type.
4. Press Return or ⌘G for the next match, and ⇧Return or ⇧⌘G for the previous match. Find navigation wraps around when you reach the end or beginning of the pane.

Keyboard shortcuts

• Find…: ⌘F (focuses the active pane's Find field)
• Find Next: ⌘G
• Find Previous: ⇧⌘G
• Use Selection for Find: ⌘E

Notes

• Each pane keeps its own Find query, but RibbonDiff also syncs with the standard macOS shared Find string.
• Find actions follow the active pane. Clicking a pane's editor or its Find field makes that side active.
• Use Selection for Find (⌘E) uses the selected text in the active editor.
• Press Esc while editing a Find field to return focus to that pane's editor.
• Use the Find field's menu for Find Next, Find Previous, Recent Searches, and Clear Recent Searches.

RibbonDiff includes built-in syntax highlighting and automatic language detection.

Auto vs manual

• Auto: RibbonDiff detects the language from the text.
• Manual override: Click the syntax badge and pick a language.

Supported languages (badge)

• Plain text
• Swift
• C-like (C/C++/ObjC style)
• Java
• PHP
• Go
• Ada
• Rust
• Python
• JavaScript / TypeScript family
• JSON
• YAML
• HTML/XML
• Markdown

Markdown fenced code blocks

In Preferences you can choose whether Markdown fenced blocks (``` / ~~~) are highlighted using the language tag after the fence (e.g. ```swift).

Toolbar visibility

• Choose View → Hide Toolbar to hide the top controls row (Wrap, Swap, and Clear).
• Choose View → Show Toolbar to bring the row back.
• Shortcut: ⌥⌘T
• RibbonDiff remembers this visibility setting across launches.
• The pane headers, Find fields, and change navigation buttons stay visible when the toolbar is hidden.

Word wrap

• Toggle Wrap in the toolbar when it is visible, or choose View → Word Wrap (window-local).
• Shortcut: ⌃⌘W
• View → Word Wrap and the shortcut still work even when the toolbar is hidden.

Important: Wrap is per window, not global. Preferences only set the default for newly opened editor windows.

Line numbers

Enable/disable line numbers independently for:

• Left (Original)
• Right (Modified)

You can change this in Preferences.

Font, font size and line spacing

RibbonDiff lets you adjust the editor typography so long comparisons are easier on your eyes.

• Open RibbonDiff → Settings… (⌘,) and go to General → Editor.
• On macOS, use Show Font Panel… to choose from your installed fonts. The current selection is shown next to Font.
• Adjust Font size and Line spacing. These changes apply immediately to both panes.
• While editing, use ⌘= (or ⌘+ on keyboards where + shares the same key) to increase text size, ⌘- to decrease it, and ⌘0 to reset the editor text size. The current text size is shared by both panes and persists across launches.
• Use Restore Default Font, Size & Spacing to return all three editor typography settings to their defaults.

Editing behavior

• Auto-indent on Return: pressing Return continues the current line's indentation automatically.
• Indent / outdent with Tab: use Tab to indent and Shift-Tab to outdent the current line or selected lines. (needs any selection)
• Bulk indent / outdent: use ⌘] to indent and ⌘[ to outdent the current line or selected lines.
• Inferred indentation: RibbonDiff tries to detect the active pane's indentation width from its text and uses that when editing. If it cannot infer a clear style, it falls back to the default indentation width.
• Current-line highlight: the caret line is highlighted subtly to help you track your position while editing.

Open Preferences from the app menu:

• RibbonDiff → Settings… (usually ⌘,)

General

• Toggle line numbers for left/right.
• Set the default word wrap behavior for newly opened windows.
• Choose the editor Font, Font size and Line spacing; on macOS, use Show Font Panel… to browse installed fonts. While editing, you can also change text size with ⌘=, ⌘-, and ⌘0.
• Enable per-pane Line endings and Encoding badges (used when saving).
• Reset all diff/syntax/theme settings back to defaults.

Appearance

• Customize diff colors: Added, Removed, Modified, Connector (ribbon).
• Choose System or Custom backgrounds for:
  • Editor background
  • Ribbon background

System backgrounds automatically follow macOS Light/Dark Mode.

Syntax

• Use built-in "System" syntax colors or enable Custom.
• Edit separate Light and Dark syntax palettes.
• Toggle Markdown fenced code-block highlighting.
• Reset current or both palettes.

Changes are saved automatically.

Theme

RibbonDiff supports:

• Built-in themes ("Simple" and "Vivid")
• User themes (created, duplicated, or imported)

Theme list tips:

• The selected theme shows a leading checkmark.
• A theme row may show a Modified badge if your current colors differ from that theme's saved defaults.

Actions you may see:

• Revert to Theme Defaults
• Save as New Theme…
• Duplicate…
• Rename… (user themes)
• Remove (user themes)

Pro

• Shows your access level: Limited (Free), Pro Trial (7 days), or Pro Lifetime.
• Start the free 7-day Pro Trial (no automatic charges when the trial ends).
• Unlock Pro Lifetime (one-time purchase).
• Restore Purchases if Pro access doesn't appear (for example after reinstalling or switching Macs).

If you previously purchased RibbonDiff as a paid App Store download, it should automatically unlock Pro Lifetime on the same Apple ID. If it doesn't, open RibbonDiff → Settings… → Pro and use Restore Purchases.

Themes can be imported/exported as JSON.

Import a theme

1. Open Preferences → Theme
2. Click Import Theme…
3. Choose a theme .json file

The imported theme is added to User Themes and applied.

Export a theme

1. Open Preferences → Theme
2. Click Export Theme…
3. Enter a theme name (stored in the JSON as Name)
4. Choose a save location

The Export button saves the current theme's settings to a JSON file.

The exported JSON includes:

• Diff colors + backgrounds
• Syntax palette(s) and Markdown options

Tip: Pressing Return in an editor continues the current line's indentation automatically.

"Can't open file"

Common reasons:

• You're in Limited mode — opening files is a Pro feature 👑.
• The target pane already contains text.
• The target pane already has an opened file with unsaved edits.

Fix:

• Start a Pro Trial or unlock Pro Lifetime from RibbonDiff → Settings… → Pro.
• Use the pane's trash / × control to clear it, or open the file in the other pane.

Opening from Finder/Terminal created a new tab

When you open files from Finder (double-click / Open With…) or from Terminal (open -a RibbonDiff …), RibbonDiff protects your current comparison.

• If the frontmost tab already has content, file(s) open, or unsaved edits, RibbonDiff opens the new files in a new tab (or a new window if needed).
• If the frontmost tab is a fresh tab (both panes are blank and not currently opened from a file), RibbonDiff reuses it.
• If you want RibbonDiff to reuse the current tab, make sure both panes are blank and unbound (not opened from a file) — use the pane's trash / × control to clear/unbind (or use a CLI "reuse" option if your workflow supports it).

Text looks garbled (wrong encoding)

If a file opens with unreadable characters (mojibake), it was likely decoded with the wrong encoding.

• Enable the Encoding badge in RibbonDiff → Settings… (General).
• In the pane header, click the Reload icon (↻) and choose Reload with Encoding to re-open the file using a different encoding.
• If RibbonDiff shows a Choose Encoding sheet on open, pick the correct encoding to continue.
• Note: Reload re-reads from disk and discards unsaved edits in that pane.

Wrap / Swap / Clear disappeared

The top toolbar row may be hidden.

• Choose View → Show Toolbar, or press ⌥⌘T.
• This only restores the top toolbar row; your editor content and diff are unchanged.

"Theme Import Failed"

• The selected JSON file may not match RibbonDiff's theme format, or may be malformed.

Syntax highlighting looks disabled

RibbonDiff may skip syntax highlighting for very large texts to keep editing responsive.

RibbonDiff is free to download and use in Limited mode. File workflows are available with a one-time Pro Lifetime unlock, or a one-time free Pro Trial (7 days). 👑 marks Pro features throughout this guide.

7-day Pro Trial: The trial starts when you tap "Start 7-Day Pro Trial" and lasts 7 days. When it ends, RibbonDiff returns to Limited mode (file open/drag-drop/save are disabled) unless you unlock Pro Lifetime. There are no automatic charges when the trial ends.

Start the Pro Trial

1. Open RibbonDiff → Settings… and select Pro.
2. Click Start 7-Day Pro Trial.

Unlock Pro Lifetime

Open RibbonDiff → Settings… → Pro and click Unlock Pro Lifetime. This is a one-time purchase tied to your Apple ID.

Restore purchases

If you previously purchased Pro Lifetime (or bought RibbonDiff when it was a paid App Store app), restore access from Settings → Pro → Restore Purchases. Make sure you're signed into the same Apple ID that made the original purchase.

Legacy paid customers

If you purchased RibbonDiff when it was a paid App Store download, the app automatically migrates you to Pro Lifetime on the same Apple ID. If it doesn't show as unlocked right away, use Restore Purchases.