oyo

A Step-through diff viewer.

https://github.com/user-attachments/assets/dd284411-48cb-4015-b500-0246629c2493

Step through changes or scroll the full diff, jump between hunks, and watch code transform instead of a static before/after.

Features

• Step-through navigation: Move through changes one at a time with keyboard shortcuts
• Hunk navigation: Jump between groups of related changes (hunks) in step or no-step mode
• No-step mode: Review all changes at once with scroll + hunk navigation (scroll-only diff viewer)
• 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 (oyo view)
• Themes: Built-in themes plus .tmTheme syntax themes (configurable)
• Configurable: XDG config file support for customization

Installation

CLI (Cargo)

cargo install oyo

Usage

Optional theme override:

oyo --theme-name tokyonight

CLI

# Diff uncommitted changes in current git repo
oyo

# Compare two files
oyo old.rs new.rs

# Commit picker
oyo view

# Split view
oyo old.rs new.rs --view split

# Evolution view
oyo old.rs new.rs --view evolution

# Autoplay mode
oyo old.rs new.rs --autoplay

# Custom autoplay speed (100ms between steps)
oyo old.rs new.rs --speed 100

# No-step mode
oyo old.rs new.rs --no-step

# Staged changes (index vs HEAD)
oyo --staged

# Git range
oyo --range HEAD~1..HEAD
# or
oyo --range main...feature

Git Integration

oyo supports git external diff (7-arg interface) and git difftool. For most workflows, difftool is smoother; diff.external will open a TUI per file.

# One-off (recommended)
git difftool -y --tool=oyo

Recommended ~/.gitconfig:

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

[difftool]
    prompt = false

[alias]
    d = difftool -y --tool=oyo
    oyo = "!oyo"

External diff setup (optional):

git config --global diff.external oyo

Note: keep your pager (e.g., less, moar, moor) for normal git diff output. Do not set core.pager to oyo. Also avoid interactive.diffFilter — it expects a stdin filter, not a TUI.

Jujutsu (jj)

In ~/.config/jj/config.toml:

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

To use jj diff --tool=oyo:

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

Note: do not set your ui.pager to oyo.

Example range diff:

jj diff -f zy -t w

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)
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
stepping = true             # Enable stepping (false = no-step mode)
# [ui.diff]
# bg = "none"               # "none", "text", or "line"
# fg = "theme"              # "theme" or "syntax"
# [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 oyo -- old.rs new.rs