oyo

A diff viewer that works two ways: step through changes or review a classic scrollable diff.

https://github.com/user-attachments/assets/0f43b54b-69fe-4cf3-9221-a7749872342b

oyo extends traditional diffs with an optional step-through mode. Use it like a normal diff viewer with scrolling and hunk navigation, or step through changes one at a time and watch the code evolve. You can switch between both modes at any time.

Two ways to use oyo

1. Classic diff (scroll-only)

Review all changes at once, scroll freely, and jump between hunks, just like a traditional diff viewer.

• Scroll the full diff
• Jump between hunks
• Vim-style navigation
• No stepping required

Enable with:

• oyo --no-step
• Toggle in-TUI with s
• Set stepping = false in config

2. Step-through review (default)

Apply changes incrementally and watch the file transform from old → new.

• Step change-by-change
• See precise evolution of the code
• Useful for large refactors or careful reviews

oyo does not replace classic diffs, it adds a new way to review them.

Features

• Classic diff mode (no-step) Scroll the full diff with hunk navigation, no stepping required
• Step-through navigation Move through changes one at a time with keyboard shortcuts
• Hunk navigation Jump between groups of related changes in both modes
• Three view modes:
  • Single: Watch the code morph from old to new state
  • Split: See old and new versions with synchronized stepping
  • Evolution: Watch the file evolve, deletions simply disappear
• Word-level diffing: See exactly which words changed within a line
• Multi-file support: Navigate between changed files with preserved positions
• Search: Regex search with to jump between matches
• Syntax highlighting: Toggle on/off for code-aware coloring (auto-enabled in no-step mode)
• Line wrap: Toggle wrapping for long lines
• Animated transitions: Smooth fade in/out animations as changes are applied
• Playback: Automatically step through all changes at a configurable speed
• Git integration: Works as a git external diff tool or standalone
• Commit picker: Browse recent commits and pick ranges interactively (oy view)
• Themes: Built-in themes plus .tmTheme syntax themes (configurable)
• Configurable: XDG config file support for customization

Installation

CLI (Cargo)

cargo install oyo

Usage

Classic diff (scroll-only)

oy --no-step
# or toggle in-app with `s`

Step-through diff

oy

Compare files

oy old.rs new.rs

Commit picker

oy view

View modes

oy old.rs new.rs --view split
oy old.rs new.rs --view evolution

Autoplay

oy old.rs new.rs --autoplay
oy old.rs new.rs --speed 100

Git ranges

oy --range HEAD~1..HEAD
oy --range main...feature

Staged changes

oy --staged

Git Integration

Recommended (git difftool)

git difftool -y --tool=oy

~/.gitconfig:

[difftool "oy"]
    cmd = oy "$LOCAL" "$REMOTE"

[difftool]
    prompt = false

[alias]
    d = difftool -y --tool=oy

Note: keep your pager (less, moar, moor) for git diff. Do not set core.pager or interactive.diffFilter to oy.

Jujutsu (jj)

[ui]
paginate = "never"
diff-formatter = ["oy", "$left", "$right"]

[diff-tools.oy]
command = ["oy", "$left", "$right"]

Keyboard Shortcuts

Vim-style counts: Most navigation commands support count prefixes (e.g., 10j moves 10 steps forward, 5J scrolls down 5 lines).

Clipboard support uses system tools: pbcopy (macOS), wl-copy / xclip / xsel (Linux), clip (Windows). Search is case-insensitive regex; invalid patterns fall back to literal matching.

Configuration

Create a config file at ~/.config/oyo/config.toml:

[ui]
auto_center = true          # Auto-center on active change (default: true)
topbar = true               # Show top bar in diff view (default: true)
view_mode = "single"        # Default: "single", "split", or "evolution"
line_wrap = false           # Wrap long lines (default: false, uses horizontal scroll)
scrollbar = false           # Show scrollbar (default: false)
strikethrough_deletions = false # Show strikethrough on deleted text
gutter_signs = true         # Show +/- sign column (single/evolution)
stepping = true             # Enable stepping (false = no-step mode)
# [ui.diff]
# bg = false                # Full-line diff background (true/false)
# fg = "theme"              # "theme" or "syntax"
# highlight = "text"        # "text" | "word" | "none"
# extent_marker = "neutral" # "neutral" or "diff"
# extent_marker_scope = "progress" # "progress" or "hunk"
# [ui.split]
# align_lines = false       # Insert blanks to keep split panes aligned
# align_fill = "╱"          # Fill character for aligned blanks (empty = no marker)
# [ui.evo]
# syntax = "context"         # "context" (non-diff only) or "full" (diff + context)
# Syntax highlighting:
# - legacy: syntax = "on"    # "on" or "off"
# - table:
#   [ui.syntax]
#   mode = "on"              # "on" or "off"
#   theme = "tokyonight"     # builtin name or "custom.tmTheme" (from ~/.config/oyo/themes)
#                             # default: ui.theme.name, fallback to "ansi"
syntax = "on"
# [ui.single]
# modified_step_mode = "mixed" # "mixed" or "modified" (single-pane only)
# theme = { name = "tokyonight" } # Built-ins listed below
primary_marker = "▶"        # Marker for primary active line (single-width char recommended)
primary_marker_right = "◀"  # Right pane marker (optional, defaults to ◀)
extent_marker = "▌"         # Left pane extent marker (Left Half Block)
extent_marker_right = "▐"   # Right pane extent marker (optional, defaults to ▐)
zen = false                 # Start in zen mode (minimal UI)

[playback]
speed = 200                 # Autoplay interval in milliseconds
autoplay = false            # Start with autoplay enabled
animation = false           # Enable fade animations
animation_duration = 150    # Animation duration per phase (ms)
auto_step_on_enter = true   # Auto-step to first change when entering a file
auto_step_blank_files = true # Auto-step when file would be blank at step 0 (new files)

[files]
panel_visible = true        # Show file panel in multi-file mode
counts = "active"           # Per-file +/- counts: active, focused, all, off

Config is loaded from (in priority order):

1. $XDG_CONFIG_HOME/oyo/config.toml
2. ~/.config/oyo/config.toml
3. Platform-specific (e.g., ~/Library/Application Support/oyo/config.toml on macOS)

Theme and syntax theme configuration is documented in THEME.md.

How It Works

Stepping applies changes in file order. The view renders applied changes, highlights the active change, and keeps pending changes muted.

Development

# Build everything
cargo build

# Run tests
cargo test

# Run CLI in development
cargo run --bin oy -- old.rs new.rs