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. 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. The diff updates automatically as you type or paste.

3. Use the ribbon to stay oriented

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

Top controls

• Wrap: Toggles word wrap in this window.
  Shortcut: ⌥⌘W
• Swap: Swaps the left/right texts (and any file association for each pane).
• Clear: Clears both panes. If either pane has unsaved edits, the trash icon turns orange as a warning.

Pane header (each side)

Each pane has a header row containing:

• Title: either the file name (if opened) or "Text 1" / "Text 2".
• 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.
• Find field: per-pane search with quick clear (×).

The editors + ribbon

• Left editor: Treated as Original
• Right editor: Treated as Modified
• Middle ribbon: connectors between change blocks, plus a progress spinner while the diff is computing.

RibbonDiff highlights changes using configurable colors:

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

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 👑.

Each pane has its own Find field.

Basic use

1. Type a query into the Find field.
2. Matches are highlighted (case-insensitive).
3. Press Return in the Find field to jump to the next match.

Keyboard shortcuts

• Find…: ⌘F (focuses Find for the active pane)
• Find Next: ⌘G
• Find Previous: ⇧⌘G

Active pane rule Find actions apply to whichever side is active:

• If a Find field is focused, that side is active.
• Otherwise, the most recently focused editor pane is active.

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).

Word wrap

• Toggle Wrap in the toolbar (window-local).
• Shortcut: ⌥⌘W

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.

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

"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.

"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.